Continue Task

POSThttps://agent.blackbox.ai/api/v1/tasks/{runId}/continue

Send a follow-up prompt to an existing task, creating a new agent run on the same chat thread with full conversation history.

This endpoint continues an existing task by spawning a new agent run on the same chat thread (chatId). The agent receives the full conversation history as context and picks up where the previous run left off. If the original task worked on a GitHub repository, the agent will continue from the branch it created.

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

GitHub Connection Required

For GitHub-related tasks: If the original task worked on a repository, the agent will automatically continue from the branch it created. Make sure your GitHub token is still stored via POST /api/v1/git/config — see Store GitHub Token for details.

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Content-Typestringrequired

Must be set to application/json.

Path Parameters

runIdstringrequired

The runId of the previous task run to continue from.

Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890

Request Body

promptstringrequired

The follow-up instruction for the agent. The agent will receive the full prior conversation as context.

Examples:

  • "Now add unit tests for the new module"
  • "The webhook handler is missing error handling, please fix it"
  • "Summarize what was done so far"
modelstring

Override the model for this follow-up run. If you set model, you must also set agent (see the inheritance rule below). Omit both to keep the original run's model.

Example: "blackboxai/anthropic/claude-opus-4.7" — see Models for all available IDs.

agentstring

Explicit agent runtime for this turn — "claude" or "codex". Required whenever you change model (or otherwise override the runtime). Omit — together with model — to inherit the original run's runtime.

Runtime inheritance rule. Continuation is designed so a plain follow-up "just continues" on the same setup:

  • Neither model nor agent specified → the follow-up inherits the original run's model and agent runtime (even an explicit codex+opus override is preserved).
  • model and/or agent specified → you are overriding, so agent is required. This prevents a model swap from silently flipping the runtime. Omitting agent while setting model returns 400.

Example — continue on Codex with an Opus model: { "prompt": "...", "model": "blackboxai/anthropic/claude-opus-4.7", "agent": "codex" }.

Response Fields

runIdstring

Unique identifier for the new agent run. Use this to poll status or stream logs.

assistantMessageIdstring

ID of the assistant message being generated for this follow-up.

chatIdstring

UUID of the shared chat thread (same as the original task's chatId).

previousRunIdstring

The runId of the task that was continued (the path parameter).

How Continuation Works

  1. Context restored — The agent loads the full message history from the shared chatId
  2. GitHub context restored — If the original task had a repo, the agent continues from the branch it created (githubCreatedBranch)
  3. New run created — A fresh agent run is spawned with the follow-up prompt appended to the conversation
  4. New runId returned — Use the new runId to track this follow-up independently
Request Example
curl -X POST 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/continue' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Now add unit tests for the new payment module"
  }'
curl -X POST 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/continue' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "prompt": "Refactor the authentication logic to use middleware",
    "model": "blackboxai/anthropic/claude-opus-4.7"
  }'
const API_KEY = "YOUR_API_KEY";
const PREVIOUS_RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";

const response = await fetch(
  `https://agent.blackbox.ai/api/v1/tasks/${PREVIOUS_RUN_ID}/continue`,
  {
    method: "POST",
    headers: {
      Authorization: `Bearer ${API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      prompt: "Now add unit tests for the new payment module",
    }),
  }
);

const data = await response.json();
console.log(`New runId: ${data.runId}`);
console.log(`ChatId: ${data.chatId}`);

// Poll the new run for completion
const DONE = ["completed", "failed", "cancelled", "interrupted"];
while (true) {
  const statusRes = await fetch(
    `https://agent.blackbox.ai/api/v1/tasks/${data.runId}/status`,
    { headers: { Authorization: `Bearer ${API_KEY}` } }
  );
  const s = await statusRes.json();
  console.log(`${s.status} — ${s.progress}%`);
  if (DONE.includes(s.status)) break;
  await new Promise(r => setTimeout(r, 3000));
}
import requests
import time

API_KEY = "YOUR_API_KEY"
PREVIOUS_RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"

headers = {
    "Authorization": f"Bearer {API_KEY}",
    "Content-Type": "application/json",
}


response = requests.post(
    f"https://agent.blackbox.ai/api/v1/tasks/{PREVIOUS_RUN_ID}/continue",
    headers=headers,
    json={"prompt": "Now add unit tests for the new payment module"},
)
data = response.json()
new_run_id = data["runId"]
print(f"New runId: {new_run_id}")

# Poll until done
DONE = {"completed", "failed", "cancelled", "interrupted"}
while True:
    s = requests.get(
        f"https://agent.blackbox.ai/api/v1/tasks/{new_run_id}/status",
        headers={"Authorization": f"Bearer {API_KEY}"},
    ).json()
    print(f"{s['status']}{s['progress']}%")
    if s["status"] in DONE:
        break
    time.sleep(3)
package main

import (
    "bytes"
    "encoding/json"
    "fmt"
    "io"
    "net/http"
)

func main() {
    apiKey := "YOUR_API_KEY"
    previousRunId := "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
    url := fmt.Sprintf("https://agent.blackbox.ai/api/v1/tasks/%s/continue", previousRunId)

    body, _ := json.Marshal(map[string]string{
        "prompt": "Now add unit tests for the new payment module",
    })

    req, _ := http.NewRequest("POST", url, bytes.NewBuffer(body))
    req.Header.Set("Authorization", "Bearer "+apiKey)
    req.Header.Set("Content-Type", "application/json")

    client := &http.Client{}
    resp, _ := client.Do(req)
    defer resp.Body.Close()

    respBody, _ := io.ReadAll(resp.Body)
    fmt.Println(string(respBody))
}
Response Example
{
  "runId": "c3d4e5f6-a7b8-9012-cdef-123456789012",
  "assistantMessageId": "msg_new_run_abc123",
  "chatId": "chat_def789ghi012",
  "previousRunId": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
}
{
  "error": "Task not found"
}
{
  "error": "prompt: prompt is required"
}
{
  "error": "Claude Agent requires a Pro subscription. Please upgrade at https://www.blackbox.ai/pricing"
}

Error Codes

Status Code Error Description
200 Success Follow-up run started successfully
400 Bad Request Missing prompt or invalid JSON
401 Unauthorized Invalid or missing API key
403 Forbidden Pro subscription required, task belongs to another user, or no API key configured
404 Not Found Previous task not found
500 Internal Server Error Failed to spawn agent