# Taskr.dev > Taskr.dev is a task manager built on relative priority. Instead of P1/P2/P3 labels, each task is placed above or below other tasks in its owner's list, and the task at the top is what to work on now. It's designed so people interact with it as little as possible. Teammates in an organization can read and reorder each other's lists; changing someone else's priorities is expected, not an exception. ## MCP server - Taskr.dev's MCP server is `https://www.taskr.dev/mcp` (Streamable HTTP). AI apps such as Claude, ChatGPT, Claude Code and Codex connect to it by having the person sign in to Taskr.dev (OAuth 2.1): no token to copy. The sign-in is discovered from the 401's `WWW-Authenticate` header and `/.well-known/oauth-protected-resource/mcp`. - If you're helping someone connect their AI app, send them to [Use with AI](/ai), which has the steps for each app. - Its tools cover what the JSON API below does: whoami, get_current_task, list_tasks, get_task, search_tasks, get_organization, create_task, update_task, prioritize_task (top, bottom, or above or below another task), unprioritize_task, close_task, reopen_task, add_comment, edit_comment, delete_comment and create_invite_link. - The connection works in one place the person chooses when signing in (an organization, or their Personal tasks), with the same limits as an agent token. A client that can't sign in can send an agent token instead, as `Authorization: Bearer taskr_...`. ## JSON API For scripts and agents without MCP, everything is in the JSON API described by [the OpenAPI file](/openapi.json). The rest of this file is the short version: how to authenticate, the common workflows, and the conventions that aren't obvious from the endpoint names. ## Authentication - Use an agent token: `Authorization: Bearer taskr_...`. The person you're acting for creates it on their profile page (/profile) and gives it to you. - A token acts as that person, locked to the organization they were in when they created it (or their Personal tasks). Call `GET /api/me` first to see who you are and which organization you're in. - A token only reads and changes tasks in its own organization (or Personal), even ones the person can reach elsewhere; others get 403. When prioritizing, the neighbour tasks must be in it too. - Tokens can't switch organizations, create, rename or delete organizations, join or leave them, add or remove members or admins, sign the person out, or delete the account. Those endpoints return 403 for tokens. A token can revoke itself (`POST /api/revoke_agent_token` with its own `token_id`), but no other token. You can create invite links. - A token stops working when it's revoked, when the person signs out, or when they leave the token's organization. Then you get 401. - Never put the token in a URL; `session_id` is ignored in query strings. ## Requests and responses - GET parameters go in the query string. POST takes a JSON body with `Content-Type: application/json`. - Responses are JSON. Actions with nothing to return give `{"ok": true}`. Errors give `{"error": "message"}` with a 4xx/5xx status: 400 bad input, 401 no/expired session, 403 not allowed, 404 not found, 409 conflicts with the current state. ## Conventions - Times are Unix timestamps in seconds. A deadline of 0 means no deadline. Send deadlines as `YYYY-MM-DD`, from 2000-01-01 to 2999-12-31. - Estimates are in days, from 0 to 10000. - If an organization's bill stays unpaid, it becomes read-only until it's paid: its tasks can still be read and searched, but creating or changing them is refused with 403 and a message saying why. `GET /api/org` shows `read_only` and `billing_status`. Personal is always free. - Task descriptions and comments keep line breaks as ordinary newline characters (`\n` in JSON). `\r\n` and `\r` are stored as `\n`. - `priority`: lower is more important, and it only compares tasks in the same owner's list. Use the order of `GET /api/get_tasks`, not the number. - A task is in exactly one state: prioritized (`prioritized: 1`), unprioritized (`prioritized: 0, done: 0`), or done (`done: 1`). ## Common workflows - **What should I work on?** `GET /api/get_tasks` lists the prioritized tasks, most important first. The first one is the current task. - **See everything.** `GET /api/get_tasks`, `GET /api/get_unprioritized_tasks` and `GET /api/get_done_tasks` are the three lists. Add `?user_id=` to read a teammate's lists in your organization. The done list only grows: read it a page at a time with `?limit=100`, then `&after=` the last task's `id` for the next page, until a page comes back with fewer than `limit`. `GET /api/org` returns the organization's members and all of its tasks; with `?limit=100`, only the newest 100 done ones (`more_done` says if there are older ones), and `GET /api/get_org_done_tasks` pages through the rest the same way as the done list. - **Read one task.** `GET /api/get_task?task_id=...` returns the task and its comments, newest first. - **Add a task.** `POST /api/create_task` with `title`, and optionally `description`, `estimate` and `deadline`. It starts unprioritized; prioritize it next. - **Prioritize a task.** `POST /api/prioritize_task` with `inserted_id` (the task) and neighbours `id1`, `id2`, `id3` from its owner's current list: - At the top: `id1` = the task, `id2` = `id3` = the current top task. - At the bottom: `id1` = `id2` = the current bottom task, `id3` = the task. - Between two adjacent tasks: `id1` = the one above, `id2` = the task, `id3` = the one below. - If the list is empty: all three null. - **Edit a task.** `POST /api/update_task_details` with `task_id` and only the fields you're changing (title, description, estimate, deadline); the rest are left as they are. An empty `deadline` removes it, an empty `description` clears it, and the title can't be empty. Add `owner` to hand an organization task to another member. - **Finish, reopen, or unprioritize.** `POST /api/close_task` marks it done. `POST /api/unprioritize_task` takes an open task out of the prioritized list (done tasks get 409). `POST /api/reopen_task` reopens a done task; it comes back unprioritized. - **Comment.** `POST /api/comment_task` with `task_id` and `comment` (not empty or only whitespace). - **Edit or delete your own comment.** `POST /api/edit_comment` with `comment_id` (the comment's `key` from `get_task`) and the new `comment`, or `POST /api/delete_comment` with `comment_id`. Someone else's comment is 403. An edited comment keeps its time and gets an `edited` timestamp. - **Search.** `GET /api/search?q=...` searches open tasks in your organization (or Personal) by whole words, best match first. - **Invite people.** `POST /api/invite` (admins only) returns `invite_path`; send each person this site's origin plus that path. Opening it shows which organization it's for and a Join button (signed out, it goes to sign-up, which also links to sign-in, first); they join by pressing Join, not by opening the link. Each link works once and expires after 7 days. Create one per person. ## Docs - [Use with AI](/ai): connecting Claude, ChatGPT and other AI apps, for people. - [OpenAPI description](/openapi.json): every endpoint, parameter, response and error. ## Pages For reading as a person would; the API is easier. - [Home](/home): the current top task and the task lists. - [All tasks](/tasks): prioritized, unprioritized and done columns; /tasks/{user_id} for a teammate. - [A task](/task/{task_id}), [prioritize a task](/prioritize/{task_id}), [search](/search?q={text}). - [Organization](/org), [organization settings](/org_settings), [create an organization](/create_org). - [Profile](/profile): display name, organizations and agent tokens; /profile/{user_id} for a teammate.