Broker API¶

The broker exposes FastAPI routes grouped by responsibility. Local development serves OpenAPI at /docs and /openapi.json.

Users and API keys¶

POST /users: Create a user with optional initial credits.
GET /users/me: Return the authenticated user profile.
POST /users/credits: Add credits to the authenticated account.
POST /users/rotate-key: Rotate the default API key and return the new key.

Jobs¶

POST /run/model: Submit a model inference job.
POST /run/equation: Submit a structured equation job.
GET /jobs/{job_id}: Read job status, metadata, and output when available.
GET /jobs/{job_id}/stream: Stream Server-Sent Events for tokens and terminal job state.
POST /jobs/{job_id}/cancel: Cancel a queued or running job.

Hosts¶

POST /hosts/register: Register a host and its model capabilities.
POST /hosts/heartbeat: Keep a host online and update its status.
POST /hosts/next-job: Atomically claim the next compatible queued job.
POST /hosts/jobs/{job_id}/chunk: Publish a generated token or text chunk.
POST /hosts/complete-job/{job_id}: Complete a job and finalize billing.
POST /hosts/fail-job/{job_id}: Fail a job and refund reserved credits.

Catalog and discovery¶

GET /models: List registered model specifications.
GET /models/{model_name}: Inspect a single registered model.
GET /hosts: Discover public host capacity and filter by model or status.

Operations¶

GET /metrics: Prometheus metrics for jobs, hosts, runtime, and cost.
/admin/*: Admin-only endpoints protected by x-admin-key.