Skip to main content
The Agent Sentinel Platform API is a cloud service that:
  • Accepts SDK telemetry uploads (POST /api/v1/ingest/)
  • Stores runs and actions securely in the cloud
  • Provides APIs for querying runs/actions, managing policies, and viewing analytics
  • Powers the web console with real-time WebSocket updates
Base URL: the examples in this reference use $AGENT_SENTINEL_URL for your platform API base URL (and AGENT_SENTINEL_HOST for its host name in WebSocket URLs). Set it once in your shell:
The Python SDK and agentsentinel-mcp already default to the hosted platform, so you only need this for direct REST calls.

Key endpoints

  • Auth
    • POST /api/v1/login/access-token
  • API keys (recommended for agents)
    • POST /api/v1/api-keys/
  • Ingest
    • POST /api/v1/ingest/
  • Runs/actions
    • GET /api/v1/runs/
    • GET /api/v1/runs/{run_id}
    • GET /api/v1/runs/{run_id}/actions
  • Activity Ledger (audit trail)
    • GET /api/v1/ledger/
    • GET /api/v1/ledger/stats
    • GET /api/v1/ledger/export
  • Policies
    • GET /api/v1/policies/
    • GET /api/v1/policies/sync
  • Stats
    • GET /api/v1/stats/
    • GET /api/v1/stats/daily
  • Replay (analysis/simulation)
    • POST /api/v1/replay/{run_id}
    • GET /api/v1/replay/analysis/{run_id}
  • Gateway (tool-call authorization)
    • POST /api/v1/gateway/authorize
    • POST /api/v1/gateway/approvals/{approval_id}/redeem

Gateway authorize

Call POST /api/v1/gateway/authorize before an agent runs a tool call:
One call checks the caller’s identity and kill switches, gets the policy decision, and reserves budget for an allowed action. It writes a chained, signed ledger row of type decision for every call, including denials. The response is {decision, reason_code, reservation_id, approval_request_id, decision_token, expires_at}.
  • allow / deny. The response carries a decision_token. This is an Ed25519-signed compact JWS (alg: EdDSA) over {org, agent, action, inputs_digest, decision, exp}, made with the platform signing key. It is valid for 5 minutes. An executor must present it before running the action. allow also returns the reservation_id holding estimated_cost_usd; pass it to ingest so the hold is reconciled.
  • require_approval. No token yet. The gateway creates an approval request, and notifies approvers the same way POST /api/v1/approvals does. It returns the request’s approval_request_id. Poll GET /api/v1/approvals/{approval_id}/poll. Once it is approved, call POST /api/v1/gateway/approvals/{approval_id}/redeem to get the token. Redemption re-checks identity, kill switches and policy for the original request, so it can still return a deny token. Each approval redeems once. A failed redemption can be retried.
Only approvals the gateway created can be redeemed. An approval created directly through POST /api/v1/approvals cannot. estimated_cost_usd must be finite and non-negative. If no signing key is configured, the endpoint returns 503. If a decision row’s signature does not verify, the request fails with no token.

Identity

Both gateway endpoints require an API key bound to an agent. A user session or an unbound key gets 403 with {"detail": {"reason_code": "agent_bound_key_required", …}}. The organization and agent are always the key’s own. The X-Sentinel-Agent-Id header is ignored on the gateway, and the token’s agent claim is always the key’s agent. A request is also rejected if the key’s organization differs from its owner’s active organization.

Kill-switch scope

The agent kill switch, enforced through the bound key, is the authoritative stop: it applies to every request the key makes. Run and mission kill switches apply when the executor reports its run_id. A request without one, or with an unknown one, is recorded under a fresh run with no mission. A supplied run_id must belong to the key’s agent and organization. A run belonging to another organization, another agent, or no agent gets 403.

Authentication

All API requests require authentication via:
  • API keys (recommended for SDK integration) - Generated in the web console
  • JWT tokens (for web console access) - Automatic via Clerk authentication
See Authentication for details.

Getting started

  1. Sign up at console.agentsentinel.dev
  2. Generate an API key in Settings → API Keys
  3. Use the key in your SDK:

OpenAPI specification

Use this platform section as the API reference entry point.