Savine Documentation

API Reference ​

Savine's API is RESTful, uses predictable resource-oriented URLs, returns JSON-encoded responses, and uses standard HTTP response codes.

Authentication ​

Identify yourself to the API by providing an X-API-Key header, or a Authorization: Bearer <JWT> token for browser/dashboard sessions.

Get your API key via the CLI (savine keys create) or underneath Settings > Developer.

bash
curl -H "X-API-Key: sk_live_yourkeyhere..." https://api.savine.dev/v1/agents

Agents API ​

List Agents ​

GET /api/v1/agents Returns a paginated list of all agents.

  • Query Params: page, limit, status
  • Response: 200 OK Array of agent objects.

Create Agent ​

POST /api/v1/agents Creates and deploys a new agent.

  • Body: Entire agent.json definition.
  • Response: 201 Created Agent object with assigned id.

Get Agent ​

GET /api/v1/agents/:id Returns full details of an agent, including its configuration overlay and versions.

Delete/Archive Agent ​

DELETE /api/v1/agents/:id Marks an agent as archived. Existing tasks will finish, but no new tasks can be queued.

Tasks API ​

Submit Task ​

POST /api/v1/tasks Submits a job to an agent asynchronously.

  • Body: { "agentId": "string", "input": "string" }
  • Response: 202 Accepted { "id": "tsk_123", "status": "QUEUED" }

Get Task Status ​

GET /api/v1/tasks/:id Returns status QUEUED, RUNNING, COMPLETED, or FAILED. If completed, the output field is populated.

Get Task Trace ​

GET /api/v1/tasks/:id/steps Returns the array of THINK, ACT, OBSERVE steps for the task execution history.

Stream Task (SSE) ​

GET /api/v1/tasks/:id/stream Server-Sent Events endpoint to stream the execution graph live as it runs.

Systems API ​

Deploy System ​

POST /api/v1/systems/deploy Deploys a new system.json manifest.

Run System ​

POST /api/v1/systems/:slug/run Executes an entire system pipeline asynchronously.

Stream System Execution ​

GET /api/v1/systems/:slug/runs/:id/stream SSE stream of every step across all agents inside the pipeline.

Observability API ​

Platform Metrics ​

GET /api/v1/metrics Returns aggregated token counts, task volumes, and cost spanning your entire workspace.

Task Telemetry ​

GET /api/v1/metrics/observability/tasks/:id Returns latency breakdown and isolated token calculation for a specific task.