Projects

A project is a body of work with a goal, kept in one priority order per workspace. It links the teams whose tickets it holds and the products it changes, and splits into milestones (M1, M2). Anyone who sees one of its teams can open it.

The Project object

A body of work with a goal. It links the teams whose tickets it holds and the products it changes, and has numbered milestones.

Attributes

idstringRequired

Unique ID of the project.

slugstringRequired

Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch.

namestringRequired

The project's display name.

summarynullable stringRequired

One line on what the project delivers, or null.

statusstringRequired

Where the project stands: planned, active, paused, completed or canceled.

One ofplannedactivepausedcompletedcanceled

leadnullable objectRequired

The member who leads the project, or null.

targetDatenullable stringRequired

The date the project should be done, as YYYY-MM-DD, or null.

teamsarray of objectsRequired

The teams whose tickets the project holds, sorted by name.

productsarray of objectsRequired

The products the project changes, sorted by name.

milestonesarray of Milestone objectsRequired

The project's milestones, in number order.

progressobjectRequired

The project's tickets counted by status category.

archivedAtnullable stringRequired

When it was archived, as an ISO 8601 timestamp; null while active.

createdAtstringRequired

When it was created, as an ISO 8601 timestamp.

updatedAtstringRequired

When it last changed, as an ISO 8601 timestamp.

documentnullable stringRequired

The project's document in Markdown, or null.

The Project object

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

List projects

GET/v1/workspaces/{slug}/projects

Returns the projects the caller can open, in priority order and without their documents. A project opens for anyone who sees one of its teams. Archived projects are left out unless archived asks for them.

Path parameters

slugstringRequired

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

Query parameters

teamstring

Only projects linked to this team, by key, such as WEB.

productstring

Only projects linked to this product, by slug, such as storefront.

archivedstring

Which archived projects to return: exclude (the default), include or only archived ones.

One ofexcludeincludeonly

Returns

Returns an object with these fields. Status 200.

projectsarray of objectsRequired

The projects in priority order.

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}/projects

1curl https://api.qa.clankership.net/v1/workspaces/acme/projects \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "projects": [    {      "id": "Pj2KsV8dRf4N",      "slug": "docs-launch",      "name": "Docs launch",      "summary": "Ship the public docs site with search and the API reference.",      "status": "active",      "lead": {        "id": "Us3NfP8kLq2V",        "name": "Maya Patel",        "email": "maya@acme.dev"      },      "targetDate": "2026-11-20",      "teams": [        {          "id": "Tm6PzN3kWq1J",          "key": "WEB",          "name": "Web",          "visibility": "open"        }      ],      "products": [        {          "id": "Pr4GtY9sLm3B",          "slug": "storefront",          "name": "Storefront"        }      ],      "milestones": [        {          "id": "Ms1RfP5kXn8B",          "number": 1,          "name": "Reference pages",          "summary": "Every API resource has a generated page."        },        {          "id": "Ms2SrC9vLm4D",          "number": 2,          "name": "Search",          "summary": "Readers find any page from the docs header."        }      ],      "progress": {        "backlog": 2,        "unstarted": 3,        "started": 2,        "completed": 6,        "canceled": 1      },      "archivedAt": null,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Create a project

POST/v1/workspaces/{slug}/projects

Adds a project at the end of the priority order, with the default views. Viewers cannot create projects, and the slug and name must be unused, archived projects included.

Path parameters

slugstringRequired

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

Body parameters

namestringRequired

The project's display name, up to 100 characters, unique in the workspace.

slugstringRequired

Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch.

summarynullable string

One line on what the project delivers, up to 200 characters.

statusstring

Where the project stands. Defaults to planned.

One ofplannedactivepausedcompletedcanceled

leadnullable string

The member who leads the project, by user ID or email address.

targetDatenullable string

The date the project should be done, as YYYY-MM-DD.

teamsarray of stringsRequired

The teams whose tickets the project holds, by key. At least one, and each one the caller sees.

productsarray of strings

The products the project changes, by slug.

documentnullable string

The project's document in Markdown.

Returns

Returns the Project 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}/projects

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/projects \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Docs launch",6    "slug": "docs-launch",7    "summary": "Ship the public docs site with search and the API reference.",8    "status": "active",9    "lead": "maya@acme.dev",10    "targetDate": "2026-11-20",11    "teams": [12      "WEB"13    ],14    "products": [15      "storefront"16    ]17  }'

Response201

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

Get a project

GET/v1/workspaces/{slug}/projects/{project}

Returns one project, archived or not, with its document and milestones.

Path parameters

slugstringRequired

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

projectstringRequired

The project's slug, such as docs-launch.

Returns

Returns the Project 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}/projects/{project}

1curl https://api.qa.clankership.net/v1/workspaces/acme/projects/{project} \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

Update a project

PATCH/v1/workspaces/{slug}/projects/{project}

Changes only the fields sent. Viewers cannot change projects, and an archived project takes no changes until it is restored. A new slug or name must be unused.

Path parameters

slugstringRequired

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

projectstringRequired

The project's slug, such as docs-launch.

Body parameters

namestring

The project's display name, up to 100 characters, unique in the workspace.

slugstring

Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch.

summarynullable string

One line on what the project delivers, up to 200 characters. null clears it.

statusstring

Where the project stands.

One ofplannedactivepausedcompletedcanceled

leadnullable string

The member who leads the project, by user ID or email address. null clears it.

targetDatenullable string

The date the project should be done, as YYYY-MM-DD. null clears it.

teamsarray of strings

Replaces the linked teams, by key. At least one; a team stays linked while the project holds its tickets.

productsarray of strings

Replaces the linked products, by slug. An empty list unlinks them all.

documentnullable string

The project's document in Markdown. null clears it.

Returns

Returns the Project 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}/projects/{project}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/projects/{project} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "status": "active",6    "targetDate": "2026-11-27"7  }'

Response200

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

Reorder a project

POST/v1/workspaces/{slug}/projects/{project}/reorder

Moves the project in the workspace's priority order, right before or right after another project. Send before or after, not both. Viewers cannot reorder projects.

Path parameters

slugstringRequired

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

projectstringRequired

The project's slug, such as docs-launch.

Body parameters

beforestring

The slug of the project to go right before.

afternullable string

The slug of the project to go right after, or null to go first.

Returns

Returns the Project 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}/projects/{project}/reorder

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/projects/{project}/reorder \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "before": "checkout-v2"6  }'

Response200

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

Archive a project

POST/v1/workspaces/{slug}/projects/{project}/archive

Archived projects leave lists and take no changes; their tickets stay on their teams. Viewers cannot archive projects, and archiving an archived project changes nothing.

Path parameters

slugstringRequired

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

projectstringRequired

The project's slug, such as docs-launch.

Returns

Returns the Project 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}/projects/{project}/archive

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/projects/{project}/archive \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

Restore a project

POST/v1/workspaces/{slug}/projects/{project}/restore

Brings an archived project back, so it takes changes again. Viewers cannot restore projects, and restoring an active project changes nothing.

Path parameters

slugstringRequired

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

projectstringRequired

The project's slug, such as docs-launch.

Returns

Returns the Project 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}/projects/{project}/restore

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/projects/{project}/restore \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "id": "Pj2KsV8dRf4N",  "slug": "docs-launch",  "name": "Docs launch",  "summary": "Ship the public docs site with search and the API reference.",  "status": "active",  "lead": {    "id": "Us3NfP8kLq2V",    "name": "Maya Patel",    "email": "maya@acme.dev"  },  "targetDate": "2026-11-20",  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open"    }  ],  "products": [    {      "id": "Pr4GtY9sLm3B",      "slug": "storefront",      "name": "Storefront"    }  ],  "milestones": [    {      "id": "Ms1RfP5kXn8B",      "number": 1,      "name": "Reference pages",      "summary": "Every API resource has a generated page."    },    {      "id": "Ms2SrC9vLm4D",      "number": 2,      "name": "Search",      "summary": "Readers find any page from the docs header."    }  ],  "progress": {    "backlog": 2,    "unstarted": 3,    "started": 2,    "completed": 6,    "canceled": 1  },  "archivedAt": null,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z",  "document": "## Goal\nEvery Acme developer finds the answer in the docs before asking in chat.\n\n## Scope\nThe API reference, guides and search."}

NextMilestones