Skip to content

api-reference.mdx

Latest commit

 

History

History
130 lines (96 loc) · 5.11 KB

api-reference.mdx

File metadata and controls

130 lines (96 loc) · 5.11 KB
title API Reference
description Raw HTTP reference for the AgentRoot proxy.

This page covers the raw HTTP endpoints exposed by the AgentRoot proxy and dashboard API. Two AgentRoot headers, your usual HTTP client, and the upstream path you'd already use — that's the entire integration surface.

The proxy contract is the same as documented in Providers → Conventions. This page is a leaner summary aimed at HTTP-only consumers; if anything here is ambiguous, the Conventions page is authoritative.

Proxy endpoint

<METHOD> https://proxy.agentroot.app/<provider>/<upstream-path>

Where <provider> is the lowercase provider slug (see the Providers catalog for all 54), and <upstream-path> is the exact path the provider's own API documents. Path parameters, query strings, and request bodies all pass through to the upstream unchanged.

Required headers

Header Value
Authorization Bearer <session_token> — your agent's AgentRoot session token, not the upstream key
X-AgentRoot-ID Your agent's EAS attestation UID
Content-Type Usually application/json; whatever the upstream expects

The upstream's own auth header (OpenAI's Authorization: Bearer sk-..., Stripe's Authorization: Bearer sk_live_..., Anthropic's x-api-key) is not sent by your code. The proxy injects it from the vault.

Optional headers

Header Use
X-AgentRoot-Idempotency-Key UUID for replay-safe retries on Writes and Transactions
X-AgentRoot-Class-Override Override the route's standing action class for this call only (tightening only)

Response headers

Header Meaning
X-AgentRoot-Class The action class this call was classified into
X-AgentRoot-Cost-USD Estimated upstream cost (when known)
X-AgentRoot-Latency-MS Proxy + upstream round-trip time
X-AgentRoot-Request-ID Correlation ID — quote in support tickets

Example

curl -X POST https://proxy.agentroot.app/openai/v1/chat/completions \
  -H "Authorization: Bearer art_live_xxxxxxxxxxxx" \
  -H "X-AgentRoot-ID: 0x7a3f..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "Hello"}]
  }'

Error codes

HTTP Code Tier Retryable Meaning
401 TOKEN_EXPIRED — after refresh Session token TTL elapsed
401 TOKEN_REVOKED — no Operator revoked the token
401 TOKEN_INVALID — no Malformed or unrecognized token
403 AGENT_KILLED 2 no Whole agent paused
403 PROVIDER_DISABLED 1 no This binding off
403 ATTESTATION_REVOKED 3 no Onchain kill, permanent
403 CLASS_DENIED — no Per-class threshold or deny-by-default (Destruction)
429 RATE_LIMITED auto after retryAfter Auto-kill threshold breached
502 UPSTREAM_ERROR — depends Upstream returned an error
503 VAULT_UNAVAILABLE — after recovery Vault unreachable; fail-closed
504 UPSTREAM_TIMEOUT — yes Upstream exceeded timeout window

Error body shape:

{
  "error": {
    "code": "AGENT_KILLED",
    "message": "Agent has been paused by operator",
    "tier": 2,
    "retryable": false,
    "requestId": "req_01HZ..."
  }
}

Health check

curl https://proxy.agentroot.app/health \
  -H "Authorization: Bearer art_live_xxxxxxxxxxxx" \
  -H "X-AgentRoot-ID: 0x7a3f..."

Returns:

{
  "proxy": "ok",
  "token": "valid",
  "vault": "ok",
  "ttl_seconds": 72400
}

The ttl_seconds value is the remaining lifetime of your session token. If it's under 600 seconds, refresh from the dashboard or rotate the agent before the token expires.

Authentication tokens

Format: art_live_xxxxxxxxxxxx

Session tokens are issued by the vault during agent registration and have a 24-hour TTL. Fetch a fresh token from the dashboard (or via the dashboard API documented separately) before the current one expires.

A revoked or expired token produces 401 TOKEN_EXPIRED or 401 TOKEN_REVOKED on the next request. The agent's EAS attestation UID never changes — only the session token does.

Provider identifiers

The full catalog of 54 launch providers — with overview, action-class defaults, and runnable code samples per language — lives at Providers Overview. The dashboard's "Connect" buttons deep-link to individual provider pages.

For unlisted upstreams, see Custom Provider — paste a base URL, classify the routes, route traffic through AgentRoot in five minutes.

Streaming and idempotency

Both work as documented in Providers → Conventions — streaming responses pass through byte-for-byte; idempotency keys deduplicate within a 24-hour window.

Related