# Sortd API

> Sortd is the work/operations layer around the mailbox. Where Gmail's API gives an AI agent a
> raw mailbox, Sortd's API gives it a team's email operation: threads become owned, stateful work
> items with assignments, AI classification, customer context and a human-in-the-loop review flow.

Use this API when the user wants an AI assistant to triage, organise, assign, or report on a
team's email work — not just read raw mail.

## Auth
Bearer API key (`Authorization: Bearer sk_live_…`) or OAuth 2.1 + PKCE. Every request is scoped;
missing scope returns 403 `scope_insufficient`; a plan without a feature returns 403
`subscription_required`.

## Conventions
- Responses are `{ data, meta: { request_id, pagination? } }`. Tolerate unknown fields.
- IDs are opaque and prefixed: tasks `tsk_`, boards `brd_`, lists `lst_`, webhooks `wh_`.
- Writes accept an `Idempotency-Key` header. Lists use opaque `cursor` pagination.
- AI classification is cached-or-enqueue: a cached result returns instantly, otherwise you get a
  202 with a poll URL (typically 10–30s).

## OpenAPI
Full machine-readable spec: https://api.sortd.com/v2/openapi.json

## Endpoints
### AI
- GET https://api.sortd.com/v2/ai/analyses — Read cached AI analyses for a thread (scope: ai.classify)
- POST https://api.sortd.com/v2/ai/classify-thread — Classify a thread (cached or enqueue) (scope: ai.classify)
- GET https://api.sortd.com/v2/ai/jobs/{id} — Poll an AI classification job (scope: ai.classify)

### Boards
- GET https://api.sortd.com/v2/boards — List boards for a team (scope: boards.read)
- GET https://api.sortd.com/v2/boards/{id} — Get a board (scope: boards.read)
- GET https://api.sortd.com/v2/boards/{id}/lists — List a board's task lists (scope: lists.read)
- GET https://api.sortd.com/v2/boards/{id}/custom-fields — List a board's custom fields (scope: customfields.read)
- POST https://api.sortd.com/v2/boards — Create a board (scope: boards.write)
- PATCH https://api.sortd.com/v2/boards/{id} — Rename a board (scope: boards.write)
- DELETE https://api.sortd.com/v2/boards/{id} — Delete a board (scope: boards.write)

### Companies
- GET https://api.sortd.com/v2/companies — List a team's CRM companies (scope: contacts.read)
- GET https://api.sortd.com/v2/companies/{id} — Get a CRM company (scope: contacts.read)
- POST https://api.sortd.com/v2/companies — Create a CRM company (scope: contacts.write)
- PATCH https://api.sortd.com/v2/companies/{id} — Update a CRM company (scope: contacts.write)
- DELETE https://api.sortd.com/v2/companies/{id} — Delete a CRM company (scope: contacts.write)

### Contacts
- GET https://api.sortd.com/v2/contacts — Search a team's CRM contacts (scope: contacts.read)
- GET https://api.sortd.com/v2/contacts/{id} — Get a CRM contact (scope: contacts.read)
- POST https://api.sortd.com/v2/contacts — Create a CRM contact (scope: contacts.write)
- PATCH https://api.sortd.com/v2/contacts/{id} — Update a CRM contact (scope: contacts.write)
- DELETE https://api.sortd.com/v2/contacts/{id} — Delete a CRM contact (scope: contacts.write)

### Custom fields
- POST https://api.sortd.com/v2/boards/{id}/custom-fields — Create a custom field on a board (scope: customfields.write)
- PATCH https://api.sortd.com/v2/boards/{id}/custom-fields/{fieldId} — Update a custom field (scope: customfields.write)
- DELETE https://api.sortd.com/v2/boards/{id}/custom-fields/{fieldId} — Delete a custom field (scope: customfields.write)

### Email
- GET https://api.sortd.com/v2/email/mailbox — Get the key owner's mailbox connection state (scope: email.metadata.read)
- GET https://api.sortd.com/v2/email/labels — List the mailbox's labels/folders (scope: email.metadata.read)
- GET https://api.sortd.com/v2/email-threads — Search the key owner's mailbox (Gmail query) (scope: email.metadata.read)
- GET https://api.sortd.com/v2/email-threads/{threadId} — Get an email thread from the key owner’s mailbox (scope: email.metadata.read)
- POST https://api.sortd.com/v2/email-threads/{threadId}/read-state — Mark an email thread read or unread (scope: email.metadata.write)
- POST https://api.sortd.com/v2/email-threads/{threadId}/archive — Archive an email thread (scope: email.metadata.write)
- POST https://api.sortd.com/v2/email-threads/{threadId}/unarchive — Unarchive an email thread (scope: email.metadata.write)
- POST https://api.sortd.com/v2/email-threads/{threadId}/labels — Add or remove Gmail labels on a thread (scope: email.metadata.write)
- POST https://api.sortd.com/v2/email-threads/{threadId}/snooze — Snooze an email thread (scope: email.metadata.write)
- POST https://api.sortd.com/v2/email-threads/{threadId}/drafts — Create a draft on a thread (scope: drafts.write)
- GET https://api.sortd.com/v2/email-threads/{threadId}/drafts — List your drafts on a thread (scope: email.metadata.read)
- POST https://api.sortd.com/v2/email-threads/{threadId}/drafts/{draftId}/send — Send an existing draft (scope: drafts.send)
- POST https://api.sortd.com/v2/email-threads/{threadId}/reply — Reply to a thread (recipients derived from the thread) (scope: email.reply)
- POST https://api.sortd.com/v2/email/send — Compose and send an email (scope: email.send)
- POST https://api.sortd.com/v2/email/drafts — Create a new draft (scope: drafts.write)

### Identity
- GET https://api.sortd.com/v2/me — Get the authenticated principal

### Lists
- POST https://api.sortd.com/v2/boards/{id}/lists — Create a list on a board (scope: lists.write)
- PATCH https://api.sortd.com/v2/lists/{id} — Rename a list (scope: lists.write)
- DELETE https://api.sortd.com/v2/lists/{id} — Delete a list (scope: lists.write)

### Tasks
- GET https://api.sortd.com/v2/tasks — List or search tasks on a board, list, email thread, or CRM contact (scope: tasks.read)
- GET https://api.sortd.com/v2/tasks/{id} — Get a task (scope: tasks.read)
- POST https://api.sortd.com/v2/tasks — Create a task (scope: tasks.write)
- PATCH https://api.sortd.com/v2/tasks/{id} — Update a task (scope: tasks.write)
- POST https://api.sortd.com/v2/tasks/{id}/complete — Mark a task complete (scope: tasks.write)
- POST https://api.sortd.com/v2/tasks/{id}/reopen — Reopen a completed task (scope: tasks.write)
- POST https://api.sortd.com/v2/tasks/{id}/move — Move a task to another list (scope: tasks.write)
- DELETE https://api.sortd.com/v2/tasks/{id} — Delete a task (scope: tasks.delete)

### Teams
- GET https://api.sortd.com/v2/teams — List teams the API is enabled for (scope: boards.read)
- GET https://api.sortd.com/v2/teams/{id} — Get a team (scope: boards.read)

### Webhooks
- POST https://api.sortd.com/v2/webhooks/subscriptions — Create a webhook subscription (scope: webhooks.manage)
- GET https://api.sortd.com/v2/webhooks/subscriptions — List webhook subscriptions (scope: webhooks.manage)
- DELETE https://api.sortd.com/v2/webhooks/subscriptions/{id} — Delete a webhook subscription (scope: webhooks.manage)
- PATCH https://api.sortd.com/v2/webhooks/subscriptions/{id} — Update or pause a webhook subscription (scope: webhooks.manage)
- POST https://api.sortd.com/v2/webhooks/subscriptions/{id}/rotate-secret — Rotate a webhook signing secret (scope: webhooks.manage)
- POST https://api.sortd.com/v2/webhooks/subscriptions/{id}/test — Send a test ping to a webhook (scope: webhooks.manage)
- GET https://api.sortd.com/v2/webhooks/subscriptions/{id}/deliveries — List a webhook’s delivery log (scope: webhooks.manage)
- POST https://api.sortd.com/v2/webhooks/deliveries/{deliveryId}/replay — Replay a webhook delivery (scope: webhooks.manage)

### Zapier
- POST https://api.sortd.com/v2/zapier/hooks — Zapier REST Hook subscribe (scope: webhooks.manage)
- DELETE https://api.sortd.com/v2/zapier/hooks/{id} — Zapier REST Hook unsubscribe (scope: webhooks.manage)
- GET https://api.sortd.com/v2/zapier/poll — Zapier polling trigger (event feed since cursor) (scope: tasks.read)
- GET https://api.sortd.com/v2/zapier/sample — Sample event payload for Zapier setup (scope: tasks.read)