Custom Work (Quoted)

Task type: custom

Anything you can describe, a human can do — but it's priced per task. You submit an instruction brief; Worca reviews it and sets a quote; work starts only after you approve. This is the only task type with an extra lifecycle stop: awaiting_approval.

queued (being quoted) → awaiting_approval (quote ready)
  → approve → queued → in_progress → done
  → decline → failed (closed by you)

Schema

Input fields

Field	Type	Required	Description
`instruction`	string	yes	What to do, in plain language — step by step if it matters
`deliverable`	string	no	What a finished result looks like
`links`	string[]	no	Accounts, assets, or references the human needs
`budget_hint_cents`	number	no	Optional budget ceiling in USD cents — helps Worca quote within range

Result fields

Field	Type	Required	Description
`summary`	string	yes	What was done
`output_url`	string	no	Link to the artifact, if any (the proof)

Example input

{
  "instruction": "Visit the three hardware stores listed and photograph their garden-hose shelf pricing.",
  "deliverable": "One photo per store, legible price tags, uploaded anywhere durable.",
  "links": [
    "https://maps.example.com/store-list"
  ]
}

Ideal workflow

worca tasks create --type custom --input @brief.json --no-wait --json   # → { id, status: queued }
worca tasks get tsk_… --json          # poll until status: awaiting_approval, read quote_cents
worca tasks approve tsk_…             # accept — work starts (or: worca tasks decline tsk_…)
worca tasks get tsk_… --json          # poll until done

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

# poll until status is awaiting_approval, then:
curl -s -X POST "$WORCA_API_URL/v1/tasks/tsk_…/approve" \
  -H "Authorization: Bearer $WORCA_API_KEY"

The task object carries quote_cents (what you pay, USD cents) and quoted_at once the quote is set. With --wait, the CLI blocks until the quote arrives, prints it, and exits 0 so your agent can decide.

Sad workflows

You decline — worca tasks decline / POST …/decline. The task closes and reads as failed on the wire; the decline itself exits 0 (a deliberate pass, not an error).
Quote never comes — until an operator quotes, status stays queued. There is no quote SLA yet; budget for human review time.
Approve/decline at the wrong moment — both return 409 unless status is exactly awaiting_approval (e.g. you already decided, or it isn't quoted yet).
Instruction too vague to quote — ops may cancel instead of quoting (failed). Write the brief like you'd brief a contractor: outcome, constraints, what "done" looks like.
Worker blocked mid-task — same as every type: flagged internally, reads in_progress, ops requeue or cancel.