ABAgentBlackBoxv2.0
ProductDocsPricingSecurityPilot program
Sign inGet started
ProductDocsPricingSecurityPilot programSign in
  • Overview
  • Quickstart
  • API reference
  • Integrations
  • Help center

API reference

All endpoints live under https://agentblackbox.si. Requests and answers are JSON.

Authentication

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.

Action gateways

EndpointBodyWhat 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.

Decisions

DecisionWhat your agent must do
ALLOWGo ahead as asked. This is the only answer that means that.
MODIFYGo ahead only with transformedAction from the answer.
REDACTGo ahead only with transformedAction, in which sensitive values are removed.
REQUIRE_APPROVALWait for a person: poll GET /api/approvals/{approvalId} until it is APPROVED, DENIED or EXPIRED. Only APPROVED means go ahead.
DENYStop. 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.

Other endpoints

EndpointUse
POST /api/eventsRecord what happened: { workUnitId, type, title, summary?, riskLevel?, payload? }. type is OBSERVATION, DECISION, TOOL_CALL, ACTION_EXECUTED, ACTION_BLOCKED or ERROR.
POST /api/policy/evaluateAsk what your rules would decide, without recording an action: ALLOW, MODIFY, REDACT, REQUIRE_APPROVAL or BLOCK.
POST /api/approvalsAsk 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).

Rate limits

EndpointLimit per key, per minute
/api/intercept120
/api/tool-actions60
/api/connector-actions60
/api/events120
/api/policy/evaluate120
/api/approvals30

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

Errors look like { "error": "…", "code": "…" }. The most common:

StatuscodeMeaning
401MISSING_API_KEY / INVALID_API_KEY / API_KEY_EXPIREDNo key, an unknown or revoked key, or an expired key
400VALIDATION_FAILEDThe body does not match; see issues
400UNKNOWN_ACTION_CATEGORY / CATEGORY_NOT_ALLOWEDUnknown category, or lower than the tool's
403AGENT_BOUND_KEY_REQUIREDActions that can execute need a key bound to an agent
404WORKUNIT_NOT_FOUND / CONNECTION_NOT_FOUND / TOOL_NOT_FOUNDUnknown, or in another workspace
409GOVERNANCE_OFFSwitch on watch-only or enforce mode first
409TOOL_NOT_ENABLED / CONNECTOR_NOT_WRITE_ENABLEDEnable the tool, or reconnect the app with write access
429 / 503RATE_LIMITED / RATE_LIMIT_UNAVAILABLEWait for Retry-After, then try again

From Node.js

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 */ }

AgentBlackBox

AgentBlackBox checks what your AI agents try to do against your rules, asks a person before risky actions, and keeps a tamper-evident record of what happened.

AgentBlackBox sees and controls only what your agents send through it or through tools you connect. It does not monitor other AI tools.

Product

  • Overview
  • Product
  • Product tour
  • Pilot program
  • Pricing
  • Documentation

Trust

  • Security
  • Report a vulnerability
  • Privacy
  • Terms
  • Subprocessors

Help

  • Help center
  • Support
  • Contact

© 2026 AgentBlackBox. All rights reserved.