Subroutine HTTP API

Every operation this release serves over HTTP, grouped by tag, as its OpenAPI document describes it. The data shapes they take and return are on one page.

A self-hosted, agent-native task and decision tracker for people and coding agents working on complex projects.

GET /v1/meta reports this installation's vocabulary - its statuses, link types, field operators and date grammar - so a client can read them rather than assume them. GET /v1/docs/agent is a guide written for an agent working through this API.

Errors are RFC 9457 problem documents and every one carries a stable code; the codes are part of the public contract and are listed in docs/errors.md.

health

• GET /healthz - Is this process alive?
• GET /readyz - Can this instance serve requests?

mcp

• POST /mcp - Speak MCP to this instance

identity

• GET /signin - Exchange a sign-in link for a browser session
• POST /v1/login-links - Issue a sign-in link for somebody
• GET /v1/me - Who am I, and what may I do?
• DELETE /v1/session - Sign this browser out
• POST /v1/users/{username}/signout - Sign somebody out of every browser they are signed in on

admin

• GET /v1/admin/backups - List the backups this instance holds
• POST /v1/admin/backups - Take a backup

agenda

• GET /v1/agenda - What am I doing today?

calendars

• GET /v1/calendars - List your calendar feeds
• POST /v1/calendars - Create a calendar feed
• DELETE /v1/calendars/{id_or_prefix} - Revoke a calendar feed
• POST /v1/calendars/{id_or_prefix}/reset - Give a feed a new URL
• GET /v1/calendars/{prefix}/{secret}.ics - Fetch a calendar feed

changes

• GET /v1/changes - What changed since you last looked

comments

• PATCH /v1/comments/{comment_id} - Edit your own comment
• DELETE /v1/comments/{comment_id} - Delete a comment
• GET /v1/documents/{id_or_ref}/comments - List a document's comments
• POST /v1/documents/{id_or_ref}/comments - Comment on a document
• GET /v1/projects/{id_or_key}/comments - List a project's comments
• POST /v1/projects/{id_or_key}/comments - Comment on a project
• GET /v1/tasks/{id_or_ref}/comments - List a task's comments
• POST /v1/tasks/{id_or_ref}/comments - Comment on a task

discovery

• GET /v1/docs/agent - A guide written for an agent
• GET /v1/docs/examples - Worked calls, in the order an agent needs them
• GET /v1/meta - What does this installation call things?

documents

• GET /v1/documents - List documents
• POST /v1/documents - Write a document
• GET /v1/documents/{id_or_ref} - Read one document
• PATCH /v1/documents/{id_or_ref} - Change a document
• DELETE /v1/documents/{id_or_ref} - Move a document to the trash
• POST /v1/documents/{id_or_ref}/move - Nest a document under another, or move it to the top level
• POST /v1/documents/{id_or_ref}/restore - Take a document out of the trash

links

• GET /v1/documents/{id_or_ref}/backlinks - List what refers to a document
• GET /v1/documents/{id_or_ref}/governing - List what governs a document
• GET /v1/documents/{id_or_ref}/links - List a document's links
• POST /v1/documents/{id_or_ref}/links - Link a document to something
• DELETE /v1/documents/{id_or_ref}/links/{link_id} - Withdraw a link
• GET /v1/documents/{id_or_ref}/proposed-links - List the links a document's writing suggests
• GET /v1/documents/{id_or_ref}/tree - Walk what has to happen before a document
• GET /v1/tasks/{id_or_ref}/backlinks - List what refers to a task
• GET /v1/tasks/{id_or_ref}/governing - List what governs a task
• GET /v1/tasks/{id_or_ref}/links - List a task's links
• POST /v1/tasks/{id_or_ref}/links - Link a task to something
• DELETE /v1/tasks/{id_or_ref}/links/{link_id} - Withdraw a link
• GET /v1/tasks/{id_or_ref}/proposed-links - List the links a task's writing suggests
• GET /v1/tasks/{id_or_ref}/tree - Walk what has to happen before a task

events

• GET /v1/documents/{id_or_ref}/events - What happened to this document
• GET /v1/documents/{id_or_ref}/journal - What happened to this document, with what was said
• GET /v1/projects/{id_or_key}/events - What happened to this project
• GET /v1/tasks/{id_or_ref}/events - What happened to this task
• GET /v1/tasks/{id_or_ref}/journal - What happened to this task, with what was said

export

• GET /v1/export/comments - Export the comments you can read
• GET /v1/export/documents - Export the documents you can read
• GET /v1/export/events - Export the events you can read
• GET /v1/export/item_types - Export the item types you can read
• GET /v1/export/link_types - Export the link types you can read
• GET /v1/export/links - Export the links you can read
• GET /v1/export/members - Export the members you can read
• GET /v1/export/project_members - Export the project members you can read
• GET /v1/export/projects - Export the projects you can read
• GET /v1/export/saved_views - Export the saved views you can read
• GET /v1/export/statuses - Export the statuses you can read
• GET /v1/export/tags - Export the tags you can read
• GET /v1/export/tasks - Export the tasks you can read
• GET /v1/export/users - Export the users you can read
• GET /v1/export/verifications - Export the verifications you can read
• GET /v1/export/workspace - Export the workspace you can read

instance

• PATCH /v1/instance - Change what this installation is called
• GET /v1/instance/unadministered-workspaces - Workspaces nobody here can administer
• GET /v1/instance/unreachable-projects - Private projects nobody here can reach
• GET /v1/instance/workspaces - Every workspace on this installation

journal

• GET /v1/journal - What happened over a period, with what was said

vocabulary

• GET /v1/link-types - The ways two items can relate here
• POST /v1/link-types - Add a link type
• PATCH /v1/link-types/{which} - Rename a link type
• DELETE /v1/link-types/{which} - Remove a link type
• GET /v1/statuses - The statuses this workspace has
• POST /v1/statuses - Add a status
• PATCH /v1/statuses/{which} - Rename or reposition a status
• DELETE /v1/statuses/{which} - Remove a status
• GET /v1/tags - The tags this workspace has
• POST /v1/tags - Declare a tag
• PATCH /v1/tags/{which} - Rename a tag, or say what it means
• DELETE /v1/tags/{which} - Remove a tag

projects

• GET /v1/projects - List projects
• POST /v1/projects - Create a project
• GET /v1/projects/{id_or_key} - Read one project
• PATCH /v1/projects/{id_or_key} - Change a project
• DELETE /v1/projects/{id_or_key} - Move a project to the trash
• GET /v1/projects/{id_or_key}/members - Who can see this project
• POST /v1/projects/{id_or_key}/members - Let somebody see a private project
• DELETE /v1/projects/{id_or_key}/members/{username} - Stop somebody seeing a private project
• POST /v1/projects/{id_or_key}/move - Move a project in the tree
• POST /v1/projects/{id_or_key}/restore - Take a project out of the trash
• GET /v1/projects/{id_or_key}/settings - What is in force in this project, and where it came from

recurrence

• POST /v1/recurrence/parse - What does this repeat mean?

tasks

• GET /v1/tasks - List tasks
• POST /v1/tasks - Create a task
• GET /v1/tasks/{id_or_ref} - Read one task
• PATCH /v1/tasks/{id_or_ref} - Change a task
• DELETE /v1/tasks/{id_or_ref} - Move a task to the trash
• POST /v1/tasks/{id_or_ref}/claim - Take a task, so nobody else does
• POST /v1/tasks/{id_or_ref}/complete - Mark a task finished
• POST /v1/tasks/{id_or_ref}/move - Move a task under another, or to the top level
• GET /v1/tasks/{id_or_ref}/occurrences - When does this come round?
• POST /v1/tasks/{id_or_ref}/release - Give a task back
• POST /v1/tasks/{id_or_ref}/restore - Take a task out of the trash
• POST /v1/tasks/{id_or_ref}/skip - Let one occurrence of a repeat go by
• GET /v1/tasks/{id_or_ref}/verifications - What has been checked against this task
• POST /v1/tasks/{id_or_ref}/verifications - Record what was checked against this task

tokens

• GET /v1/tokens - List the credentials you can act on
• POST /v1/tokens - Issue a credential
• DELETE /v1/tokens/{id_or_prefix} - Revoke a credential

users

• GET /v1/users - List the accounts on this instance
• POST /v1/users - Create an account
• GET /v1/users/{username} - Read one account
• PATCH /v1/users/{username} - Mark somebody as having left, hand an agent over, or say where you are

views

• GET /v1/views - The views you can see
• POST /v1/views - Save a view
• GET /v1/views/{key} - One saved view
• PATCH /v1/views/{key} - Change a saved view
• DELETE /v1/views/{key} - Forget a saved view

workspaces

• GET /v1/workspaces - List workspaces
• POST /v1/workspaces - Create a workspace
• GET /v1/workspaces/{id_or_slug} - Read one workspace
• PATCH /v1/workspaces/{id_or_slug} - Change a workspace
• DELETE /v1/workspaces/{id_or_slug} - Move a workspace to the trash
• GET /v1/workspaces/{id_or_slug}/members - Who belongs to this workspace
• POST /v1/workspaces/{id_or_slug}/members - Add somebody to this workspace
• PATCH /v1/workspaces/{id_or_slug}/members/{username} - Change what somebody may do in this workspace
• DELETE /v1/workspaces/{id_or_slug}/members/{username} - Take somebody out of this workspace
• POST /v1/workspaces/{id_or_slug}/restore - Take a workspace out of the trash
• GET /v1/workspaces/{id_or_slug}/settings - What is in force in this workspace, and where it came from