REST API Reference

Generated from the API spec — do not edit by hand. Run pnpm gen to refresh.

Everything the CLI does rides on this /v1 surface.

export WORCA_API_URL="https://worca-hi-api.up.railway.app"

Authentication

Every endpoint requires a Bearer API key:

Authorization: Bearer wk_live_…

A missing or invalid key returns 401 with

{
  "error": "Invalid or missing API key"
}

The examples below use $WORCA_API_URL and $WORCA_API_KEY — the same variables the SDK and CLI read.

The task object

Every task-returning endpoint serializes this shape:

Field	Type	Required	Description
`id`	string	no	Callback ID — poll `GET /v1/tasks/:id` with it
`mode`	string	no	Always `EXECUTE`
`type`	enum: social_post · video_edit · phone_call · custom	no	Task type
`status`	enum: queued · awaiting_approval · in_progress · done · failed	no	Wire status; `done` and `failed` are terminal. `awaiting_approval` (custom tasks): the quote is in — approve or decline
`quote_cents`	number	null	no
`quoted_at`	string	null	no
`picked_up_at`	string	null	no
`concluded_at`	string	null	no
`result`	object	null	no
`proof_url`	string	null	no
`created_at`	string	no	ISO timestamp the task was created

Endpoints

GET /v1/whoami

Who does this key belong to. Use it to validate a key and read the account name/tier.

Returns \{ account: \{ id, name, tier } }

curl -s "$WORCA_API_URL/v1/whoami" \
  -H "Authorization: Bearer $WORCA_API_KEY"

GET /v1/status

Platform-wide system status: worker-queue depth and the median time from task creation to human pickup. For bare uptime checks without a key, use GET /health.

Returns \{ ok, time, hours, queue: \{ queued, in_progress }, eta_s } — eta_s is the median seconds until a human picks a task up (recent sample; null if there's no recent data).

curl -s "$WORCA_API_URL/v1/status" \
  -H "Authorization: Bearer $WORCA_API_KEY"

GET /v1/task-types

The machine-readable task catalog — what humans can do, with field-level input/result schemas and an example input per type. Same registry the CLI ships offline.

Returns \{ task_types: [...] } — one entry per type with name, title, summary, input_fields, result_fields, proof, and example_input.

curl -s "$WORCA_API_URL/v1/task-types" \
  -H "Authorization: Bearer $WORCA_API_KEY"

POST /v1/tasks

Create an execute task. A vetted human performs it; poll the returned id for the result.

Request body

Field	Type	Required	Description
`type`	enum: social_post · video_edit · phone_call · custom	yes	Which task type to run
`input`	object	yes	Type-specific input — schema and example from `GET /v1/task-types`
`deadline`	string	no	ISO timestamp the task must conclude by

Returns 201 with the created task object; status starts at queued. custom tasks are quoted first: poll until status is awaiting_approval, then approve or decline.

Errors

400 — type missing or not an execute type
400 — input fails the type's schema — \{ error: "invalid input", details: [...] } lists per-field problems

curl -s -X POST "$WORCA_API_URL/v1/tasks" \
  -H "Authorization: Bearer $WORCA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "type": "social_post", "input": { … } }'

POST /v1/tasks/:id/approve

Accept the quote on a custom task. The task joins the worker queue and work starts.

Returns The task object, now queued.

Errors

404 — No task with that id on this account
409 — Task is not awaiting approval

curl -s -X POST "$WORCA_API_URL/v1/tasks/tsk_3b91…/approve" \
  -H "Authorization: Bearer $WORCA_API_KEY"

POST /v1/tasks/:id/decline

Decline the quote. The task concludes; it reads as failed on the wire.

Returns The task object, now failed.

Errors

404 — No task with that id on this account
409 — Task is not awaiting approval

curl -s -X POST "$WORCA_API_URL/v1/tasks/tsk_3b91…/decline" \
  -H "Authorization: Bearer $WORCA_API_KEY"

GET /v1/tasks

List the account's tasks, newest first.

Query parameters

Parameter	Type	Required	Description
`status`	enum: queued · awaiting_approval · in_progress · done · failed	no	Filter by wire status
`limit`	number	no	Page size (default 20, max 100)

Returns \{ tasks: [...] } — task objects, newest first.

curl -s "$WORCA_API_URL/v1/tasks?status=done&limit=10" \
  -H "Authorization: Bearer $WORCA_API_KEY"

GET /v1/tasks/:id

The callback endpoint. Poll until status is done or failed.

Returns The task object.

Errors

404 — No task with that id on this account

curl -s "$WORCA_API_URL/v1/tasks/tsk_3b91…" \
  -H "Authorization: Bearer $WORCA_API_KEY"