Documentation
API reference
The Go API serves JSON, SSE and WebSocket endpoints. Inference streams go directly from the client to the gateway; the Next.js console does not proxy them. The authoritative machine-readable contract is generated from the validated route schemas in controlplane/.
Authentication
Browser requests use a secure, host-only session cookie. Mutating browser requests must send X-Agentranking-CSRF with the value of the readable ar_csrf cookie. Machine clients use a workspace-scoped bearer API key. A session or CLI bearer calling /v1 must also send one X-Agentranking-Workspace-ID header; an API key is already bound to its workspace and project. W below means /api/v1/workspaces/{workspace_id}.
curl -N https://agentranking.io/v1/chat/completions \
-H "Authorization: Bearer ar_live_REPLACE_WITH_WORKSPACE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<model-id from GET /v1/models>",
"messages": [{"role":"user","content":"Explain exact settlement."}],
"stream": true
}'Example only. Replace the placeholder key and model ID with values from your workspace. No response is shown because output depends on the request.
curl https://agentranking.io/v1/responses \
-H "Authorization: Bearer ar_live_REPLACE_WITH_WORKSPACE_KEY" \
-H "Content-Type: application/json" \
-d '{
"model": "<model-id from GET /v1/models>",
"input": "Summarize the retention policy.",
"store": false
}'Example only. store: false requests no stored response. Stored responses are opt-in and expire under the retention rules below.
CLI login
Install with curl -fsSL https://agentranking.io/install.sh | sh and run agentranking login. The CLI uses the OAuth 2.0 Device Authorization Grant: it prints a short code, opens /activate and polls for approval. Approving the request requires a fresh passkey, password or wallet step-up in the browser. The resulting bearer is a revocable CLI session stored under AGENTRANKING_HOME (default ~/.agentranking), never a browser cookie.
agentranking logout revokes that session. whoami, account, workspace list, workspace use, keys list, keys create and keys revoke manage the account from the terminal. The same binary includes the native provider connector under agentranking connector bootstrap|enroll|run|status|doctor|uninstall. Automation can use agentranking login --with-api-key with a key on stdin, but that credential is limited to inference, catalog, jobs, usage and file access. agentranking auth status reports the active credential, source, expiry and capabilities. See Install for commands and platform-specific setup.
Money and timestamps
Monetary fields are integer microdollars (0.000001 USD). Native amounts are decimal strings in wei or lamports. Never use floating-point arithmetic for money and never add unlike units. Timestamps are ISO-8601 with an explicit offset.
{
"available_micros": "3200000",
"granted_micros": "1200000",
"topped_up_micros": "2000000",
"spent_micros": "4100000",
"is_available": true
}Provider earnings are a separate read at GET W/supply/earnings withpending_micros, withdrawable_micros,payout_pending_micros and the current minimum payout request. Customer credit is never combined with provider earnings in one response.
Errors
Management endpoints return RFC 9457 application/problem+json. OpenAI-compatible execution endpoints keep their OpenAI-shaped error envelope, and SSE/binary transports keep their declared stream behavior. All families carry a request ID header; stack traces, SQL and credentials are never returned.
{
"title": "Unauthorized",
"status": 401,
"detail": "Authentication is required."
}Idempotency and retries
Inference and money- or resource-mutating requests accept Idempotency-Key. Reusing a key with different canonical input is a conflict. A streaming request that already exposed output is never silently rerun to pretend it is the same stream.
Discovery and from-prices
GET /v1/models and GET /api/v1/catalog/models expose approved models with capability metadata and buyer-facing from-prices. The model list is the source for from-prices; the gateway computes and settles the exact metered charge. Listing search is not public: it is an authenticated advanced surface for workspace operators and requires catalog:read.
OpenAI-compatible profiles
Supported profiles are chat, responses, embeddings, images, audio_speech and audio_transcription. A profile is available only where an eligible deployment publishes it.
Chat and Responses support non-streaming and streamed responses. Embeddings validate indices and dimensions. Image generation accepts only approved recipes and bounded counts. Audio speech accepts published voices and formats. A profile that is not supported by an eligible deployment returns an explicit error instead of a synthetic result.
Types streaming uses server-sent events. For Responses, lifecycle event types are preserved. Cancellation is supported for an admitted stored response; closing a chat stream settles delivered usage.
Jobs, batches and files
Jobs are submitted as a chat-shaped request and return an accepted job with a reserve. Batches accept JSONL items with unique custom_id values and a declared completion window. Files are workspace-owned, bounded and expire. Result artifacts are published only after successful terminal state.
Private endpoints
Routing endpoints use normal per-request metering. Reserved endpoints use a capacity rate and expose replica bounds and budgets. Both are authorized by workspace ownership and the default policy. Routes for this slice are registered independently of inference; the console reports their absence honestly.
Provider API
A native device uses a one-use bootstrap credential; a browser device is upserted by its installation key. Starting serving resolves an approved variant, runtime recipe and meter profile, creates the runtime and offer automatically, and records one accepted immutable price revision. Profiles, modes, assurance and availability are derived and enforced server-side.
Administration
Platform roles gate incident publication, catalog approval and reconciliation. Approval of a catalog object records a review decision on an immutable manifest. It does not create supply and does not prove that a provider runs the object correctly.
Endpoint inventory
| Method | Path | Purpose |
|---|---|---|
| POST | /api/v1/auth/signup | Create an account; no workspace is implied |
| POST | /api/v1/auth/signin | Create a browser session and CSRF token |
| POST | /api/v1/auth/device/code | Start a CLI device authorization request |
| POST | /api/v1/auth/device/token | Poll and exchange an approved CLI request |
| GET | /api/v1/account | Read the signed-in account |
| PATCH | /api/v1/account/preferences | Store the chooser last_workspace_id only |
| GET | /api/v1/account/sessions | List user-global browser, CLI and mobile sessions |
| GET | /api/v1/account/passkeys | List user-global passkeys |
| GET | /api/v1/account/wallets | List the user’s verified wallets |
| GET | /api/v1/auth/credential | Read an API key’s fixed workspace, project and scopes |
| GET/POST | /api/v1/workspaces | List authorized workspaces / create one |
| GET | /api/v1/workspaces/{workspace_id} | Read the workspace descriptor and permissions |
| GET | /api/v1/catalog/models | Approved models with variants and eligible price ranges |
| GET | /api/v1/marketplace/listings | Eligible listing search for the explicit workspace |
| POST | /v1/chat/completions | OpenAI-compatible chat, streaming or JSON |
| POST | /v1/responses | OpenAI-compatible Responses API |
| GET | /v1/responses/{response_id} | Read an explicitly stored response |
| POST | /v1/embeddings | Embeddings with declared dimensions and encoding |
| POST | /v1/images/generations | Approved image recipe generation |
| POST | /v1/audio/speech | Speech synthesis for published voices |
| GET/POST | /v1/files | List and upload workspace files (delete: /v1/files/{file_id}) |
| GET | W/inference/requests/{request_id} | Admitted request status and settlement projection |
| GET | W/inference/receipts/{receipt_id} | One exact settlement receipt |
| GET | W/billing/credit-balance | Customer credit projection |
| GET/POST | W/billing/card-orders | Card funding orders and checkout |
| GET/POST | W/billing/crypto-invoices | Native deposit invoices |
| GET/POST | W/billing/refunds | Refund history and requests |
| GET | W/usage | Settled usage rows with exact token counts |
| POST/GET | W/inference/jobs | Submit and list durable inference jobs |
| POST | W/inference/jobs/{job_id}/cancel | Cancel a durable job |
| POST/GET | W/inference/batches | Upload and list JSONL batches |
| GET | W/inference/endpoints | Private routing and reserved-capacity endpoints |
| GET | W/supply/devices | Bounded device inventory |
| POST | W/supply/device-enrollments | Issue a one-use native device bootstrap credential |
| GET/POST | W/supply/models | List or register provider-observed model manifests |
| POST | W/supply/devices/{device_id}/serve | Create or attach one approved runtime and offer |
| POST | W/supply/offers/{offer_id}/price-revisions | Publish an immutable offer price revision |
| POST | W/supply/offers/{offer_id}/pause | Pause new work for an offer |
| GET | W/supply/earnings | Journal-derived provider balances |
| GET/POST | W/supply/payouts | Crypto or fiat payout history and requests |
| GET | W/supply/fiat-account | Provider fiat account and onboarding state |
| GET | W/exports | Export records and published content |
| GET | W/notifications | Workspace notices and per-user read state |
| GET/POST | W/disputes | Support dispute history and creation |
| GET/POST | W/webhooks | Signed webhook subscriptions |
| GET | /api/v1/admin/incidents | Incident list for support roles |
| POST | /api/v1/admin/catalog/approvals | Approve an immutable catalog object |
| GET | /api/v1/admin/reconciliations | Incremental and operator-triggered full ledger reconciliation evidence |
Retention
Synchronous prompts remain in process memory and are not logged. Asynchronous inputs and generated outputs are stored as bounded encrypted local files with workspace ownership, random paths, integrity digests and a default 24-hour expiry. PostgreSQL stores metadata and references, not prompt bodies. A repeated idempotent non-streaming request is rejected as a replay; the result body is not cached for redelivery.
Stored Responses retention is opt-in and expires automatically. Streaming output is delivered incrementally; the server records usage and billing metadata rather than treating every token as a durable message log.
Limits
Request bodies, output length, tool definitions, image counts, queue wait and execution deadlines are bounded. Admission reserves credit and allocates funding lots under one transaction. Revoking an API key stops new work immediately; active work is cancelled separately.
