API Reference

Base URL: https://app.modelreins.com (SaaS) or your self-hosted coordinator address. All endpoints require the Authorization: Bearer <api-key> header unless noted otherwise.

Jobs

`POST /api/jobs`

Create a job record. To dispatch it immediately, use POST /dispatch instead.

{
  "prompt": "Summarize this document",
  "input": "...",
  "provider": "claude",
  "model": "haiku",
  "priority": "normal",
  "tier": "medium",
  "tags": ["summarize"]
}

`POST /dispatch`

Dispatch a job to the best available worker. Accepts the same body as POST /api/jobs but also runs the router scoring algorithm and assigns the job immediately.

Returns 200 with the job object (including the assigned worker) on success, or 503 if no eligible workers are available.

`GET /api/jobs/:id`

Get job details and result.

`PUT /api/jobs/:id`

Update a job’s metadata (tags, priority, tier). Cannot update a job that has already completed.

`GET /api/jobs`

List jobs. Query params: status, provider, limit, offset.

`POST /api/jobs/:id/cancel`

Cancel a pending or running job.

`POST /api/jobs/:id/retry`

Requeue a failed or stuck job.

Workers

`GET /api/workers`

List all registered workers.

`GET /api/workers/:id`

Get worker details.

`POST /api/workers/:id/pause`

Pause a worker (stops picking up new jobs).

`POST /api/workers/:id/resume`

Resume a paused worker.

Presence

`GET /presence`

List all workers currently reporting presence (online, idle, busy). Includes last heartbeat timestamp and current load.

`PUT /presence`

Workers call this to report or update their presence. Typically sent by the Companion on a heartbeat interval.

{
  "instance": "my-worker",
  "status": "idle",
  "tags": "code,draft,economy",
  "provider": "ollama"
}

Killswitch

`POST /tenant/killswitch`

Activate the tenant killswitch. Immediately halts all running jobs, pauses all workers, and rejects new dispatches. Use in emergencies (runaway costs, compromised keys, etc.).

{
  "level": 4,
  "reason": "runaway dispatch detected"
}

Levels: 0 (no-op) through 4 (full halt). See the killswitch docs for level definitions.

`POST /tenant/killswitch/clear`

Clear the killswitch and resume normal operations. Paused workers must be resumed individually or with ?resume_all=true.

Cost

`GET /api/cost/summary`

Cost summary for a period. Query params: period (day, week, month).

`GET /api/cost/breakdown`

Cost breakdown by provider. Query params: period.

Health

`GET /health`

Returns 200 OK with coordinator status. No auth required.