Authentication

API Key

Include your key in the X-Api-Key header on every request. Keys are scoped to your organization.

X-Api-Key: your_api_key_here

Missing or invalid keys return 401:

{ "error": "API key is required" }
{ "error": "Invalid API key" }

Submitting Tasks

A task is a unit of work dispatched to a Scribe. The agent works through it autonomously. Tasks move through open → in_progress → done. If the agent needs input, the task enters waiting.

POST /api/v1/scribes/:scribe_id/requests

curl -X POST "https://www.obelisk.li/api/v1/scribes/SCRIBE_ID/requests" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: your_api_key_here" \
  -d '{
    "task": {
      "summary": "Summarize open support tickets and flag blockers.",
      "acceptance_criteria": "Ticket count + blocker list"
    }
  }'

Task fields

Field	Required	Description
`task.summary`	Yes	What the Scribe should do.
`task.title`	No	Short label. Auto-generated from summary if omitted.
`task.acceptance_criteria`	No	Definition of done.
`task.attachments`	No	Array of file objects (max 5). See below.
`actor_kind`	No	Must be `"task"`. Defaults to `"task"`.

Attachments

Provide external URLs. Obelisk downloads and stores them server-side. Each attachment requires url and content_type. filename is derived from the URL if omitted.

"attachments": [
  {
    "url": "https://files.example.com/handoff.html",
    "content_type": "text/html",
    "filename": "handoff.html"
  }
]

Receipts

The POST returns immediately with a receipt. The task is dispatched asynchronously.

{
  "request": {
    "id": "req_01J0X1BX0Y3E4B1XM0TSAM0SZY",
    "scribe_id": "9f2a3b7c-...",
    "status": "accepted",
    "entity_type": "task",
    "entity_id": null,
    "error_message": null,
    "created_at": "2026-03-25T18:30:00.000Z",
    "updated_at": "2026-03-25T18:30:00.000Z"
  }
}

Polling

GET /api/v1/requests/:id to check progress. Status transitions: accepted → dispatched → fulfilled | failed.

Once fulfilled, entity_id is the ScribeTask UUID. On failure, error_message explains why.

{
  "request": {
    "id": "req_01J0X1BX0Y3E4B1XM0TSAM0SZY",
    "scribe_id": "9f2a3b7c-...",
    "status": "fulfilled",
    "entity_type": "task",
    "entity_id": "93a2f9f7-bc8d-40e4-8ecf-d02150846dc6",
    "error_message": null,
    "created_at": "2026-03-25T18:30:00.000Z",
    "updated_at": "2026-03-25T18:30:05.000Z"
  }
}

Listing Requests

GET /api/v1/scribes/:scribe_id/requests

Param	Description
`status`	`accepted`, `dispatched`, `fulfilled`, or `failed`
`entity_type`	Currently only `task`
`limit`	Results per page (default 25, max 100)

Next: Errors →