Conventions and permissions

Every route in the 10xGraph REST API lives under /v1/ (except /ping), returns the same JSON envelope, authenticates with a Bearer token, and is guarded by a resource and action permission pair. This page lists those shared rules, the full permission table, the WebSocket close codes and the HTTP status codes.

Base URL and response envelope

Successful responses wrap the payload in data and add a metadata object with request_id, timestamp and message. Errors raised by the application return error instead, with the same metadata. The details list is empty unless the error carries extra context (validation errors, for example).

{
  "data": {},
  "metadata": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-05-23T10:00:00",
    "message": "OK"
  }
}

{
  "error": {
    "code": "EXPIRED_TOKEN",
    "message": "Token has expired, please login again",
    "details": []
  },
  "metadata": {
    "request_id": "550e8400-e29b-41d4-a716-446655440000",
    "timestamp": "2026-05-23T10:00:00",
    "message": "Token has expired, please login again"
  }
}

Errors from HTTPException (permission denied, not found, empty upload) use the code HTTPException. Request validation failures use VALIDATION_ERROR. Three responses come from middleware and do not use this exact shape: 409, 413 and 429 (see HTTP status codes).

Authentication

When auth is configured in 10xgraph.json, every endpoint except /ping (and the public eval routes) needs a Bearer token. Send it as an Authorization header on HTTP routes. WebSocket clients that cannot set headers have two fallbacks, listed here in order of preference.

Authorization: Bearer <token>

// Preferred for browsers: the token rides in a request header, not the URL
new WebSocket("ws://host/v1/graph/ws", ["10xgraph-bearer", token]);

# Last-resort fallback (WebSocket only): the token lands in URLs and access logs
/v1/graph/ws?token=<token>

The server echoes the 10xgraph-bearer sentinel back on accept, which browsers require to complete the handshake. The older agentflow-bearer sentinel is accepted until 2.0. The ?token= query parameter is read only on WebSocket connections.

If auth is not configured ("auth": null), credentials are not required. Missing, invalid or expired credentials return HTTP 401. A permission failure returns 403. On WebSocket routes both become close code 1008. See authentication for setup.

Permission model

Each endpoint declares one (resource, action) pair. On every request the server calls authorize(user, resource, action) on the configured AuthorizationBackend. The built-in DefaultAuthorizationBackend allows any request whose user has a user_id, so write your own backend for real access control.

Permission reference

The table lists every (resource, action) pair the server enforces. POST /v1/ag-ui exists only when ag_ui.enabled is true in 10xgraph.json. The /v1/evals/* routes are mounted only when MODE is not production.

The last three rows are the complete public allowlist. Every other route must carry a RequirePermission guard, and the server refuses to start if one does not.

WebSocket close codes

WebSocket routes report failures with close codes instead of HTTP statuses. 1008 also covers a graph that is on the wrong socket: a realtime graph on /v1/graph/ws, or a turn-based graph on /v1/graph/live.

HTTP status codes

These are the status codes the server returns. Routes document their own specific causes on their pages.