Sortd API

Quickstart

Authenticate, find work, create a task, and get the AI read on a thread — in five minutes.

1. Authenticate

Create a key in Sortd (Settings → API). Send it as a Bearer token on every request. Keys are shown once — store it now.

curl https://api.sortd.com/v2/me -H "Authorization: Bearer sk_live_…"

Responses are always { "data": …, "meta": { "request_id": … } }. Lists add meta.pagination.

2. Walk the hierarchy

Teams → boards → lists. IDs are opaque and prefixed (brd_, lst_, tsk_).

curl "https://api.sortd.com/v2/teams" -H "Authorization: Bearer sk_live_…"
curl "https://api.sortd.com/v2/boards?team_id=TEAM_ID" -H "Authorization: Bearer sk_live_…"
curl "https://api.sortd.com/v2/boards/brd_…/lists" -H "Authorization: Bearer sk_live_…"

3. Find and create work

# list tasks (cursor-paginated)
curl "https://api.sortd.com/v2/tasks?list_id=lst_…&limit=20" -H "Authorization: Bearer sk_live_…"

# create a task — Idempotency-Key makes retries safe
curl -X POST https://api.sortd.com/v2/tasks \
  -H "Authorization: Bearer sk_live_…" \
  -H "Idempotency-Key: 7c1f-…" \
  -d '{"list_id":"lst_…","title":"Follow up with Acme","notes":"Sent pricing"}'

4. Get the AI read on a thread

Classification is cached-or-enqueue: a cached result returns instantly; otherwise you get 202 with a poll URL (typically 10–30s).

curl -X POST https://api.sortd.com/v2/ai/classify-thread \
  -H "Authorization: Bearer sk_live_…" \
  -d '{"thread_id":"…"}'
# -> { "data": { "status": "queued", "job_id": "job_…", "poll_url": "https://api.sortd.com/v2/ai/jobs/job_…" } }

Errors & scopes

Errors are { "error": { "code", "message", "request_id" } } with stable codes — scope_insufficient, subscription_required, rate_limited, idempotency_conflict. Keys carry scopes (tasks.read, tasks.write, ai.classify, webhooks.manage, …).

Next