Yarnt API Reference

A REST API for working with tickets, projects, comments, and history.

The Yarnt REST API is the HTTP twin of the MCP server: the same operations and permission model, over plain JSON instead of a tool-call protocol. Reach for it from a script, a webhook, or a CI job where an MCP client doesn't fit.

Base URL: https://api.yarnt.app — every endpoint below hangs off it, e.g. https://api.yarnt.app/v1/tickets.

Authentication

Every /v1/* request needs an Authorization header carrying an API key:

Authorization: Bearer yk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Mint a key in Yarnt under Settings → API keys and bind it to a robot — a workspace member representing the script or service using the key. The key acts as that robot: it can see and do exactly what that robot's membership permits, nothing more. Revoke a key at any time from the same settings page; revoked or unknown keys are rejected immediately.

A missing, malformed, invalid, or revoked key gets a 401 with { "error": "..." }.

Errors

Non-2xx responses are always { "error": "<message>" }. The status code tells you what kind of problem it is:

Status	Meaning
`400`	A required field is missing or invalid (e.g. no `title` when creating a ticket).
`401`	Missing, invalid, or revoked API key.
`404`	The ticket, project, or member referenced doesn't exist.

Discovery

Two endpoints help you find your way around:

Request	Returns
`GET /` (no key needed)	A short service description and a pointer to these docs.
`GET /v1` (with a key)	A machine-readable index of every route below, with a one-line description of each.

Endpoints

GET /v1/tickets POST /v1/tickets GET /v1/tickets/:id PATCH /v1/tickets/:id POST /v1/tickets/:id/start|finish|drop GET/POST /v1/tickets/:id/comments GET /v1/tickets/:id/history GET /v1/users GET /v1/projects

GET/v1/tickets

List tickets in the workspace, filtered by list, assignee, or project.

Query param	Values
`list`	`queue` (default) \| `now` \| `next` \| `wishlist` \| `finished` \| `all`
`assignee`	`me` \| `unassigned` \| a user id (see GET /v1/users)
`project`	A project name.

now and next are the two sublists of the queue: now is what's in flight, next is what's waiting. all is every list at once.

Returns — each ticket reports the list it's on; assignee is a user id (or null), which you can resolve to a name via GET /v1/users:

{ "tickets": [ { "id": "...", "title": "...", "list": "next", "assignee": "9eb481fe-..." } ] }

POST/v1/tickets

Create a ticket. title is required.

Body field	Type
`title`	string, required
`project`	string, optional — a project name
`wish`	boolean, optional — file it as a wish instead of the backlog

201: { "id": "...", "wish": false }

GET/v1/tickets/:id

Full detail for one ticket:

{
  "id": "...", "title": "...", "list": "now", "assignee": "9eb481fe-...",
  "project": "...", "labels": ["..."], "blocked": false, "blockedReason": null,
  "createdAt": "...", "updatedAt": "...", "body": "..."
}

PATCH/v1/tickets/:id

Edit any subset of a ticket's fields.

Body field	Type
`title`	string, optional
`body`	string, optional
`assignee`	a user id to set, `null` to unassign, omit to leave unchanged
`project`	string (name) to set, `null` to clear, omit to leave unchanged

Returns { "id": "..." }.

POST/v1/tickets/:id/start

POST/v1/tickets/:id/finish

POST/v1/tickets/:id/drop

Move a ticket through its lifecycle. No body. Each returns { "id": "..." }.

GET/v1/tickets/:id/comments

Returns { "comments": [ { "createdAt": "...", "authorId": "...", "body": "..." } ] }.

POST/v1/tickets/:id/comments

Body: { "body": "..." }, required. 201 on success.

GET/v1/tickets/:id/history

Returns { "history": [ { "createdAt": "...", "kind": "...", "fromVal": "...", "toVal": "..." } ] }.

GET/v1/users

List the workspace members you can assign tickets to. Use a member's id as the assignee value elsewhere. kind is person for people and integration for bots and service accounts.

{ "users": [ { "id": "9eb481fe-...", "name": "Ada", "kind": "person" },
             { "id": "470ed8e7-...", "name": "Claude", "kind": "integration" } ] }

GET/v1/projects

List projects in the workspace.

Query param	Values
`includeArchived`	`true` to include archived projects (default: excluded)

Returns { "projects": [ { "name": "...", "archived": false } ] }.

Examples

Create a ticket

curl -s https://api.yarnt.app/v1/tickets \
  -H "Authorization: Bearer yk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  -H "Content-Type: application/json" \
  -d '{"title": "Fix the flaky deploy step", "project": "infra"}'

{ "id": "b1e2...", "wish": false }

List your in-flight tickets

curl -s "https://api.yarnt.app/v1/tickets?list=now&assignee=me" \
  -H "Authorization: Bearer yk_xxxxxxxxxxxxxxxxxxxxxxxxxxxx"

{ "tickets": [ { "id": "b1e2...", "title": "Fix the flaky deploy step", "list": "now", "assignee": "470ed8e7-..." } ] }

Questions about the API: help@yarnt.app.