Skip to main content
Version: 1.1.0

AgentID Data Plane API

Public runtime API for AgentID Data Plane.

Authentication​

Use one of these authentication mechanisms for all endpoints:

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

x-agentid-api-key is the preferred transport for server and SDK integrations.

Key lifecycle guidance:

  • Create keys in System -> Integration in AgentID Dashboard.
  • Prefer environment variables (AGENTID_API_KEY) and secret managers.
  • Rotate keys regularly; revoke immediately on suspicion of compromise.
  • Distinguish environments with separate keys (for example dev, staging, prod).

Error Payloads​

Data-plane endpoints do not currently use one globally standardized error envelope.

Current production behavior is:

  • /api/v1/guard typically returns a flat guard-style payload such as:

    \{
      "allowed": false,
      "reason": "unauthorized"
    \}

  • /api/v1/agent/config, /api/v1/ingest, and /api/v1/ingest/finalize return flat JSON payloads such as:

    \{
      "error": "Unauthorized"
    \}

    or

    \{
      "error": "Invalid payload",
      "details": \{\}
    \}

This reference documents the current live contract rather than an aspirational normalized envelope.

Rate Limiting​

AgentID enforces per-system and platform-level limits.

Typical model:

  • per-second smoothing and per-minute guardrails
  • short burst allowance
  • optional plan-tier overrides

When limited, API returns 429 with:

  • Retry-After
  • X-RateLimit-Limit
  • X-RateLimit-Remaining
  • X-RateLimit-Reset

Retry Guidance​

  • 429: retry with exponential backoff and jitter, respect Retry-After.
  • 503: retry with exponential backoff; treat as transient infra issue.
  • 5xx: retry with capped exponential backoff.
  • /api/v1/ingest: safe to retry only with the same event_id (idempotent key).
  • /api/v1/ingest/finalize: safe to retry with the same client_event_id.

Recommended backoff:

  • attempt 1: 250ms + jitter
  • attempt 2: 500ms + jitter
  • attempt 3: 1000ms + jitter
  • attempt 4: 2000ms + jitter (cap at 5s)

Idempotence (/api/v1/ingest)​

  • event_id is the idempotency key.
  • Duplicate event_id requests are rejected with 409 DUPLICATE_EVENT_ID.
  • Reuse the exact same event_id on network retries to avoid duplicate telemetry writes.

Full Integration Example (Lifecycle)​

User Input -> /api/v1/agent/config -> capability/config lookup
                         -> /api/v1/guard -> allow/block verdict
                         -> (if allowed) LLM provider call
                         -> /api/v1/ingest (same event correlation)
                         -> /api/v1/ingest/finalize (sdk_ingest_ms on same lifecycle row)

Node.js (pseudo):

const guard = await fetch("https://app.getagentid.com/api/v1/guard", { ... });
if (!guard.allowed) throw new Error("blocked");
const llm = await callModel();
await fetch("https://app.getagentid.com/api/v1/ingest", { event_id, input, output: llm.output, ... });

Python (pseudo):

guard = requests.post("https://app.getagentid.com/api/v1/guard", json=payload, headers=headers).json()
if not guard["allowed"]:
    raise Exception("blocked")
llm_output = run_model()
requests.post("https://app.getagentid.com/api/v1/ingest", json={...}, headers=headers)
requests.post("https://app.getagentid.com/api/v1/ingest/finalize", json={...}, headers=headers)

Direct C# / Java Integration Guide​

If your team is integrating AgentID from C#, Java, Spring Boot, or ASP.NET without an official SDK, use the dedicated guide:

That guide covers:

  • where to place the integration in your application architecture
  • what you must implement yourself without an SDK
  • how to handle client_event_id, guard_event_id, and event_id
  • how to apply transformed_input
  • pseudo-code for both C# and Java

SDK Wrapper Semantics​

Official JS and Python SDKs default to backend-first enforcement.

  • /guard is authoritative for prompt injection, DB access, code execution, and PII leakage.
  • clientFastFail / client_fast_fail opt in to local preflight before the backend call.
  • If backend guard is unreachable and effective failure mode is fail_close, wrapped SDK flows may apply local fallback enforcement before the final execution decision.

Production Readiness​

  • Guard timeout target: ~2s (common production default).
  • Choose fail-open vs fail-closed according to system risk class.
  • Log request_id, client_event_id, guard_event_id, event_id.
  • Monitor 429, 503, policy blocks, latency percentiles, and ingest write success ratio.
  • Keep key rotation and revoke workflows operationally tested.
  • SDK wrappers may emit sdk_config_fetch_ms, sdk_local_scan_ms, sdk_guard_ms, and then finalize sdk_ingest_ms after the primary ingest write.

Versioning Policy​

  • Endpoint namespace versioning uses /api/v1/....
  • Breaking changes ship in new major path versions (/api/v2/...).
  • Non-breaking additions may appear in current major (v1) with backward compatibility.
  • Deprecations are announced ahead of breaking rollout with migration guidance.

Authentication​

AgentID API key used for Data Plane authentication. Example: x-agentid-api-key: sk_live_...

Security Scheme Type:

apiKey

Header parameter name:

x-agentid-api-key