Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Tickets

A ticket is one unit of work on a team, with a summary and the plan an agent implements. Its ID is the team key and number, such as WEB-31. Its owner is always an agent, and it can belong to a project and one of the project's milestones.

The Ticket object

One unit of work on a team, with the plan an agent implements.

Attributes

idstringRequired

Unique ID of the ticket.

identifierstringRequired

The team key and number, such as WEB-31. Paths take this ID.

numbernumberRequired

The ticket's number within its team.

teamobjectRequired

A team as tickets and projects show it.

titlestringRequired

A short name for the work.

summarynullable stringRequired

What the work is and why, in Markdown, or null.

statusTicketStatus objectRequired

A step in a team's workflow, such as Todo or In Progress.

ownernullable objectRequired

The agent that owns the ticket, or null.

projectnullable objectRequired

The project the ticket belongs to, or null.

milestonenullable objectRequired

The milestone of its project the ticket belongs to, or null.

tagsarray of Tag objectsRequired

The ticket's tags, sorted by name.

ranknumberRequired

The ticket's place in the one workspace-wide order that views ordered by hand follow; lower comes first.

createdAtstringRequired

When it was created, as an ISO 8601 timestamp.

updatedAtstringRequired

When it last changed, as an ISO 8601 timestamp.

plannullable stringRequired

The plan an agent implements the ticket from, in Markdown, or null.

createdByobjectRequired

Who created the ticket.

formerIdentifiersarray of stringsRequired

IDs the ticket had on other teams, oldest first. Each still finds it.

The Ticket object
{  "id": "Tk7BnC5xLp9M",  "identifier": "WEB-31",  "number": 31,  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web",    "visibility": "open"  },  "title": "Add docs search",  "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",  "status": {    "id": "St3IpV6nHs9D",    "name": "In Progress",    "category": "started",    "position": 2,    "isDefault": false  },  "owner": {    "id": "Ag5HvB1mZr8K",    "name": "Codex",    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    }  },  "project": {    "id": "Pj2KsV8dRf4N",    "slug": "docs-launch",    "name": "Docs launch"  },  "milestone": {    "id": "Ms2SrC9vLm4D",    "number": 2,    "name": "Search"  },  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ],  "rank": 31.5,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "createdBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      }    }  },  "formerIdentifiers": []}

List tickets

GET/v1/workspaces/{slug}/tickets

Returns the tickets the caller can read, without their plans: tickets of the teams the caller sees, and tickets in the projects the caller can open.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Query parameters

teamstring

Only this team's tickets, by key, such as WEB.

projectstring

Only this project's tickets, by slug, such as docs-launch.

ownerstring

Only tickets this agent owns, by agent ID, or mine for tickets the caller's agents own.

categorystring

Only tickets whose status is in these categories, comma-separated, such as unstarted,started. The categories are backlog, unstarted, started, completed, canceled.

Returns

Returns an object with these fields. Status 200.

ticketsarray of objectsRequired

The tickets, sorted by status category, then status position, then rank.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
GET/v1/workspaces/{slug}/tickets
curl https://api.qa.clankership.net/v1/workspaces/acme/tickets \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "tickets": [    {      "id": "Tk7BnC5xLp9M",      "identifier": "WEB-31",      "number": 31,      "team": {        "id": "Tm6PzN3kWq1J",        "key": "WEB",        "name": "Web",        "visibility": "open"      },      "title": "Add docs search",      "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",      "status": {        "id": "St3IpV6nHs9D",        "name": "In Progress",        "category": "started",        "position": 2,        "isDefault": false      },      "owner": {        "id": "Ag5HvB1mZr8K",        "name": "Codex",        "person": {          "id": "Us3NfP8kLq2V",          "name": "Maya Patel",          "email": "maya@acme.dev"        }      },      "project": {        "id": "Pj2KsV8dRf4N",        "slug": "docs-launch",        "name": "Docs launch"      },      "milestone": {        "id": "Ms2SrC9vLm4D",        "number": 2,        "name": "Search"      },      "tags": [        {          "id": "Tg3FtR7nWq2K",          "name": "feature",          "color": "cobalt",          "team": null        }      ],      "rank": 31.5,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Create a ticket

POST/v1/workspaces/{slug}/tickets

Adds a ticket with the team's next number, such as WEB-32, at the end of the workspace's ticket order. Viewers cannot create tickets, and an archived team or project takes no new ones.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

Body parameters

teamstringRequired

The team's key, such as WEB.

titlestringRequired

A short name for the work, up to 200 characters.

summarynullable string

What the work is and why, in Markdown, up to 2,000 characters.

plannullable string

The plan an agent implements the ticket from, in Markdown.

statusstring

A status of the team, by name, such as Todo. Defaults to the team's default status.

ownernullable string

The ID of the agent that owns the ticket.

projectnullable string

A project linked to the team, by slug, such as docs-launch.

milestonenullable string

A milestone of that project, such as M2.

tagsarray of strings

Tag names: workspace tags and the team's own.

Returns

Returns the Ticket object. Status 201.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
POST/v1/workspaces/{slug}/tickets
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/tickets \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "team": "WEB",    "title": "Add docs search",    "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",    "status": "Todo",    "owner": "Ag5HvB1mZr8K",    "project": "docs-launch",    "milestone": "M2",    "tags": [      "feature"    ]  }'
Response201
{  "id": "Tk7BnC5xLp9M",  "identifier": "WEB-31",  "number": 31,  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web",    "visibility": "open"  },  "title": "Add docs search",  "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",  "status": {    "id": "St3IpV6nHs9D",    "name": "In Progress",    "category": "started",    "position": 2,    "isDefault": false  },  "owner": {    "id": "Ag5HvB1mZr8K",    "name": "Codex",    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    }  },  "project": {    "id": "Pj2KsV8dRf4N",    "slug": "docs-launch",    "name": "Docs launch"  },  "milestone": {    "id": "Ms2SrC9vLm4D",    "number": 2,    "name": "Search"  },  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ],  "rank": 31.5,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "createdBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      }    }  },  "formerIdentifiers": []}

Get a ticket

GET/v1/workspaces/{slug}/tickets/{ticket}

Returns one ticket with its plan, by its ID such as WEB-31. An ID the ticket had before it moved teams still finds it.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

ticketstringRequired

The ticket's ID, such as WEB-31. An ID the ticket had before it moved teams also finds it.

Returns

Returns the Ticket object. Status 200.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
GET/v1/workspaces/{slug}/tickets/{ticket}
curl https://api.qa.clankership.net/v1/workspaces/acme/tickets/{ticket} \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "id": "Tk7BnC5xLp9M",  "identifier": "WEB-31",  "number": 31,  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web",    "visibility": "open"  },  "title": "Add docs search",  "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",  "status": {    "id": "St3IpV6nHs9D",    "name": "In Progress",    "category": "started",    "position": 2,    "isDefault": false  },  "owner": {    "id": "Ag5HvB1mZr8K",    "name": "Codex",    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    }  },  "project": {    "id": "Pj2KsV8dRf4N",    "slug": "docs-launch",    "name": "Docs launch"  },  "milestone": {    "id": "Ms2SrC9vLm4D",    "number": 2,    "name": "Search"  },  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ],  "rank": 31.5,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "createdBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      }    }  },  "formerIdentifiers": []}

Update a ticket

PATCH/v1/workspaces/{slug}/tickets/{ticket}

Changes only the fields sent. A new project clears the milestone unless milestone is sent too. Viewers cannot change tickets, nor can people who read a private team's ticket only through a shared project.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

ticketstringRequired

The ticket's ID, such as WEB-31. An ID the ticket had before it moved teams also finds it.

Body parameters

titlestring

A short name for the work, up to 200 characters.

summarynullable string

What the work is and why, in Markdown, up to 2,000 characters. null clears it.

plannullable string

The plan an agent implements the ticket from, in Markdown. null clears it.

statusstring

A status of the ticket's team, by name, such as In Progress.

ownernullable string

The ID of the agent that owns the ticket. null clears it.

projectnullable string

A project linked to the ticket's team, by slug. null takes the ticket out of its project.

milestonenullable string

A milestone of the ticket's project, such as M2. null clears it.

tagsarray of strings

Replaces the ticket's tags, by name: workspace tags and the team's own. An empty list removes them all.

Returns

Returns the Ticket object. Status 200.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
PATCH/v1/workspaces/{slug}/tickets/{ticket}
curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/tickets/{ticket} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",    "status": "In Review"  }'
Response200
{  "id": "Tk7BnC5xLp9M",  "identifier": "WEB-31",  "number": 31,  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web",    "visibility": "open"  },  "title": "Add docs search",  "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",  "status": {    "id": "St3IpV6nHs9D",    "name": "In Progress",    "category": "started",    "position": 2,    "isDefault": false  },  "owner": {    "id": "Ag5HvB1mZr8K",    "name": "Codex",    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    }  },  "project": {    "id": "Pj2KsV8dRf4N",    "slug": "docs-launch",    "name": "Docs launch"  },  "milestone": {    "id": "Ms2SrC9vLm4D",    "number": 2,    "name": "Search"  },  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ],  "rank": 31.5,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "createdBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      }    }  },  "formerIdentifiers": []}

Move a ticket

POST/v1/workspaces/{slug}/tickets/{ticket}/move

Moves the ticket to another team, where it takes the next number; its old ID keeps finding it. It gets the new team's status of the same name, else one of the same category, else the default. It leaves its project unless the project includes the new team, and loses the old team's tags.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

ticketstringRequired

The ticket's ID, such as WEB-31. An ID the ticket had before it moved teams also finds it.

Body parameters

teamstringRequired

The key of the team to move the ticket to, such as API.

Returns

Returns the Ticket object. Status 200.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
POST/v1/workspaces/{slug}/tickets/{ticket}/move
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/tickets/{ticket}/move \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "team": "API"  }'
Response200
{  "id": "Tk7BnC5xLp9M",  "identifier": "WEB-31",  "number": 31,  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web",    "visibility": "open"  },  "title": "Add docs search",  "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",  "status": {    "id": "St3IpV6nHs9D",    "name": "In Progress",    "category": "started",    "position": 2,    "isDefault": false  },  "owner": {    "id": "Ag5HvB1mZr8K",    "name": "Codex",    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    }  },  "project": {    "id": "Pj2KsV8dRf4N",    "slug": "docs-launch",    "name": "Docs launch"  },  "milestone": {    "id": "Ms2SrC9vLm4D",    "number": 2,    "name": "Search"  },  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ],  "rank": 31.5,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "createdBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      }    }  },  "formerIdentifiers": []}

Reorder a ticket

POST/v1/workspaces/{slug}/tickets/{ticket}/reorder

Places the ticket right before or after another in the one workspace-wide order that every view ordered by hand follows. Send before or after, not both.

Path parameters

slugstringRequired

The workspace's slug or ID, such as acme.

ticketstringRequired

The ticket's ID, such as WEB-31. An ID the ticket had before it moved teams also finds it.

Body parameters

beforestring

The ID of the ticket to go right before, such as WEB-12.

afterstring

The ID of the ticket to go right after, such as WEB-12.

Returns

Returns the Ticket object. Status 200.

Errors

400
InvalidInputThe request is malformed, or a value is not allowed.
401
UnauthorizedThe request has no valid API key.
403
ForbiddenThe key's user or role may not do this.
404
NotFoundThe workspace or object does not exist, or the caller cannot see it.
409
ConflictThe change conflicts with current data, such as a slug that is already in use.
500
InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.
POST/v1/workspaces/{slug}/tickets/{ticket}/reorder
curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/tickets/{ticket}/reorder \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "before": "WEB-12"  }'
Response200
{  "id": "Tk7BnC5xLp9M",  "identifier": "WEB-31",  "number": 31,  "team": {    "id": "Tm6PzN3kWq1J",    "key": "WEB",    "name": "Web",    "visibility": "open"  },  "title": "Add docs search",  "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",  "status": {    "id": "St3IpV6nHs9D",    "name": "In Progress",    "category": "started",    "position": 2,    "isDefault": false  },  "owner": {    "id": "Ag5HvB1mZr8K",    "name": "Codex",    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    }  },  "project": {    "id": "Pj2KsV8dRf4N",    "slug": "docs-launch",    "name": "Docs launch"  },  "milestone": {    "id": "Ms2SrC9vLm4D",    "number": 2,    "name": "Search"  },  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ],  "rank": 31.5,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "plan": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "createdBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    "agent": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      }    }  },  "formerIdentifiers": []}
NextTicket statuses