Skip to main content
PATCH
/
api
/
v1
/
tasks
/
{runId}
curl -X PATCH 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "cancel" }'
{
  "success": true,
  "status": "cancelled",
  "message": "Task a1b2c3d4-e5f6-7890-abcd-ef1234567890 cancelled successfully"
}
This endpoint allows you to cancel a running task or rename its chat title. When cancelling, the agent process is terminated and the run status is updated to cancelled.

Authentication

To use this API, you need a BLACKBOX API Key. Follow these steps to get your API key:
  1. Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
  2. Once provisioning completes, you will be redirected to your Dashboard
  3. From the Dashboard, create an API key to use with all Agent API requests
Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

Headers

Authorization
string
required
API Key of the form Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560
Content-Type
string
required
Must be set to application/json.

Path Parameters

runId
string
required
The unique run identifier of the task to cancel or update.Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Request Body

action
string
Action to perform. Use "cancel" to stop the running task.Must be "cancel" when provided.
title
string
New title for the task’s chat thread. Length: 1–200 characters.Example: "Stripe Integration Task"
You must provide either action: "cancel" or a title. Providing both is allowed — the cancel takes precedence.

Response Fields

success
boolean
Whether the operation succeeded.
status
string
The current status of the run after the operation.
message
string
Human-readable description of the result.
curl -X PATCH 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{ "action": "cancel" }'
{
  "success": true,
  "status": "cancelled",
  "message": "Task a1b2c3d4-e5f6-7890-abcd-ef1234567890 cancelled successfully"
}

Use Cases

Cancel with Timeout Guard

async function runWithTimeout(runId, apiKey, timeoutMs = 300_000) {
  const statusUrl = `https://agent.blackbox.ai/api/v1/tasks/${runId}/status`;
  const cancelUrl = `https://agent.blackbox.ai/api/v1/tasks/${runId}`;
  const DONE = ["completed", "failed", "cancelled", "interrupted"];
  const headers = { Authorization: `Bearer ${apiKey}` };

  const deadline = Date.now() + timeoutMs;

  while (Date.now() < deadline) {
    const res = await fetch(statusUrl, { headers });
    const s = await res.json();
    if (DONE.includes(s.status)) return s;
    await new Promise(r => setTimeout(r, 3000));
  }

  // Timeout — cancel the task
  await fetch(cancelUrl, {
    method: "PATCH",
    headers: { ...headers, "Content-Type": "application/json" },
    body: JSON.stringify({ action: "cancel" }),
  });

  throw new Error("Task cancelled due to timeout");
}

Cancel Multiple Tasks

async function cancelAll(runIds, apiKey) {
  return Promise.allSettled(
    runIds.map(id =>
      fetch(`https://agent.blackbox.ai/api/v1/tasks/${id}`, {
        method: "PATCH",
        headers: {
          Authorization: `Bearer ${apiKey}`,
          "Content-Type": "application/json",
        },
        body: JSON.stringify({ action: "cancel" }),
      }).then(r => r.json())
    )
  );
}

Error Codes

Status CodeErrorDescription
200SuccessOperation completed successfully
400Bad RequestInvalid JSON or no valid action provided
401UnauthorizedInvalid or missing API key
403ForbiddenTask belongs to a different user
404Not FoundTask not found
500Internal Server ErrorServer error