Tasks

Read, create and move cards on your organization's task board from the CLI, the REST API and MCP.

median tasks create --title "Retry failed exports" --priority high
median tasks status MED-12 in_review

Everybody 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/app

Every 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.