Skip to main content
Return tasks from a workspace’s taskboard. You choose exactly which phases (board columns) to include, and every task in the response uses the same schema regardless of which phase it lives in.

​
Endpoint

GET https://api.median.sh/api/tasks

​
Headers

HeaderRequiredDescription
AuthorizationYes (or apiKey query param)Bearer <your-api-key>

​
Phases

A task’s phase is the board column it sits in. The valid phases, in board order, are: requests · todo · in_progress · ready · shipped · archive

​
Query parameters

ParameterTypeRequiredDescription
phasesstringNoComma-separated list of phases to include, e.g. todo,in_progress. When omitted, tasks from all phases are returned.
phasestring (repeatable)NoAlternative to phases. Repeat the parameter to pass several phases: ?phase=todo&phase=ready. Merged with phases when both are present.
prioritystringNoOnly return tasks with this priority. One of urgent, high, medium, low, none.
labelstringNoOnly return tasks carrying this label.
limitintegerNoMaximum number of tasks to return. Defaults to 200, capped at 500.
apiKeystringNoAPI key, if not sent via the Authorization header.
Passing a phase or priority that isn’t in the list above returns 400.

​
Examples

Fetch every task currently in the todo and in_progress phases: 
curl "https://api.median.sh/api/tasks?phases=todo,in_progress" \
  -H "Authorization: Bearer mdn_live_xxx..."
Fetch all incoming feature requests: 
curl "https://api.median.sh/api/tasks?phases=requests&label=feature" \
  -H "Authorization: Bearer mdn_live_xxx..."
Using the repeatable phase form and a body-less key: 
curl "https://api.median.sh/api/tasks?phase=ready&phase=shipped&apiKey=mdn_live_xxx..."

​
Response

200 OK with the matching tasks. Tasks are ordered by phase (board order), then by their position within the phase. 
{
  "workspace": {
    "id": "k17c9...",
    "name": "Median",
    "prefix": "MED"
  },
  "phases": ["todo", "in_progress"],
  "count": 2,
  "tasks": [
    {
      "id": "j57d2...",
      "taskCode": "MED-196",
      "taskNumber": 196,
      "title": "Export with GitHub Repository Integration",
      "description": null,
      "phase": "todo",
      "status": "todo",
      "priority": "medium",
      "labels": ["feature"],
      "project": "Median V1",
      "order": 0,
      "assignee": { "name": "Abdul", "avatar": "" },
      "assignees": [],
      "source": null,
      "sources": [],
      "createdAt": 1710000000000,
      "updatedAt": 1710003600000
    }
  ]
}

​
Top-level fields

FieldTypeDescription
workspaceobjectThe workspace the API key belongs to (id, name, prefix).
phasesstring[]The phases that were requested. Reflects all phases when none were specified.
countintegerNumber of tasks in tasks.
tasksobject[]The matching tasks, each using the schema below.

​
Task schema

Every entry in tasks has the same fields:
FieldTypeDescription
idstringConvex document id for the task.
taskCodestringHuman-readable code, e.g. MED-196.
taskNumberintegerNumeric portion of the task code.
titlestringTask title.
descriptionstring | nullTask description, or null when empty.
phasestringThe board column the task is in (same value as status).
statusstringAlias of phase, for parity with the CLI and dashboard.
prioritystringurgent, high, medium, low, or none.
labelsstring[]Labels applied to the task.
projectstringProject the task belongs to.
ordernumberSort position of the task within its phase.
assigneeobject | nullLegacy single assignee (name, avatar), or null.
assigneesobject[]Assigned members (userId, name, imageUrl). Empty when none.
sourceobject | nullPrimary origin of the task (platform, url, author), or null.
sourcesobject[]All origins for the task. Empty when none.
createdAtintegerCreation time, Unix milliseconds.
updatedAtinteger | nullLast update time, Unix milliseconds, or null.

​
Errors

See Overview → Error shape.
StatusReason
400An unknown phase or priority was supplied, or limit was not a positive integer.
401API key missing, invalid, or revoked.
405Wrong HTTP method (only GET and OPTIONS are accepted).