Skip to content
IdleAI/Docs
Workspace
Handbook/Build & operate
Guide

HTTP API reference

The current routes, authentication requirements, response shapes, and intentionally disabled capabilities.

Reviewed 20 September 20266 sectionsUnderstand the status labels

In this chapter

Conventions#

The canonical origin is https://idleai.xyz. Browser account APIs use HttpOnly wallet-session cookies and same-origin mutation checks. The developer completion route uses a bearer API key instead. Treat error bodies as route-specific: browser routes commonly return an error string, while the OpenAI-shaped route uses an error object.

Examples use placeholders and are not credentials. Do not extract or publish HttpOnly session cookies to follow an example. Use the actual browser sign-in flow, and keep developer keys in an authorized secret store.

Route index#

Method and pathAuthorizationCurrent behavior
GET /api/authOptional wallet sessionReturns the authenticated address or null.
POST /api/authSame-origin challenge flowCreates a challenge or verifies a signature.
DELETE /api/authSame-origin wallet sessionRevokes that session and clears cookies.
GET /api/stateOptional wallet sessionReturns owner-scoped account metadata; no fabricated market data.
POST /api/keysWallet sessionCreates a real API key; full secret is returned once.
DELETE /api/keysWallet sessionRevokes a key belonging to that owner.
GET /api/suppliersWallet sessionReturns the owner's application or null.
POST /api/suppliersWallet sessionStores one pending application per wallet.
GET /api/v1/modelsPublicReturns the live catalog of published models with active offers.
POST /api/v1/chat/completionsBearer API keyExecutes a billed request through the pipeline; 401 invalid key, 402 unfunded, 409 replayed request_id.
POST /api/chatWallet sessionSame pipeline for the workspace composer; requires a funded balance.
POST /api/depositsWallet sessionClaims a USDG transfer to the treasury by tx hash; on-chain verification before crediting.
GET /api/receiptsWallet sessionLists the account's usage receipts.
GET/POST/DELETE /api/chatsWallet sessionLists, saves, and deletes saved conversations. GET /api/chats?export=1 downloads every chat as JSON.
GET/POST/DELETE /api/profileWallet sessionProfile fields (display name, referral code) and sign-out-everywhere.
GET /api/activityWallet sessionAppend-only feed: top-ups, usage charges, referral credits, payouts.
GET /api/payouts · POST /api/payoutsWallet sessionLists and requests supplier payouts; escrowed pending operator settlement.
POST /api/accountWallet sessionFunding/reset operations are unavailable; no faucet.
POST or DELETE /api/ordersWallet sessionTrading is unavailable; no synthetic fill.
GET /api/configPublicReports capability flags; peer matching remains unavailable.
POST /api/configSame-originCannot enable peer matching; returns unavailable.
GET or POST /api/earlyPublic registration/statsWaitlist operations; administrative exports have a separate gate.

Authentication payloads#

json
{
  "action": "challenge",
  "address": "<YOUR_EVM_WALLET_ADDRESS>"
}
POST /api/auth. The response includes the expected message and sets a short-lived challenge cookie.
json
{
  "action": "verify",
  "signature": "<SIGNATURE_OF_THE_SERVER_MESSAGE>"
}
POST /api/auth after signing the exact server message. The server uses its stored challenge; a client-supplied replacement message is not authoritative.
json
{
  "address": null
}
GET /api/auth when no valid session is present.

API key payloads#

json
{
  "label": "production-backend"
}
POST /api/keys using the authenticated browser session. Labels must be 1–80 characters.
json
{
  "ok": true,
  "key": {
    "id": "<KEY_ID>",
    "label": "production-backend",
    "key": "<SECRET_SHOWN_ONCE>",
    "created": 0
  }
}
Response shape only; created is a timestamp in milliseconds, not the illustrative zero shown here.
json
{
  "id": "<KEY_ID>"
}
DELETE /api/keys. Ownership is checked server-side; an address in the request cannot override it.

Supplier application payload#

json
{
  "name": "<SUPPLIER_NAME>",
  "endpoint": "https://<YOUR_AUTHORIZED_ENDPOINT>/v1",
  "model": "<EXACT_MODEL_ID>",
  "email": "<OPERATIONS_CONTACT>",
  "retention": "<ACCURATE_DATA_HANDLING_DESCRIPTION>",
  "rights": true
}
POST /api/suppliers. This stores an application; it does not probe or activate an endpoint.

Successful creation returns 201 with an application ID and pending review status. An existing application returns 409 rather than being overwritten. The server requires nonempty string fields within the current bounds, an appropriate HTTPS URL, a contact email, and explicit rights confirmation.

Errors and retries#

StatusTypical meaningAction
400Invalid wallet, key label, or application payload.Correct the request; do not retry unchanged.
401No valid session/key, or rejected/expired sign-in challenge.Sign in again or use an active credential.
403Origin or cross-site request rejected.Use the canonical site; do not disable the check.
404Unknown owner-scoped resource or unregistered waitlist address.Check the resource and account context.
409A supplier application already exists.Read the existing status instead of duplicating it.
413Request exceeds a transport/body limit.Reduce the payload.
429A configured request/capacity limit was reached.Back off; no universal public quota or SLA is promised here.
503Storage/verification unavailable or a capability intentionally disabled.Distinguish an outage from a feature that is not live; do not loop retries.

A waitlist storage failure returns a retry hint and does not claim successful persistence. For future paid inference, timeout/retry handling must use reconciled request identities; an HTTP error alone is not enough to decide whether work happened or money moved.

Handbook