curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/diff' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/diff?base=initial' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/diff?base=initial`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(`Has git: ${data.hasGit}`);
console.log(data.diff);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/diff",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"base": "initial"},
)
data = response.json()
print(f"Has git: {data['hasGit']}")
print(data["diff"])
{
"diff": "diff --git a/README.fr.md b/README.fr.md\nnew file mode 100644\nindex 0000000..a1b2c3d\n--- /dev/null\n+++ b/README.fr.md\n@@ -0,0 +1,10 @@\n+# Bienvenue\n+\n+Ceci est le README en français.\n+\n+## Installation\n+\n+```bash\n+npm install\n+```\n",
"path": "/vercel/sandbox",
"hasGit": true,
"base": "initial"
}
{
"diff": "",
"path": "/vercel/sandbox",
"hasGit": true,
"base": "HEAD"
}
{
"error": "No sandbox available for this task"
}
File Management
Get Workspace Diff
Get the cumulative git diff of all changes made by the agent in the sandbox workspace.
GET
/
api
/
v1
/
tasks
/
{runId}
/
files
/
diff
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/diff' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/diff?base=initial' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/diff?base=initial`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(`Has git: ${data.hasGit}`);
console.log(data.diff);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/diff",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"base": "initial"},
)
data = response.json()
print(f"Has git: {data['hasGit']}")
print(data["diff"])
{
"diff": "diff --git a/README.fr.md b/README.fr.md\nnew file mode 100644\nindex 0000000..a1b2c3d\n--- /dev/null\n+++ b/README.fr.md\n@@ -0,0 +1,10 @@\n+# Bienvenue\n+\n+Ceci est le README en français.\n+\n+## Installation\n+\n+```bash\n+npm install\n+```\n",
"path": "/vercel/sandbox",
"hasGit": true,
"base": "initial"
}
{
"diff": "",
"path": "/vercel/sandbox",
"hasGit": true,
"base": "HEAD"
}
{
"error": "No sandbox available for this task"
}
This endpoint returns a unified git diff of all changes made by the agent in the sandbox workspace. If the workspace is a git repository, it produces a proper
git diff output. For non-git workspaces, it falls back to a pseudo-diff listing all file contents.
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
sk-xxxxxxxxxxxxxxxxxxxxxx
Headers
string
required
API Key of the form
Bearer <api_key>.Example: Bearer sk_b41b647ffbfed27f616560Path Parameters
string
required
The unique run identifier returned when the task was created.
Query Parameters
string
default:"/vercel/sandbox"
Workspace path to diff.Default:
/vercel/sandboxstring
default:"HEAD"
Git ref to diff against.
"HEAD"— diff staged + unstaged changes against HEAD (default)"initial"— diff from the very first commit to current working tree
base=initialResponse Fields
string
Unified diff output. Empty string if no changes.
string
The workspace path that was diffed.
boolean
Whether the workspace is a git repository.
string | null
The git ref used as the diff base.
null for non-git workspaces.curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/diff' \
-H 'Authorization: Bearer YOUR_API_KEY'
curl 'https://agent.blackbox.ai/api/v1/tasks/a1b2c3d4-e5f6-7890-abcd-ef1234567890/files/diff?base=initial' \
-H 'Authorization: Bearer YOUR_API_KEY'
const API_KEY = "YOUR_API_KEY";
const RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890";
const response = await fetch(
`https://agent.blackbox.ai/api/v1/tasks/${RUN_ID}/files/diff?base=initial`,
{ headers: { Authorization: `Bearer ${API_KEY}` } }
);
const data = await response.json();
console.log(`Has git: ${data.hasGit}`);
console.log(data.diff);
import requests
API_KEY = "YOUR_API_KEY"
RUN_ID = "a1b2c3d4-e5f6-7890-abcd-ef1234567890"
response = requests.get(
f"https://agent.blackbox.ai/api/v1/tasks/{RUN_ID}/files/diff",
headers={"Authorization": f"Bearer {API_KEY}"},
params={"base": "initial"},
)
data = response.json()
print(f"Has git: {data['hasGit']}")
print(data["diff"])
{
"diff": "diff --git a/README.fr.md b/README.fr.md\nnew file mode 100644\nindex 0000000..a1b2c3d\n--- /dev/null\n+++ b/README.fr.md\n@@ -0,0 +1,10 @@\n+# Bienvenue\n+\n+Ceci est le README en français.\n+\n+## Installation\n+\n+```bash\n+npm install\n+```\n",
"path": "/vercel/sandbox",
"hasGit": true,
"base": "initial"
}
{
"diff": "",
"path": "/vercel/sandbox",
"hasGit": true,
"base": "HEAD"
}
{
"error": "No sandbox available for this task"
}
Error Codes
| Status Code | Error | Description |
|---|---|---|
| 200 | Success | Diff returned |
| 401 | Unauthorized | Invalid or missing API key |
| 403 | Forbidden | Task belongs to a different user |
| 404 | Not Found | Task not found or no sandbox available |
| 500 | Internal Server Error | Failed to get diff |