Get Workspace Diff

GEThttps://agent.blackbox.ai/api/v1/tasks/{runId}/files/diff

Get the cumulative git diff of all changes made by the agent in the sandbox workspace.

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

Your API key will be in the format: sk-xxxxxxxxxxxxxxxxxxxxxx

Headers

Authorizationstringrequired

API Key of the form Bearer <api_key>.

Example: Bearer sk_b41b647ffbfed27f616560

Path Parameters

runIdstringrequired

The unique run identifier returned when the task was created.

Query Parameters

pathstringdefault: /vercel/sandbox

Workspace path to diff.

Default: /vercel/sandbox

basestringdefault: 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

Example: base=initial

Response Fields

diffstring

Unified diff output. Empty string if no changes.

pathstring

The workspace path that was diffed.

hasGitboolean

Whether the workspace is a git repository.

basestring | null

The git ref used as the diff base. null for non-git workspaces.

Request Example

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"])

Response Example

{
  "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+

  "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