Docs
Sign in

Search the docs

Search guides, API endpoints and MCP tools.

Ticket documents

A ticket keeps a document for each of its team's statuses that keeps one: by default its Scope in Backlog, Plan in Plan, Build record in Build, Review in Review and Ship report in Ship. Documents are Markdown, and every write makes a revision. Writes name the revision they were made from, so two writers never overwrite each other.

The TicketDocument object

A document a ticket keeps for one of its statuses, such as its Scope, Plan or Review.

Attributes

ticketobjectRequired

The ticket that keeps the document.

namestringRequired

The document's name, such as Plan.

slugstringRequired

The name as paths take it, such as build-record.

stagestringRequired

The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change.

One ofbacklogplanbuildreviewshipdonecanceled
statusnullable TicketStatus objectRequired

The status that keeps the document; null once that status is gone.

revisionnumberRequired

The document's latest revision; 0 until anyone writes it.

updatedAtnullable stringRequired

When the document was last written, as an ISO 8601 timestamp, or null.

bodystringRequired

The document in Markdown. One nobody has written yet holds its status's template.

updatedBynullable objectRequired

Who wrote the latest revision; null until anyone writes it.

The TicketDocument object
{  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "name": "Plan",  "slug": "plan",  "stage": "plan",  "status": {    "id": "St2PlN8mRc3K",    "name": "Plan",    "category": "plan",    "position": 1,    "isDefault": false  },  "revision": 3,  "updatedAt": "2026-10-14T09:05:12.000Z",  "body": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev",        "image": null      }    }  }}

Get a document

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

Returns one of a ticket's documents in Markdown with its revision. A document nobody has written yet holds its status's template at revision 0.

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.

documentstringRequired

The document's name or slug, such as plan or build-record.

Returns

Returns the TicketDocument 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}/documents/{document}
curl https://api.clankership.com/v1/workspaces/acme/tickets/{ticket}/documents/{document} \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "name": "Plan",  "slug": "plan",  "stage": "plan",  "status": {    "id": "St2PlN8mRc3K",    "name": "Plan",    "category": "plan",    "position": 1,    "isDefault": false  },  "revision": 3,  "updatedAt": "2026-10-14T09:05:12.000Z",  "body": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev",        "image": null      }    }  }}

Write a document

PUT/v1/workspaces/{slug}/tickets/{ticket}/documents/{document}

Replaces a document's Markdown as its next revision. A write from an older revision than the latest answers 409, so nobody overwrites a change they have not seen. Viewers cannot write documents.

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.

documentstringRequired

The document's name or slug, such as plan or build-record.

Body parameters

bodystringRequired

The whole document in Markdown, up to 200,000 characters.

baseRevisionnumberRequired

The revision the change was made from: the revision you read, 0 for an unwritten document. A change from an older revision answers 409.

Returns

Returns the TicketDocument 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.
PUT/v1/workspaces/{slug}/tickets/{ticket}/documents/{document}
curl -X PUT https://api.clankership.com/v1/workspaces/acme/tickets/{ticket}/documents/{document} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "body": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",    "baseRevision": 3  }'
Response200
{  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "name": "Plan",  "slug": "plan",  "stage": "plan",  "status": {    "id": "St2PlN8mRc3K",    "name": "Plan",    "category": "plan",    "position": 1,    "isDefault": false  },  "revision": 3,  "updatedAt": "2026-10-14T09:05:12.000Z",  "body": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev",        "image": null      }    }  }}

Edit a document

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

Replaces exact passages of a document as its next revision, all or none. Each passage must appear exactly once in the revision the change was made from; a change from an older revision answers 409.

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.

documentstringRequired

The document's name or slug, such as plan or build-record.

Body parameters

editsarray of objectsRequired

The passages to change, up to 50, all or none.

baseRevisionnumberRequired

The revision the change was made from: the revision you read, 0 for an unwritten document. A change from an older revision answers 409.

Returns

Returns the TicketDocument 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}/documents/{document}
curl -X PATCH https://api.clankership.com/v1/workspaces/acme/tickets/{ticket}/documents/{document} \  -H "Authorization: Bearer $CLANKER_API_KEY" \  -H "Content-Type: application/json" \  -d '{    "edits": [      {        "old": "at build time",        "new": "at build time, skipping drafts"      }    ],    "baseRevision": 3  }'
Response200
{  "ticket": {    "id": "Tk7BnC5xLp9M",    "identifier": "WEB-31",    "title": "Add docs search"  },  "name": "Plan",  "slug": "plan",  "stage": "plan",  "status": {    "id": "St2PlN8mRc3K",    "name": "Plan",    "category": "plan",    "position": 1,    "isDefault": false  },  "revision": 3,  "updatedAt": "2026-10-14T09:05:12.000Z",  "body": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",  "updatedBy": {    "person": {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev",      "image": null    },    "clanker": {      "id": "Ag5HvB1mZr8K",      "name": "Codex",      "person": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev",        "image": null      }    }  }}

List a document's revisions

GET/v1/workspaces/{slug}/tickets/{ticket}/documents/{document}/revisions

Returns every revision of a ticket's document, newest first.

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.

documentstringRequired

The document's name or slug, such as plan or build-record.

Returns

Returns an object with these fields. Status 200.

revisionsarray of objectsRequired

The document's revisions, newest first. Empty until anyone writes it.

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}/documents/{document}/revisions
curl https://api.clankership.com/v1/workspaces/acme/tickets/{ticket}/documents/{document}/revisions \  -H "Authorization: Bearer $CLANKER_API_KEY"
Response200
{  "revisions": [    {      "revision": 3,      "body": "## Approach\n1. Index every docs page at build time.\n2. Add a search box to the docs header that queries the index.",      "author": {        "person": {          "id": "Us3NfP8kLq2V",          "name": "Maya Patel",          "email": "maya@acme.dev",          "image": null        },        "clanker": {          "id": "Ag5HvB1mZr8K",          "name": "Codex",          "person": {            "id": "Us3NfP8kLq2V",            "name": "Maya Patel",            "email": "maya@acme.dev",            "image": null          }        }      },      "createdAt": "2026-10-14T09:05:12.000Z"    }  ]}
NextTicket statuses