All endpoints live under https://agentblackbox.si. Requests and answers are JSON.
Send your API key in the x-agentblackbox-key header. Keys belong to one workspace. Actions that can execute need a key bound to an agent (403 AGENT_BOUND_KEY_REQUIRED otherwise). Every answer carries an x-request-id; quote it when you contact support.
| Endpoint | Body | What it does |
|---|---|---|
POST /api/intercept | { workUnitId, tool, actionCategory, riskLevel?, amount?, externalRecipient?, payload? } | Decides on an action your agent will take itself. Executes nothing. |
POST /api/connector-actions | { connectionId, tool, workUnitId, payload, … } | Decides, and if allowed acts in a connected app: gmail.send, slack.postMessage, github.comment, drive.share, notion.append. |
POST /api/tool-actions | { workUnitId, tool | governedToolId, payload, … } | Decides, and if allowed calls one of your registered HTTP or MCP tools. |
actionCategory is one of READ_DATA, SEND_MESSAGE, MONEY, DELETE, EXTERNAL_SHARE, UPDATE_RECORD. riskLevel is LOW, MEDIUM, HIGH or CRITICAL. AgentBlackBox never lets a declared category or risk go below what it already knows about the tool and the work unit.
| Decision | What your agent must do |
|---|---|
ALLOW | Go ahead as asked. This is the only answer that means that. |
MODIFY | Go ahead only with transformedAction from the answer. |
REDACT | Go ahead only with transformedAction, in which sensitive values are removed. |
REQUIRE_APPROVAL | Wait for a person: poll GET /api/approvals/{approvalId} until it is APPROVED, DENIED or EXPIRED. Only APPROVED means go ahead. |
DENY | Stop. In enforce mode the HTTP status is 403. |
Modes: with protection off the intercept answer is ALLOW and nothing is recorded, and the connector and tool gateways answer 409 GOVERNANCE_OFF. In shadow (watch-only) mode decisions are recorded and returned, but nothing is blocked. In enforce mode they apply.
| Endpoint | Use |
|---|---|
POST /api/events | Record what happened: { workUnitId, type, title, summary?, riskLevel?, payload? }. type is OBSERVATION, DECISION, TOOL_CALL, ACTION_EXECUTED, ACTION_BLOCKED or ERROR. |
POST /api/policy/evaluate | Ask what your rules would decide, without recording an action: ALLOW, MODIFY, REDACT, REQUIRE_APPROVAL or BLOCK. |
POST /api/approvals | Ask a person to approve: { workUnitId, reason?, actionCategory?, riskLevel?, amount?, externalRecipient? }. |
GET /api/approvals/{id} | An approval's status: PENDING, APPROVED, DENIED, or EXPIRED when nobody decided within 72 hours (expiresAt says when). |
| Endpoint | Limit per key, per minute |
|---|---|
| /api/intercept | 120 |
| /api/tool-actions | 60 |
| /api/connector-actions | 60 |
| /api/events | 120 |
| /api/policy/evaluate | 120 |
| /api/approvals | 30 |
Over the limit, the answer is 429 RATE_LIMITED with Retry-After in seconds. If a gateway cannot check its limit, it answers 503 RATE_LIMIT_UNAVAILABLE with Retry-After: 5 and runs nothing. In both cases, wait and try again.
Errors look like { "error": "…", "code": "…" }. The most common:
| Status | code | Meaning |
|---|---|---|
| 401 | MISSING_API_KEY / INVALID_API_KEY / API_KEY_EXPIRED | No key, an unknown or revoked key, or an expired key |
| 400 | VALIDATION_FAILED | The body does not match; see issues |
| 400 | UNKNOWN_ACTION_CATEGORY / CATEGORY_NOT_ALLOWED | Unknown category, or lower than the tool's |
| 403 | AGENT_BOUND_KEY_REQUIRED | Actions that can execute need a key bound to an agent |
| 404 | WORKUNIT_NOT_FOUND / CONNECTION_NOT_FOUND / TOOL_NOT_FOUND | Unknown, or in another workspace |
| 409 | GOVERNANCE_OFF | Switch on watch-only or enforce mode first |
| 409 | TOOL_NOT_ENABLED / CONNECTOR_NOT_WRITE_ENABLED | Enable the tool, or reconnect the app with write access |
| 429 / 503 | RATE_LIMITED / RATE_LIMIT_UNAVAILABLE | Wait for Retry-After, then try again |
const res = await fetch("https://agentblackbox.si/api/intercept", {
method: "POST",
headers: { "x-agentblackbox-key": process.env.ABB_KEY, "content-type": "application/json" },
body: JSON.stringify({ workUnitId, tool: "gmail.send", actionCategory: "SEND_MESSAGE", riskLevel: "MEDIUM" }),
});
const answer = await res.json();
if (answer.decision !== "ALLOW") { /* ask a person, use transformedAction, or stop */ }