# dothings

dothings (https://dothings.fyi) is a team task workspace. This document describes its REST
API, CLI, and MCP server so an LLM can fully operate it.

## Authentication
All API calls use a personal access token:
    Authorization: Bearer dt_live_<token>
Create a token at https://dothings.fyi/settings/tokens. A token acts AS its user — it inherits
that user's project access, and tasks/comments it creates are attributed to them.
Mutations that assign someone, @-mention them, or reply notify that person (in-app and
via push), so they carry real-world side effects beyond the data change.

## Core concepts
A task belongs to exactly one project and sits in one status column.

Status (workflow column):
  think_about — a rough idea or maybe; not committed yet
  todo — committed and ready to be picked up
  doing — actively in progress now
  finished — done (or, for a think_about idea, discarded)

Priority: none, low, medium, high, urgent.

Task body: GitHub-flavored markdown. Recommended shape — a one-line summary, then
"## Context" and an "## Acceptance criteria" checklist using "- [ ]".

Assignees are referenced by username; resolve names via the members endpoint. Labels
are project-scoped and must already exist in a project before being applied.

Link types:
  blocks — source must be done before the target can proceed
  relates — loosely related
  duplicates — source duplicates the target
  implements — source implements the target
  parent — source is the parent of the target (subtask hierarchy)

Comments are markdown, threaded via reply_to_id, and support @username mentions.

## REST API (base https://api.dothings.fyi)
  GET    /v1/whoami
      current user + accessible projects
  PATCH  /v1/whoami
      update your own profile { display_name?, github_username? }
  GET    /v1/api-keys
      your active personal access tokens (self)
  GET    /v1/teammates
      everyone in the workspace (admin)
  POST   /v1/notifications/:id/read
      mark one notification read (self)
  POST   /v1/notifications/read-all
      mark all notifications read (self)
  POST   /v1/messages/read
      mark mention/reply messages read { comment_ids? }
  GET    /v1/projects?q=
      list projects
  POST   /v1/projects
      create a project (admin) { name, description?, color?, member_ids? }
  GET    /v1/projects/:id
      one project (id or slug)
  PATCH  /v1/projects/:id
      rename / set description / archive (admin) { name?, description?, archived? }
  GET    /v1/projects/:id/members
      assignable people
  POST   /v1/projects/:id/members
      add a member (admin) { user_id }
  DELETE /v1/projects/:id/members?user_id=
      remove a member (admin)
  PATCH  /v1/projects/:id/members/:userId
      set a member's project role (admin) { role }
  GET    /v1/projects/:id/labels
      labels
  POST   /v1/projects/:id/labels
      create a label { name, color? }
  POST   /v1/projects/:id/github
      connect a repo (admin) { repo }
  DELETE /v1/projects/:id/github
      disconnect the repo (admin)
  POST   /v1/projects/:id/github/sync
      re-pull GitHub items (member)
  GET    /v1/tasks?project=&status=&priority=&assignee=&label=&q=&limit=&offset=
      list/search tasks (paginated: total/has_more/limit/offset; limit ≤ 500, default 200)
  POST   /v1/tasks
      create a task
  GET    /v1/tasks/:id
      one task, fully hydrated
  PATCH  /v1/tasks/:id
      update fields; assignees/labels replace
  POST   /v1/tasks/:id/move
      move to a status column { status, position? }
  PUT    /v1/tasks/:id/assignees
      replace assignees { assignees[] }
  PUT    /v1/tasks/:id/labels
      replace labels { labels[] }
  DELETE /v1/tasks/:id
      delete a task
  GET    /v1/tasks/:id/comments
      comment thread
  POST   /v1/tasks/:id/comments
      add a comment { body, reply_to_id? }
  PATCH  /v1/comments/:id
      edit a comment (author/admin) { body }
  DELETE /v1/comments/:id
      delete a comment (author/admin)
  POST   /v1/task-links
      link tasks { source_task_id, target_task_id, type }
  PATCH  /v1/task-links/:id
      change a link's type { type }
  DELETE /v1/task-links/:id
      remove a link
  GET    /v1/projects/:id/github-items
      list synced GitHub issues & PRs
  POST   /v1/github-links
      link a GitHub item to a task { task_id, github_item_id }
  DELETE /v1/github-links?task_id=&github_item_id=
      remove a GitHub item link
  GET    /v1/pages?project_id=
      list a project's pages (summaries)
  POST   /v1/pages
      create a page { project_id, type, title?, content? }
  GET    /v1/pages/:id
      one page with full content
  PATCH  /v1/pages/:id
      update a page { title?, content?, archived? }
  DELETE /v1/pages/:id
      delete a page
  POST   /v1/page-links
      link a page to a task { page_id, task_id }
  DELETE /v1/page-links?page_id=&task_id=
      remove a page ↔ task link
  PATCH  /v1/workspace
      rename the workspace (owner) { name }
  GET    /v1/workspace/members
      list workspace members (member)
  PATCH  /v1/workspace/members/:userId
      set a member's workspace role (admin) { role }
  DELETE /v1/workspace/members/:userId
      remove a workspace member (admin)
  POST   /v1/workspace/invites
      invite a member by email (admin) { email, role? }
  POST   /v1/workspace/invites/:id/resend
      resend a pending invite (admin)
  DELETE /v1/workspace/invites/:id
      revoke a pending invite (admin)
  GET    /v1/workspace/github
      list repos the workspace can connect (admin)

Responses are JSON. Errors are { "error": { "code", "message" } } with status codes
401 (bad/revoked token), 403 (no access), 404 (not found), 400 (bad input).

Example:
  curl -H "Authorization: Bearer dt_live_…" https://api.dothings.fyi/v1/whoami
  curl -X POST https://api.dothings.fyi/v1/tasks \
    -H "Authorization: Bearer dt_live_…" -H "content-type: application/json" \
    -d '{"project":"website","title":"Fix footer links","status":"todo","priority":"high"}'

## CLI
Install:  npm i -g justdothings
Auth:     justdothings login   (or set DOTHINGS_TOKEN)
Commands:
  justdothings login
      save an API token (verifies it first)
  justdothings logout
      remove the stored API token
  justdothings whoami
      current user + accessible projects
  justdothings auth status
      show the configured base URL + whether a token is set
  justdothings auth keys
      list your active personal access tokens
  justdothings profile set [--display-name --github-username]
      update your own profile
  justdothings notifications read <id>
      mark one notification read
  justdothings notifications read-all
      mark all your notifications read
  justdothings notifications read-messages [--comment <id>…]
      mark mention/reply messages read
  justdothings projects list
      list projects
  justdothings projects create --name <n> [--description --color --member <id>…]
      create a project (admin)
  justdothings projects rename <idOrSlug> <name>
      rename a project (admin)
  justdothings projects set-description <idOrSlug> <description>
      set a project's description (admin)
  justdothings projects archive <idOrSlug>
      archive a project (admin)
  justdothings projects unarchive <idOrSlug>
      unarchive a project (admin)
  justdothings members list --project <slug>
      list assignable people
  justdothings members add <projectIdOrSlug> <userId>
      add a member (admin)
  justdothings members remove <projectIdOrSlug> <userId>
      remove a member (admin)
  justdothings members set-role <projectIdOrSlug> <userId> <role>
      set a project member's role (admin)
  justdothings teammates list
      list everyone in the workspace (admin)
  justdothings labels list --project <slug>
      list labels
  justdothings labels create --project <slug> --name <n> [--color <hex>]
      create a label
  justdothings tasks list [--project --status --priority --assignee --me --label --search --all]
      list/search tasks (hides finished by default)
  justdothings tasks mine [--project --status --all]
      tasks assigned to you
  justdothings tasks get <id>
      show a task in full (id or share link)
  justdothings tasks create --project <slug> --title <t> [--body|--body-file --status --priority --assignee… --label… --due]
      create a task
  justdothings tasks update <id> [--status --priority --abandoned --add-assignee --remove-label …]
      update a task
  justdothings tasks move <id> <status>
      move between columns
  justdothings tasks start <id>
      move a task to doing
  justdothings tasks done <id>
      move a task to finished
  justdothings tasks open <id>
      open the task in your browser
  justdothings tasks delete <id> --yes
      delete a task
  justdothings comments list <taskId>
      read a comment thread
  justdothings comments add <taskId> "<body>" [--reply-to <id>]
      add a comment
  justdothings comments edit <commentId> "<body>"
      edit a comment (author/admin)
  justdothings comments delete <commentId>
      delete a comment (author/admin)
  justdothings link <src> <tgt> --type <type>
      link two tasks
  justdothings unlink <linkId>
      remove a task link
  justdothings relink <linkId> <type>
      change a task link's type
  justdothings github items <projectIdOrSlug>
      list a project's synced GitHub issues & PRs
  justdothings github link <taskId> <githubItemId>
      link a GitHub issue/PR to a task
  justdothings github link-pr <taskId> <number>
      sync + link a repo PR/issue #number to a task
  justdothings github unlink <taskId> <githubItemId>
      remove a GitHub item link from a task
  justdothings github connect <projectIdOrSlug> <repo>
      connect a repo + initial sync (admin)
  justdothings github disconnect <projectIdOrSlug>
      disconnect the repo + drop items (admin)
  justdothings github sync <projectIdOrSlug>
      re-pull a project's GitHub items (member)
  justdothings github repos list
      list repos the workspace can connect (admin)
  justdothings pages list --project <slug>
      list a project's pages
  justdothings pages get <id>
      show a page with its full content
  justdothings pages create --project <slug> --type <doc|sheet|tweet> [--title --content|--content-file]
      create a page
  justdothings pages update <id> [--title --content|--content-file --archive --unarchive]
      update a page
  justdothings pages delete <id> --yes
      delete a page
  justdothings pages link <pageId> <taskId>
      link a page to a task
  justdothings pages unlink <pageId> <taskId>
      remove a page ↔ task link
  justdothings workspace rename <name>
      rename the workspace (owner)
  justdothings workspace members list
      list workspace members (member)
  justdothings workspace members set-role <userId> <role>
      set a workspace member's role (admin)
  justdothings workspace members remove <userId>
      remove a workspace member (admin)
  justdothings workspace invites send <email> [--role]
      invite someone to the workspace (admin)
  justdothings workspace invites resend <id>
      resend a workspace invite (admin)
  justdothings workspace invites revoke <id>
      revoke a workspace invite (admin)
  justdothings mcp
      run the stdio MCP server
  justdothings install-mcp [--client claude-code|claude-desktop|cursor]
      print the MCP config snippet
  justdothings docs
      open the documentation in your browser
Every command accepts --json for machine output.

## MCP server
Run the stdio server with: justdothings mcp
Add it to a Claude/Cursor client (env carries the token):
  { "mcpServers": { "dothings": { "command": "justdothings", "args": ["mcp"],
    "env": { "DOTHINGS_TOKEN": "dt_live_…" } } } }

Tools:
- whoami — the authenticated user + accessible projects
- update_profile — update your own display name / GitHub handle
- list_api_keys — your active personal access tokens (self)
- mark_notification_read — mark one of your notifications read
- mark_all_notifications_read — mark all your notifications read
- mark_messages_read — mark mention/reply messages read
- list_projects — list/resolve projects (by name or slug)
- create_project — create a project (admin)
- update_project — rename / set description (admin)
- list_teammates — everyone in the workspace (admin); ids feed add_member
- add_member — add a teammate to a project (admin)
- remove_member — remove a teammate from a project (admin)
- list_tasks — list/search tasks with filters
- get_task — one task in full (body, assignees, labels, linked GitHub issues/PRs, task links, image attachments)
- create_task — create a task in a project
- update_task — patch a task; assignees/labels replace the set
- move_task — move a task to a status column
- delete_task — permanently delete a task
- add_comment — add a markdown comment (supports @mentions, replies)
- edit_comment — edit a comment (author or admin)
- delete_comment — delete a comment (author or admin)
- list_comments — read a task's comment thread
- list_labels — labels in a project
- create_label — create a project label
- list_members — people assignable in a project
- link_tasks — create a typed link between two tasks
- unlink_tasks — remove a task link by id
- update_task_link — change a task link's type
- list_github_items — list a project's synced GitHub issues & PRs
- link_github — link a GitHub issue/PR to a task
- unlink_github — remove a GitHub item link from a task
- list_pages — list a project's pages (docs, sheets, tweet drafts)
- get_page — one page in full, incl. its typed content
- create_page — create a page (doc|sheet|tweet) in a project
- update_page — update a page's title / content / archived flag
- delete_page — permanently delete a page
- link_page — link a page to a task (same project)
- unlink_page — remove a page ↔ task link
- connect_github_repo — connect a repo "owner/repo" + initial sync (admin)
- disconnect_github_repo — disconnect the repo + drop synced items (admin)
- sync_github — re-pull a project's GitHub issues & PRs (member)
- archive_project — archive or unarchive a project (admin)
- set_project_member_role — set a member's per-project role: "admin" or "member"
- rename_workspace — rename the token's workspace (owner)
- list_workspace_members — list workspace members with roles (member)
- set_workspace_member_role — set a member's workspace role (admin)
- remove_workspace_member — remove a member from the workspace (admin)
- invite_workspace_member — invite someone to the workspace by email (admin)
- resend_workspace_invite — resend a pending invite email, refresh expiry (admin)
- revoke_workspace_invite — cancel a pending workspace invite (admin)
- list_installable_repos — repos the workspace can connect via GitHub App (admin)

It also exposes a "dothings://conventions" resource with the guidance below.

## Conventions
## Status (the workflow column)
- think_about — a rough idea or "maybe"; not committed yet.
- todo — committed and ready to be picked up (the right default for "add a task").
- doing — actively in progress now.
- finished — done (or, for a think_about idea, discarded).

## Finishing vs. discarding
Moving a task to finished marks it done AND closes any linked GitHub issues. To drop a
think_about idea rather than complete it, set abandoned: true (update_task) so it isn't
counted as a real completion.

## Priority
none, low, medium, high, urgent — set it to reflect real urgency.

## Writing a task body (markdown)
A one-line summary, then "## Context" and an "## Acceptance criteria" checklist (- [ ]).

## Assignees & labels
Assignees are referenced by username (resolve via list_members). Labels are
project-scoped and must exist before use (create with create_label). A task created
directly into (or moved to) doing should always have an assignee — default to the
current user, or the person doing the work. Work in progress needs an owner.

## Linking tasks
blocks, relates, duplicates, implements, parent — pick the type matching the real dependency.

## Resolving a project
Tasks belong to exactly one project. Resolve the user's words to a project via
list_projects; if several could match, ask which one.

## GitHub & task links
get_task returns linked github_items (issues AND pull requests) and task links
(typed relationships to other tasks) — read them to see what a task references.
Every task also carries attachments: image URLs parsed out of its markdown body
(the inline ![](url) images the web composer uploads).

## Pages (in-project docs, sheets & tweet drafts)
A project can hold pages — list_pages/get_page to read, create_page/update_page to write,
link_page to attach one to a task. A page's content shape is keyed by its type:
- doc — a TipTap/ProseMirror node: { type: "doc", content: [ … ] }.
- sheet — a table: { columns: [{ id, name, type, options?, width? }], rows: [{ "<columnId>": cell }] };
  a column type is text | number | date | due | updated | checkbox | select | member.
- tweet — a draft thread: { tweets: [{ id, text, images? }] }.
update_page REPLACES content, so get_page first and send back the full value. The anchored,
Google-Docs-style comment threads on a doc page are web-only (no REST/CLI/MCP surface).

## Notifications & attribution
You act AS the token's user; tasks/comments/completions are attributed to them.
Assigning, @-mentioning, or replying notifies that person (in-app + push) — don't
bulk-assign or mention more people than intended.