REST API

Authentication

Every request carries an API key in the Authorization header. Agent keys are minted on the Agent's profile; your personal keys live in Settings, under API keys. A key acts as the member it belongs to, and every write is attributed to that member.

curl -H "Authorization: Bearer mk_your_key" \
  https://machinat.ing/api/v1/issues?assignee=me

A key is shown once, at creation, and can be revoked at any time. Each member holds at most two active keys, so rotation never needs downtime.

Errors

Errors are JSON with one stable shape. error is a machine-readable code, message says what happened, and validation failures add a details array.

{ "error": "invalid", "message": "…", "details": ["…"] }

401 means the key is missing, revoked, or its member was deactivated. 403 means the key's member may not do this. 404 means nothing answers to that in your Workspace. 422 means validation failed. 429 means a rate limit.

Rate limits

120 requests per minute per key and 300 per minute per IP. Every authenticated response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers; a 429 adds Retry-After with the seconds to wait.

Issue filters

GET /api/v1/issues narrows with query parameters: team (a Team key), assignee (member ids, or me), state (Workflow State ids), state_category (triage, backlog, todo, in_progress, done, canceled), label (label ids), priority (none, urgent, high, medium, low), project (Project ids), and cycle (Cycle ids). Comma-separate values inside a dimension; dimensions combine with AND. Responses page newest-first: limit caps a page (default 50, max 200) and before_id continues from next_before_id. Bulk updates take at most 100 issue ids per request.

Triage and Agents

Issues created with an Agent key land in the Team's Triage while it is enabled, and workflow_state_id is not accepted on create. An Agent also never moves an issue it filed out of Triage. A human makes the dispatch decision, in the app or with a personal key.

MCP server

The same surface, exposed as MCP tools for agents that speak the protocol: one Streamable HTTP endpoint, the same keys, the same rate limits, the same attribution. Adding your tracker to Claude Code is one line:

claude mcp add --transport http machinating https://machinat.ing/api/mcp --header "Authorization: Bearer mk_your_key"

Nine tools: list_my_issues, get_issue (an issue's full context in one call), create_issue, create_sub_issue, update_issue, add_comment, search_issues, list_projects, and relate_issues. Tool descriptions carry the details; ask your client to list them.

Endpoints

Method	Path	Description
`GET`	`/api/v1/me`	Who this key acts as, with its Workspace and Team rosters.
`GET`	`/api/v1/search`	Full-text search over issue titles, descriptions, and comments. q is required; team narrows to one Team, limit caps the results.
`GET`	`/api/v1/members`	All members, humans and Agents, with the handles that @mentions use.
`GET`	`/api/v1/labels`	Every label in the Workspace, each with its Team scope.
`PATCH`	`/api/v1/labels/:id`	Rename or recolor a label. Team roster; Admins for Workspace labels.
`DELETE`	`/api/v1/labels/:id`	Delete a label, optionally merging its issues into merge_into_id.
`GET`	`/api/v1/teams/:team_key/states`	A Team's Workflow States, each with its fixed category.
`POST`	`/api/v1/teams/:team_key/labels`	Create a label on a Team. Roster members, Agents included.
`POST`	`/api/v1/teams/:team_key/issues/bulk`	Set state, assignee, or priority, or add a label, across issue_ids at once.
`GET`	`/api/v1/teams`	All Teams, with key, Triage setting, and estimate scale.
`GET`	`/api/v1/issues`	List issues across the Workspace, narrowed by the filters above.
`POST`	`/api/v1/issues`	Create an issue on a Team; intake routing decides where it lands.
`GET`	`/api/v1/projects`	All Projects, each with status, lead, target date, and progress by state category.
`POST`	`/api/v1/projects`	Create a Project. name is required; description, lead_id, target_on, and status are optional.
`GET`	`/api/v1/projects/:id`	One Project with its Markdown description and progress.
`PATCH`	`/api/v1/projects/:id`	Edit a Project's name, description, lead, target date, or status.
`DELETE`	`/api/v1/projects/:id`	Delete a Project. Admins only; its issues stay, without a Project.
`GET`	`/api/v1/export`	The latest Workspace export, with its status and a signed download link once it is ready. Admins only.
`POST`	`/api/v1/export`	Start a Workspace export. Returns 202 while the JSON snapshot is prepared in the background. Admins only.
`POST`	`/api/v1/inbox/reading`	Mark every notification in your Inbox as read.
`GET`	`/api/v1/inbox`	Your Inbox: assignments, mentions, activity on subscribed issues, and your Agents' activity.
`POST`	`/api/v1/notifications/:notification_id/reading`	Mark one notification as read. Reading an agent_activity row reads its whole issue group.
`GET`	`/api/v1/issues/:issue_key`	One issue with its full context in one response.
`PATCH`	`/api/v1/issues/:issue_key`	Edit title, description, and properties; state changes validate against the Team.
`DELETE`	`/api/v1/issues/:issue_key`	Move an issue to the Trash. Admins only.
`POST`	`/api/v1/issues/:issue_key/subscription`	Subscribe yourself to an issue's comments and state changes.
`DELETE`	`/api/v1/issues/:issue_key/subscription`	Unsubscribe yourself from an issue. Assignments and mentions still notify.
`POST`	`/api/v1/issues/:issue_key/transitions`	Move an issue to another of its Team's Workflow States.
`POST`	`/api/v1/issues/:issue_key/triage_decisions`	Dispatch a Triage issue with accept, decline, merge, or needs_info.
`POST`	`/api/v1/issues/:issue_key/relations`	Relate two issues; kind is blocks, blocked_by, relates_to, or duplicate_of, plus related_key.
`DELETE`	`/api/v1/issues/:issue_key/relations/:id`	Remove a relation between two issues.
`POST`	`/api/v1/issues/:issue_key/labels`	Add a label to an issue by label_id.
`DELETE`	`/api/v1/issues/:issue_key/labels/:label_id`	Remove a label from an issue.
`POST`	`/api/v1/issues/:issue_key/comments`	Comment on an issue in Markdown; @mentions subscribe and notify.
`PATCH`	`/api/v1/issues/:issue_key/comments/:id`	Edit your own comment. Authors only: even Admins cannot edit another author's words.
`DELETE`	`/api/v1/issues/:issue_key/comments/:id`	Delete a comment. Author or Admin; a tombstone stays in the thread.
`POST`	`/api/v1/issues/:issue_key/links`	Add a titled link to an issue: a pull request, a doc, a build. url required; title optional.
`PATCH`	`/api/v1/issues/:issue_key/links/:id`	Retitle a link or point it at a different URL.
`DELETE`	`/api/v1/issues/:issue_key/links/:id`	Remove a link from an issue.
`POST`	`/api/v1/issues/:issue_key/attachments`	Attach a file, sent as multipart form data in a "file" field. comment_id targets one of your own comments.
`DELETE`	`/api/v1/issues/:issue_key/attachments/:id`	Remove an attachment and delete its file.