Continue Task
https://agent.blackbox.ai/api/v1/tasks/{runId}/continueSend 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:
- Go to app.blackbox.ai/agent-api and click Get an API Key (requires a Pro subscription)
- Once provisioning completes, you will be redirected to your Dashboard
- 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
AuthorizationstringrequiredAPI Key of the form Bearer <api_key>.
Example: Bearer sk_b41b647ffbfed27f616560
Content-TypestringrequiredMust be set to application/json.
Path Parameters
runIdstringrequiredThe runId of the previous task run to continue from.
Example: a1b2c3d4-e5f6-7890-abcd-ef1234567890
Request Body
promptstringrequiredThe 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"
modelstringOverride 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.
agentstringExplicit 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
modelnoragentspecified → the follow-up inherits the original run's model and agent runtime (even an explicit codex+opus override is preserved). modeland/oragentspecified → you are overriding, soagentis required. This prevents a model swap from silently flipping the runtime. Omittingagentwhile settingmodelreturns400.
Example — continue on Codex with an Opus model: { "prompt": "...", "model": "blackboxai/anthropic/claude-opus-4.7", "agent": "codex" }.
Response Fields
runIdstringUnique identifier for the new agent run. Use this to poll status or stream logs.
assistantMessageIdstringID of the assistant message being generated for this follow-up.
chatIdstringUUID of the shared chat thread (same as the original task's chatId).
previousRunIdstringThe runId of the task that was continued (the path parameter).
How Continuation Works
- Context restored — The agent loads the full message history from the shared
chatId - GitHub context restored — If the original task had a repo, the agent continues from the branch it created (
githubCreatedBranch) - New run created — A fresh agent run is spawned with the follow-up prompt appended to the conversation
- New
runIdreturned — Use the newrunIdto track this follow-up independently
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))
}{
"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 |