AgentID Data Plane API

Endpoints

Base URL and authentication

All endpoints are served from https://app.getagentid.com. Download the machine-readable spec: openapi.yaml.

Public runtime API for the AgentID data plane.

Authentication

Send the AI system's API key with every request:

• Header: x-agentid-api-key: sk_live_... (preferred)
• Header: Authorization: Bearer sk_live_...

When both headers are present, x-agentid-api-key wins. Each key belongs to exactly one AI system; a system_id in the request must match that system.

Key lifecycle:

• Create keys in AI system → Integration in the AgentID dashboard. The full key is shown once; AgentID stores only a hash and the prefix.
• Keep keys in environment variables (AGENTID_API_KEY) or a secret manager.
• Use separate keys per environment (prod, staging, dev) and revoke a key immediately when it may be exposed.

Error payloads

Endpoints do not share one error envelope:

• /api/v1/guard always answers with a verdict object, for example { "allowed": false, "reason": "unauthorized" }.
• /api/v1/agent/config, /api/v1/ingest and /api/v1/ingest/finalize answer errors with { "error": "...", "reason": "...", "details": {...} } where reason and details are optional.

Rate limiting

Limits apply per AI system (requests per minute, optional daily request cap, optional hourly and daily token caps, and a short burst limit). A limited request returns 429 with:

• Retry-After (seconds)
• X-RateLimit-Limit
• X-RateLimit-Remaining

Retry guidance

• 429: wait for Retry-After, then retry with exponential backoff and jitter.
• 503 and other 5xx: retry with capped exponential backoff (for example 250 ms, 500 ms, 1 s, 2 s; cap at 5 s).
• /api/v1/ingest: retry only with the same event_id.
• /api/v1/ingest/finalize: safe to retry with the same client_event_id.

Correlation and diagnostics headers

• Send x-correlation-id to correlate a request; AgentID echoes it (or a generated value) in the response.
• X-AgentID-Latency reports server processing time in milliseconds.
• A Guard response produced without a full check because a dependency failed in fail-open mode carries X-AgentID-Status: BYPASSED_INFRA_ERROR.

Lifecycle

user input -> /api/v1/guard          -> verdict (allow / mask / block)
           -> (if allowed) model call with transformed_input
           -> /api/v1/ingest          -> completion event (same client_event_id)
           -> /api/v1/ingest/finalize -> optional SDK timing on the same event

/ingest should include provider usage or normalized tokens. Cost and ROI charts are computed from completion events with a model id and token counts.

Versioning

• Paths are versioned under /api/v1/....
• Breaking changes ship under a new major path (/api/v2/...).
• Fields may be added to v1 responses; clients must ignore unknown fields.