Tasks
Read, create and move cards on your organization's task board from the CLI, the REST API and MCP.
Updated Oct 1, 20263 minute read
median tasks create --title "Retry failed exports" --priority high
median tasks status MED-12 in_reviewEverybody in the organization can read and move cards. Changing the board settings needs an admin or owner. A MEDIAN_KEY acts as an admin.
Reference a card
| Pass | Example |
|---|---|
| The key | MED-12. Case does not matter, so med-12 works |
| The number | 12 |
| The id | k97a2fh3m1x8p4qv6r2t9w5y |
| Key rule | Detail |
|---|---|
| Prefix | Up to 8 letters or numbers, starting with a letter. Stored in capitals |
| Default prefix | The first three letters or numbers of the organization slug, so acme-support gives ACM. TASK when that does not start with a letter |
| Numbers | Counted per organization from 1. A deleted card's number is not reused |
| Changing the prefix | Every key on the board changes with it |
| Field | Limit |
|---|---|
| Title | 160 characters. Longer titles are cut. Runs of whitespace become one space |
| Description | 10,000 characters. Longer descriptions are cut |
| Code | Status | When |
|---|---|---|
task_not_found | 404 | No such card, or a key with another prefix. The message names the right one, like "Tasks here are MED-1, MED-2, and so on, so ABC-4 is not one of them." |
title_required | 400 | The title is empty |
not_a_member | 400 | The assignee is not in the organization |
key_prefix_invalid | 400 | "Use up to eight letters or numbers, starting with a letter." |
signal_not_found | 404 | Adopting a signal that is not in your organization |
already_a_task | 409 | Adopting a signal that is already a card. The message names the card, like "That is already MED-4." |
not_a_request | 409 | Declining a card that is not in requests |
Columns
| Status | Holds | Its signal becomes |
|---|---|---|
requests | What customers asked for, before anybody decided | open |
planned | Agreed, not started | planned |
in_progress | Being worked on | in progress |
in_review | Waiting on a review | in review |
done | Finished, newest first | done |
A new card goes on top of its column, in planned unless you pass a status. A moved card goes to the bottom of its new column unless you pass place: "top".
Moving a card that came from a signal moves the signal to the matching status. Moving it to done messages everyone who reported it, in the conversation they reported it from. A card with a Linear or GitHub issue moves that issue too.
Endpoints
| Endpoint | Description |
|---|---|
GET /v1/tasks | One column, or the whole board. Up to 100 cards |
POST /v1/tasks | Create a card |
GET /v1/tasks/{task} | One card, with every commit and pull request on it |
PATCH /v1/tasks/{task} | Change the title, description, priority, assignee or status |
DELETE /v1/tasks/{task} | Delete a card. Its tracker issues stay |
GET /v1/tasks/requests | Open signals not yet on the board. Up to 60 |
POST /v1/tasks/requests/{id} | Put a request on the board |
POST /v1/tasks/{task}/decline | Decline a request. The card goes and its signal is declined. Nobody is messaged |
GET /v1/tasks/settings | The prefix, trackers, watched repositories and code switch |
PATCH /v1/tasks/settings | Change the prefix, the code switch, the GitHub issue repository or the watched repositories. Admins and owners |
curl "https://api.median.sh/v1/tasks?status=in_progress" \
-H "Authorization: Bearer $MEDIAN_KEY"In a PATCH, null clears the priority or the assignee. An assignee is an email address or a user id.
CLI
median tasks list --status planned --assignee dana@acme.com
median tasks get MED-12
median tasks create --title "Retry failed exports" --file ./notes/exports.md
median tasks status MED-12 in_progress --place top
median tasks priority MED-12 none
median tasks assign MED-12 dana@acme.com
median tasks requests
median tasks adopt <signal id> --status planned
median tasks decline MED-14
median tasks settings --prefix ACME --code off
median tasks settings --issues acme/app --watch acme/appEvery flag is in the CLI reference. Install and sign in with the CLI guide.
MCP
median.tasks is a namespace on the MCP server:
const review = await median.tasks.list({ status: "in_review" });
const stale = review.filter((t) => Date.now() - t.updatedAt > 7 * 864e5);
for (const task of stale) {
await median.tasks.update({ task: task.key, priority: "high" });
}
return stale.map((t) => t.key);What moves on its own
| When | Then |
|---|---|
| Median is connected to Linear and a team is picked | A card gets a Linear issue when it is created, edited or moved while it is in planned, in_progress or in_review. The issue's state follows the card |
A signal with no card moves to planned, in progress, in review or done | A card is made in the matching column |
| A signal with a card moves forward | The card moves forward with it. It never moves back, except that reopening the signal sends the card to requests. Declining the signal leaves the card alone |
--code off stops commits and pull requests from moving cards.