Conventions and permissions

Everything on this page applies to every endpoint in this section.

Base URL

All API routes (except /ping) are prefixed with /v1/.

Response envelope

Every successful endpoint wraps its payload in a uniform envelope:

{
  "success": true,
  "data": { ... },
  "message": "optional message",
  "timestamp": "2026-05-23T10:00:00Z"
}

Errors (4xx / 5xx) return FastAPI’s standard detail format:

{
  "detail": "Not authorized to invoke graph"
}

Authentication

When auth is configured in 10xgraph.json, all endpoints except /ping require a Bearer token:

Authorization: Bearer <token>

WebSocket connections that cannot set an Authorization header have two options, in order of preference:

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

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

The server echoes the agentflow-bearer sentinel back on accept(), which browsers require to complete the handshake.

If auth is not configured ("auth": null), credentials are not required and the auth layer is skipped entirely.

Authentication failures return HTTP 403 with an error.code such as REVOKED_TOKEN or EXPIRED_TOKEN, not 401. On WebSocket routes the same failures become close code 1008.

Permission model

Each endpoint requires a specific (resource, action) pair. The table below lists them. When an AuthorizationBackend is configured, the authorize(user, resource, action) method is called. The built-in DefaultAuthorizationBackend allows all requests as long as user_id is present.

Permission reference

The table below lists every (resource, action) pair enforced by the server. When an AuthorizationBackend is configured, each request calls authorize(user, resource, action).

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.

HTTP status codes