# Views A view is a saved way to look at tickets: filters, grouping, order and layout. Each view belongs to one team, one project or one person. Anyone who sees a team or project can read its views, and changes apply for everyone; a person's own views are the tabs of their My work and only they see them. Filters can name the reader: owner me, clanker mine, and mine for tickets the reader owns or their clankers work on. ## The View object A saved way to look at a team's, a project's or a person's tickets: filters, grouping, order and layout. ### Attributes - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. ### Example ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ## List your views `GET /v1/workspaces/{slug}/me/views` Returns the caller's own views, the tabs of their My work. Everyone starts with Work, List and Board, each showing the open tickets they own or their clankers work on; Work is the default. Only the caller sees them. An account API key has no person and gets InvalidInput. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. ### Returns Returns an object with these fields. The status is 200. - `views` (array of objects, required): The views in tab order, as people arranged them. See [the View object](https://docs.clankership.com/api/views/object.md). - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/me/views \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "views": [ { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ] } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Create one of your views `POST /v1/workspaces/{slug}/me/views` Saves a view of the tickets the caller can read, across every team, as a My work tab only they see. Personal views group by status, category, owner, clanker, tag, project, team or none. Viewers can save their own views too. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `name` (string, required): The view's name, up to 60 characters, unique within its team, project or person. - `filters` (object): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `team`, `none`): How the view groups tickets. Defaults to status. - `orderBy` (string, one of: `manual`, `created`, `updated`): `manual` follows the order people set by hand, `created` puts the newest first and `updated` the most recently changed. Defaults to manual. - `layout` (string, one of: `list`, `board`, `work`): A list, a board or the work layout. Defaults to list. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 201. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/me/views \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "My clankers", "filters": { "categories": [ "plan", "build", "review" ], "clankers": [ "mine" ] }, "groupBy": "status", "layout": "board" }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Get one of your views `GET /v1/workspaces/{slug}/me/views/{view}` Returns one of the caller's own views with the tickets it shows, in its order. Another member's view is NotFound. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `view` (string, in path, required): The view's slug, such as active. ### Returns Returns an object with these fields. The status is 200. A view with the tickets it shows. - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. - `tickets` (array of objects, required): The tickets the view shows, in its order. - `id` (string, required): Unique ID of the ticket. - `identifier` (string, required): The team key and number, such as WEB-31. Paths take this ID. - `number` (number, required): The ticket's number within its team. - `team` (object, required): A team as tickets and projects show it. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `visibility` (string, one of: `open`, `private`, required): Who sees the team: open teams are listed for everyone in the workspace, private teams only for their members and for owners and admins. - `title` (string, required): A short name for the work. - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `owner` (nullable object, required): The person accountable for the ticket, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `clankers` (array of objects, required): The clankers working on the ticket, in the order they were added. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `project` (nullable object, required): The project the ticket belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `milestone` (nullable object, required): The milestone of its project the ticket belongs to, or null. - `id` (string, required): Unique ID of the milestone. - `number` (number, required): The milestone's number within the project: 2 is M2. - `name` (string, required): The milestone's name. - `tags` (array of objects, required): The ticket's tags, sorted by name. See [the Tag object](https://docs.clankership.com/api/tags/object.md). - `id` (string, required): Unique ID of the tag. - `name` (string, required): The tag's name, such as bug. - `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color. - `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag. - `id` (string, required): Unique ID of the team. - `key` (string, required): The team's key, such as WEB. - `checklist` (object, required): The ticket's checklist items for the statuses of its current stage, counted. The Work layout fills the stage's stretch of the track by this share. - `done` (number, required): How many of those items are done. - `inProgress` (number, required): How many of those items are in progress: started and not done. - `total` (number, required): How many items there are. - `needsHuman` (nullable object, required): Why the ticket waits on a person, or null when it does not. - `reasons` (array of strings, one of: `human-items`, `question`, `work-returned`, required): Why: `human-items` when only Human items are left on the current status's checklist in Plan, Build, Review or Ship; `question` while a question waits for an answer; `work-returned` when work sent to a clanker came back finished (a draft, refinement or plan) or declined. - `items` (array of strings, required): The open Human items, for `human-items`; otherwise empty. - `questions` (array of objects, required): The open questions, oldest first. - `id` (string, required): Unique ID of the question. - `question` (string, required): The question, up to 1,000 characters. - `choices` (array of strings, required): Up to four answers the asker suggests. Any answer will do. - `askedBy` (object, required): Who asked: a clanker for its person, or a person. - `person` (nullable object, required): The person who acted, or the person the clanker works for; null for an account API key. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `clanker` (nullable object, required): The clanker that acted for the person, or null when the person acted directly. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `askedAt` (string, required): When, as an ISO 8601 timestamp. - `work` (nullable object, required): The work that came back, for `work-returned`; otherwise null. - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked. - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined. - `reply` (nullable string, required): What the clanker said when it finished or declined, or null. - `rank` (number, required): The ticket's place in the one workspace-wide order that views ordered by hand follow; lower comes first. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. - `statuses` (array of objects, required): Every status of the view's teams, empty ones and ones its filters leave out included: the team's statuses, the union across a project's teams, or for a personal view the union across every team the person sees. Matching names and categories share one entry. The website shows the ones the filters select and offers the others as drop targets. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `teams` (array of strings, required): The keys of the teams with this status. A ticket moves into the column only when its team is one of them. - `work` (nullable object, required): For a view with the Work layout, its crew, lanes and log; otherwise null. - `crew` (number, required): How many different clankers work on the view's tickets. - `lanes` (array of objects, required): One lane per ticket, in the view's order. - `ticket` (string, required): Unique ID of the ticket. - `state` (string, one of: `live`, `needs-human`, `ready`, `idle`, `done`, `canceled`, required): Whose move it is: needs-human while the ticket waits on a person (see the ticket's needsHuman); live while a clanker has the newest work sent on it; ready when that work was a build the clanker finished; idle otherwise; done or canceled once the ticket is. - `message` (nullable object, required): The newest work a person sent a clanker on the ticket, or null. - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked. - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined. - `reply` (nullable string, required): What the clanker said when it finished or declined, or null. - `log` (array of objects, required): The latest four changes to the view's tickets, newest first. - `id` (string, required): Unique ID of the event. - `type` (string, required): The event's type, such as ticket.updated. - `actor` (string, required): Who made the change, such as Maya Patel or Codex · Maya Patel. - `subject` (nullable string, required): What changed, such as WEB-31 Rate limits. - `createdAt` (string, required): When, as an ISO 8601 time. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/me/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z", "tickets": [ { "id": "Tk7BnC5xLp9M", "identifier": "WEB-31", "number": 31, "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web", "visibility": "open" }, "title": "Add docs search", "status": { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false }, "owner": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev", "image": null }, "clankers": [ { "id": "Ag5HvB1mZr8K", "name": "Codex", "person": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev", "image": null } } ], "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 } ], "checklist": { "done": 1, "inProgress": 1, "total": 3 }, "needsHuman": null, "rank": 31.5, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ], "statuses": [ { "id": "St1BkL4pQx7N", "name": "Backlog", "category": "backlog", "position": 0, "isDefault": true, "teams": [ "WEB" ] }, { "id": "St2PlN8mRc3K", "name": "Plan", "category": "plan", "position": 1, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St4IrG2wZf5M", "name": "Review", "category": "review", "position": 3, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St5ShY7kPb1Q", "name": "Ship", "category": "ship", "position": 4, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St6DnW4cRm9X", "name": "Done", "category": "done", "position": 5, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St7CnJ3xTe8L", "name": "Canceled", "category": "canceled", "position": 6, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St8DpR9vLw2H", "name": "Duplicate", "category": "canceled", "position": 7, "isDefault": false, "teams": [ "WEB" ] } ], "work": null } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Update one of your views `PATCH /v1/workspaces/{slug}/me/views/{view}` Changes only the settings sent; `filters` replaces the saved filters. `isDefault: true` makes it the view My work opens. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `view` (string, in path, required): The view's slug, such as active. - `name` (string): The view's name, up to 60 characters, unique within its team, project or person. A new name gives the view a new slug. - `filters` (object): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `team`, `none`): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`): `manual` follows the order people set by hand, `created` puts the newest first and `updated` the most recently changed. - `layout` (string, one of: `list`, `board`, `work`): A list, a board or the work layout. - `isDefault` (boolean): `true` makes this the view the owner's page opens. Always `true`. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 200. ### Request ```bash curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/me/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "layout": "board", "isDefault": true }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Delete one of your views `DELETE /v1/workspaces/{slug}/me/views/{view}` Deletes the view; it does not come back. The default view stays until another view is the default. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `view` (string, in path, required): The view's slug, such as active. ### Returns Returns no content. The status is 204. ### Request ```bash curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/me/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Reorder one of your views `POST /v1/workspaces/{slug}/me/views/{view}/reorder` Moves the view right before or right after another of your views, changing the order of your My work tabs. Send `before` or `after`, not both. Viewers can reorder their own views. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `view` (string, in path, required): The view's slug, such as active. - `before` (string): The slug of the view to go right before. - `after` (string): The slug of the view to go right after. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 200. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/me/views/{view}/reorder \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "before": "active" }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## List a team's views `GET /v1/workspaces/{slug}/teams/{team}/views` Returns the team's saved views. Every team starts with All tickets, Active and Backlog. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in path, required): The team's key, such as WEB. ### Returns Returns an object with these fields. The status is 200. - `views` (array of objects, required): The views in tab order, as people arranged them. See [the View object](https://docs.clankership.com/api/views/object.md). - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/teams/{team}/views \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "views": [ { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ] } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Create a team view `POST /v1/workspaces/{slug}/teams/{team}/views` Saves a view of the team's tickets, with a slug made from its name. Team views group by status, category, owner, clanker, tag, project or none. Members of the team and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in path, required): The team's key, such as WEB. - `name` (string, required): The view's name, up to 60 characters, unique within its team, project or person. - `filters` (object): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `none`): How the view groups tickets. Defaults to status. - `orderBy` (string, one of: `manual`, `created`, `updated`): `manual` follows the order people set by hand, `created` puts the newest first and `updated` the most recently changed. Defaults to manual. - `layout` (string, one of: `list`, `board`, `work`): A list, a board or the work layout. Defaults to list. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 201. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/teams/{team}/views \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Search work", "filters": { "categories": [ "plan", "build", "review" ], "tags": [ "feature" ] }, "groupBy": "clanker", "layout": "board" }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Get a team view `GET /v1/workspaces/{slug}/teams/{team}/views/{view}` Returns the view with the tickets it shows, in its order, and the team's statuses for a status grouping's columns. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in path, required): The team's key, such as WEB. - `view` (string, in path, required): The view's slug, such as active. ### Returns Returns an object with these fields. The status is 200. A view with the tickets it shows. - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. - `tickets` (array of objects, required): The tickets the view shows, in its order. - `id` (string, required): Unique ID of the ticket. - `identifier` (string, required): The team key and number, such as WEB-31. Paths take this ID. - `number` (number, required): The ticket's number within its team. - `team` (object, required): A team as tickets and projects show it. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `visibility` (string, one of: `open`, `private`, required): Who sees the team: open teams are listed for everyone in the workspace, private teams only for their members and for owners and admins. - `title` (string, required): A short name for the work. - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `owner` (nullable object, required): The person accountable for the ticket, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `clankers` (array of objects, required): The clankers working on the ticket, in the order they were added. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `project` (nullable object, required): The project the ticket belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `milestone` (nullable object, required): The milestone of its project the ticket belongs to, or null. - `id` (string, required): Unique ID of the milestone. - `number` (number, required): The milestone's number within the project: 2 is M2. - `name` (string, required): The milestone's name. - `tags` (array of objects, required): The ticket's tags, sorted by name. See [the Tag object](https://docs.clankership.com/api/tags/object.md). - `id` (string, required): Unique ID of the tag. - `name` (string, required): The tag's name, such as bug. - `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color. - `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag. - `id` (string, required): Unique ID of the team. - `key` (string, required): The team's key, such as WEB. - `checklist` (object, required): The ticket's checklist items for the statuses of its current stage, counted. The Work layout fills the stage's stretch of the track by this share. - `done` (number, required): How many of those items are done. - `inProgress` (number, required): How many of those items are in progress: started and not done. - `total` (number, required): How many items there are. - `needsHuman` (nullable object, required): Why the ticket waits on a person, or null when it does not. - `reasons` (array of strings, one of: `human-items`, `question`, `work-returned`, required): Why: `human-items` when only Human items are left on the current status's checklist in Plan, Build, Review or Ship; `question` while a question waits for an answer; `work-returned` when work sent to a clanker came back finished (a draft, refinement or plan) or declined. - `items` (array of strings, required): The open Human items, for `human-items`; otherwise empty. - `questions` (array of objects, required): The open questions, oldest first. - `id` (string, required): Unique ID of the question. - `question` (string, required): The question, up to 1,000 characters. - `choices` (array of strings, required): Up to four answers the asker suggests. Any answer will do. - `askedBy` (object, required): Who asked: a clanker for its person, or a person. - `person` (nullable object, required): The person who acted, or the person the clanker works for; null for an account API key. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `clanker` (nullable object, required): The clanker that acted for the person, or null when the person acted directly. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `askedAt` (string, required): When, as an ISO 8601 timestamp. - `work` (nullable object, required): The work that came back, for `work-returned`; otherwise null. - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked. - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined. - `reply` (nullable string, required): What the clanker said when it finished or declined, or null. - `rank` (number, required): The ticket's place in the one workspace-wide order that views ordered by hand follow; lower comes first. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. - `statuses` (array of objects, required): Every status of the view's teams, empty ones and ones its filters leave out included: the team's statuses, the union across a project's teams, or for a personal view the union across every team the person sees. Matching names and categories share one entry. The website shows the ones the filters select and offers the others as drop targets. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `teams` (array of strings, required): The keys of the teams with this status. A ticket moves into the column only when its team is one of them. - `work` (nullable object, required): For a view with the Work layout, its crew, lanes and log; otherwise null. - `crew` (number, required): How many different clankers work on the view's tickets. - `lanes` (array of objects, required): One lane per ticket, in the view's order. - `ticket` (string, required): Unique ID of the ticket. - `state` (string, one of: `live`, `needs-human`, `ready`, `idle`, `done`, `canceled`, required): Whose move it is: needs-human while the ticket waits on a person (see the ticket's needsHuman); live while a clanker has the newest work sent on it; ready when that work was a build the clanker finished; idle otherwise; done or canceled once the ticket is. - `message` (nullable object, required): The newest work a person sent a clanker on the ticket, or null. - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked. - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined. - `reply` (nullable string, required): What the clanker said when it finished or declined, or null. - `log` (array of objects, required): The latest four changes to the view's tickets, newest first. - `id` (string, required): Unique ID of the event. - `type` (string, required): The event's type, such as ticket.updated. - `actor` (string, required): Who made the change, such as Maya Patel or Codex · Maya Patel. - `subject` (nullable string, required): What changed, such as WEB-31 Rate limits. - `createdAt` (string, required): When, as an ISO 8601 time. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/teams/{team}/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z", "tickets": [ { "id": "Tk7BnC5xLp9M", "identifier": "WEB-31", "number": 31, "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web", "visibility": "open" }, "title": "Add docs search", "status": { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false }, "owner": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev", "image": null }, "clankers": [ { "id": "Ag5HvB1mZr8K", "name": "Codex", "person": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev", "image": null } } ], "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 } ], "checklist": { "done": 1, "inProgress": 1, "total": 3 }, "needsHuman": null, "rank": 31.5, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ], "statuses": [ { "id": "St1BkL4pQx7N", "name": "Backlog", "category": "backlog", "position": 0, "isDefault": true, "teams": [ "WEB" ] }, { "id": "St2PlN8mRc3K", "name": "Plan", "category": "plan", "position": 1, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St4IrG2wZf5M", "name": "Review", "category": "review", "position": 3, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St5ShY7kPb1Q", "name": "Ship", "category": "ship", "position": 4, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St6DnW4cRm9X", "name": "Done", "category": "done", "position": 5, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St7CnJ3xTe8L", "name": "Canceled", "category": "canceled", "position": 6, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St8DpR9vLw2H", "name": "Duplicate", "category": "canceled", "position": 7, "isDefault": false, "teams": [ "WEB" ] } ], "work": null } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Update a team view `PATCH /v1/workspaces/{slug}/teams/{team}/views/{view}` Changes only the settings sent, for everyone who opens the view; `filters` replaces the saved filters. Members of the team and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in path, required): The team's key, such as WEB. - `view` (string, in path, required): The view's slug, such as active. - `name` (string): The view's name, up to 60 characters, unique within its team, project or person. A new name gives the view a new slug. - `filters` (object): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `none`): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`): `manual` follows the order people set by hand, `created` puts the newest first and `updated` the most recently changed. - `layout` (string, one of: `list`, `board`, `work`): A list, a board or the work layout. - `isDefault` (boolean): `true` makes this the view the owner's page opens. Always `true`. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 200. ### Request ```bash curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/teams/{team}/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "layout": "board", "isDefault": true }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Delete a team view `DELETE /v1/workspaces/{slug}/teams/{team}/views/{view}` Deletes the view. The default view stays until another view is the default. Members of the team and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in path, required): The team's key, such as WEB. - `view` (string, in path, required): The view's slug, such as active. ### Returns Returns no content. The status is 204. ### Request ```bash curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/teams/{team}/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Reorder a team view `POST /v1/workspaces/{slug}/teams/{team}/views/{view}/reorder` Moves the view right before or right after another of the team's views, changing the order of its tabs for everyone. Send `before` or `after`, not both. Members of the team and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `team` (string, in path, required): The team's key, such as WEB. - `view` (string, in path, required): The view's slug, such as active. - `before` (string): The slug of the view to go right before. - `after` (string): The slug of the view to go right after. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 200. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/teams/{team}/views/{view}/reorder \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "before": "active" }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## List a project's views `GET /v1/workspaces/{slug}/projects/{project}/views` Returns the project's saved views. Every project starts with Board, its default, and All tickets. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `project` (string, in path, required): The project's slug, such as docs-launch. ### Returns Returns an object with these fields. The status is 200. - `views` (array of objects, required): The views in tab order, as people arranged them. See [the View object](https://docs.clankership.com/api/views/object.md). - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/projects/{project}/views \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "views": [ { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ] } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Create a project view `POST /v1/workspaces/{slug}/projects/{project}/views` Saves a view of the project's tickets, with a slug made from its name. Project views group by status, category, owner, clanker, tag, milestone, team or none. Members of the project's teams and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `project` (string, in path, required): The project's slug, such as docs-launch. - `name` (string, required): The view's name, up to 60 characters, unique within its team, project or person. - `filters` (object): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `milestone`, `team`, `none`): How the view groups tickets. Defaults to status. - `orderBy` (string, one of: `manual`, `created`, `updated`): `manual` follows the order people set by hand, `created` puts the newest first and `updated` the most recently changed. Defaults to manual. - `layout` (string, one of: `list`, `board`, `work`): A list, a board or the work layout. Defaults to list. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 201. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/projects/{project}/views \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "By milestone", "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "milestone" }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Get a project view `GET /v1/workspaces/{slug}/projects/{project}/views/{view}` Returns the view with the tickets it shows, in its order. A status grouping uses the statuses the project's teams share as columns, or categories when their statuses differ. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `project` (string, in path, required): The project's slug, such as docs-launch. - `view` (string, in path, required): The view's slug, such as active. ### Returns Returns an object with these fields. The status is 200. A view with the tickets it shows. - `id` (string, required): Unique ID of the view. - `slug` (string, required): Made from the view's name and unique within its team, project or person, such as active. - `name` (string, required): The view's name, such as Active. - `team` (nullable object, required): The team the view belongs to, or null. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `project` (nullable object, required): The project the view belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `person` (nullable object, required): The person whose own view this is, shown only to them on My work, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `filters` (object, required): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `project`, `milestone`, `team`, `none`, required): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`, required): How the view orders tickets: manual follows the order people set by hand, created puts the newest first and updated the most recently changed. - `layout` (string, one of: `list`, `board`, `work`, required): How the view draws its tickets: a list, a board, or the work layout. - `isDefault` (boolean, required): Whether the owner's page opens this view: its Tickets page, or My work. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. - `tickets` (array of objects, required): The tickets the view shows, in its order. - `id` (string, required): Unique ID of the ticket. - `identifier` (string, required): The team key and number, such as WEB-31. Paths take this ID. - `number` (number, required): The ticket's number within its team. - `team` (object, required): A team as tickets and projects show it. - `id` (string, required): Unique ID of the team. - `key` (string, required): 2 to 5 capital letters that start the team's ticket IDs, such as WEB. - `name` (string, required): The team's display name. - `visibility` (string, one of: `open`, `private`, required): Who sees the team: open teams are listed for everyone in the workspace, private teams only for their members and for owners and admins. - `title` (string, required): A short name for the work. - `status` (object, required): A step in a team's workflow, such as Plan or Build. See [the TicketStatus object](https://docs.clankership.com/api/ticket-statuses/object.md). - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `owner` (nullable object, required): The person accountable for the ticket, or null. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `clankers` (array of objects, required): The clankers working on the ticket, in the order they were added. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `project` (nullable object, required): The project the ticket belongs to, or null. - `id` (string, required): Unique ID of the project. - `slug` (string, required): Lowercase letters, digits and hyphens, unique in the workspace, such as docs-launch. - `name` (string, required): The project's display name. - `milestone` (nullable object, required): The milestone of its project the ticket belongs to, or null. - `id` (string, required): Unique ID of the milestone. - `number` (number, required): The milestone's number within the project: 2 is M2. - `name` (string, required): The milestone's name. - `tags` (array of objects, required): The ticket's tags, sorted by name. See [the Tag object](https://docs.clankership.com/api/tags/object.md). - `id` (string, required): Unique ID of the tag. - `name` (string, required): The tag's name, such as bug. - `color` (string, one of: `gray`, `red`, `orange`, `amber`, `green`, `teal`, `cobalt`, `iris`, `pink`, required): The tag's color. - `team` (nullable object, required): The team a team tag belongs to; null for a workspace tag. - `id` (string, required): Unique ID of the team. - `key` (string, required): The team's key, such as WEB. - `checklist` (object, required): The ticket's checklist items for the statuses of its current stage, counted. The Work layout fills the stage's stretch of the track by this share. - `done` (number, required): How many of those items are done. - `inProgress` (number, required): How many of those items are in progress: started and not done. - `total` (number, required): How many items there are. - `needsHuman` (nullable object, required): Why the ticket waits on a person, or null when it does not. - `reasons` (array of strings, one of: `human-items`, `question`, `work-returned`, required): Why: `human-items` when only Human items are left on the current status's checklist in Plan, Build, Review or Ship; `question` while a question waits for an answer; `work-returned` when work sent to a clanker came back finished (a draft, refinement or plan) or declined. - `items` (array of strings, required): The open Human items, for `human-items`; otherwise empty. - `questions` (array of objects, required): The open questions, oldest first. - `id` (string, required): Unique ID of the question. - `question` (string, required): The question, up to 1,000 characters. - `choices` (array of strings, required): Up to four answers the asker suggests. Any answer will do. - `askedBy` (object, required): Who asked: a clanker for its person, or a person. - `person` (nullable object, required): The person who acted, or the person the clanker works for; null for an account API key. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `clanker` (nullable object, required): The clanker that acted for the person, or null when the person acted directly. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `askedAt` (string, required): When, as an ISO 8601 timestamp. - `work` (nullable object, required): The work that came back, for `work-returned`; otherwise null. - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked. - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined. - `reply` (nullable string, required): What the clanker said when it finished or declined, or null. - `rank` (number, required): The ticket's place in the one workspace-wide order that views ordered by hand follow; lower comes first. - `createdAt` (string, required): When it was created, as an ISO 8601 timestamp. - `updatedAt` (string, required): When it last changed, as an ISO 8601 timestamp. - `statuses` (array of objects, required): Every status of the view's teams, empty ones and ones its filters leave out included: the team's statuses, the union across a project's teams, or for a personal view the union across every team the person sees. Matching names and categories share one entry. The website shows the ones the filters select and offers the others as drop targets. - `id` (string, required): Unique ID of the ticket status. - `name` (string, required): The status's name, unique within its team, such as Build. - `category` (string, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`, required): The fixed stage the status belongs to: backlog, plan, build, review, ship, done or canceled. It cannot change. - `position` (number, required): Orders the status within its category; lower comes first. - `isDefault` (boolean, required): Whether new tickets get this status when none is named. - `teams` (array of strings, required): The keys of the teams with this status. A ticket moves into the column only when its team is one of them. - `work` (nullable object, required): For a view with the Work layout, its crew, lanes and log; otherwise null. - `crew` (number, required): How many different clankers work on the view's tickets. - `lanes` (array of objects, required): One lane per ticket, in the view's order. - `ticket` (string, required): Unique ID of the ticket. - `state` (string, one of: `live`, `needs-human`, `ready`, `idle`, `done`, `canceled`, required): Whose move it is: needs-human while the ticket waits on a person (see the ticket's needsHuman); live while a clanker has the newest work sent on it; ready when that work was a build the clanker finished; idle otherwise; done or canceled once the ticket is. - `message` (nullable object, required): The newest work a person sent a clanker on the ticket, or null. - `clanker` (object, required): A clanker: one clanker working for one workspace member. Clankers work on tickets as their clankers. See [the Clanker object](https://docs.clankership.com/api/clankers/object.md). - `id` (string, required): Unique ID of the clanker. - `name` (string, required): The clanker, such as Codex. - `person` (object, required): A person in the workspace. - `id` (string, required): The person's user ID. - `name` (string, required): The person's display name. - `email` (string, required): The person's email address. - `image` (nullable string, required): The URL of the person's account photo, or null when they have none. - `ask` (string, one of: `draft`, `refine`, `plan`, `build`, `mention`, `answer`, required): What was asked. - `status` (string, one of: `queued`, `delivered`, `completed`, `declined`, required): Where the work is: queued, delivered, completed or declined. - `reply` (nullable string, required): What the clanker said when it finished or declined, or null. - `log` (array of objects, required): The latest four changes to the view's tickets, newest first. - `id` (string, required): Unique ID of the event. - `type` (string, required): The event's type, such as ticket.updated. - `actor` (string, required): Who made the change, such as Maya Patel or Codex · Maya Patel. - `subject` (nullable string, required): What changed, such as WEB-31 Rate limits. - `createdAt` (string, required): When, as an ISO 8601 time. ### Request ```bash curl https://api.clankership.com/v1/workspaces/{slug}/projects/{project}/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z", "tickets": [ { "id": "Tk7BnC5xLp9M", "identifier": "WEB-31", "number": 31, "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web", "visibility": "open" }, "title": "Add docs search", "status": { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false }, "owner": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev", "image": null }, "clankers": [ { "id": "Ag5HvB1mZr8K", "name": "Codex", "person": { "id": "Us3NfP8kLq2V", "name": "Maya Patel", "email": "maya@acme.dev", "image": null } } ], "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 } ], "checklist": { "done": 1, "inProgress": 1, "total": 3 }, "needsHuman": null, "rank": 31.5, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ], "statuses": [ { "id": "St1BkL4pQx7N", "name": "Backlog", "category": "backlog", "position": 0, "isDefault": true, "teams": [ "WEB" ] }, { "id": "St2PlN8mRc3K", "name": "Plan", "category": "plan", "position": 1, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St3BdV6nHs9D", "name": "Build", "category": "build", "position": 2, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St4IrG2wZf5M", "name": "Review", "category": "review", "position": 3, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St5ShY7kPb1Q", "name": "Ship", "category": "ship", "position": 4, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St6DnW4cRm9X", "name": "Done", "category": "done", "position": 5, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St7CnJ3xTe8L", "name": "Canceled", "category": "canceled", "position": 6, "isDefault": false, "teams": [ "WEB" ] }, { "id": "St8DpR9vLw2H", "name": "Duplicate", "category": "canceled", "position": 7, "isDefault": false, "teams": [ "WEB" ] } ], "work": null } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Update a project view `PATCH /v1/workspaces/{slug}/projects/{project}/views/{view}` Changes only the settings sent, for everyone who opens the view; `filters` replaces the saved filters. Members of the project's teams and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `project` (string, in path, required): The project's slug, such as docs-launch. - `view` (string, in path, required): The view's slug, such as active. - `name` (string): The view's name, up to 60 characters, unique within its team, project or person. A new name gives the view a new slug. - `filters` (object): Which tickets a view shows. Filters combine with and; the values within one filter with or. - `statuses` (array of strings): Only tickets with these statuses, by name. - `categories` (array of strings, one of: `backlog`, `plan`, `build`, `review`, `ship`, `done`, `canceled`): Only tickets whose status is in these categories. - `tags` (array of strings): Only tickets with any of these tags, by name. - `owners` (array of strings): Only tickets these people own, by user ID; me matches the person reading the view, none tickets without an owner. - `clankers` (array of strings): Only tickets any of these clankers works on, by clanker ID; mine matches the reader's clankers, none tickets without clankers. - `mine` (boolean): Only tickets the person reading the view owns or their clankers work on. Always `true`. - `projects` (array of strings): Only tickets in these projects, by slug; none matches tickets without a project. Team and personal views. - `milestones` (array of strings): Only tickets in these milestones, such as M1; none matches tickets without one. Project views only. - `teams` (array of strings): Only tickets of these teams, by key. Project and personal views. - `needsHuman` (boolean): Only tickets that wait on a person, as their `needsHuman` says. Always `true`. - `groupBy` (string, one of: `status`, `category`, `owner`, `clanker`, `tag`, `milestone`, `team`, `none`): How the view groups tickets. - `orderBy` (string, one of: `manual`, `created`, `updated`): `manual` follows the order people set by hand, `created` puts the newest first and `updated` the most recently changed. - `layout` (string, one of: `list`, `board`, `work`): A list, a board or the work layout. - `isDefault` (boolean): `true` makes this the view the owner's page opens. Always `true`. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 200. ### Request ```bash curl -X PATCH https://api.clankership.com/v1/workspaces/{slug}/projects/{project}/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "layout": "board", "isDefault": true }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Delete a project view `DELETE /v1/workspaces/{slug}/projects/{project}/views/{view}` Deletes the view. The default view stays until another view is the default. Members of the project's teams and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `project` (string, in path, required): The project's slug, such as docs-launch. - `view` (string, in path, required): The view's slug, such as active. ### Returns Returns no content. The status is 204. ### Request ```bash curl -X DELETE https://api.clankership.com/v1/workspaces/{slug}/projects/{project}/views/{view} \ -H "Authorization: Bearer $CLANKER_API_KEY" ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id. ## Reorder a project view `POST /v1/workspaces/{slug}/projects/{project}/views/{view}/reorder` Moves the view right before or right after another of the project's views, changing the order of its tabs for everyone. Send `before` or `after`, not both. Members of the project's teams and workspace owners and admins change its views; viewers cannot. ### Parameters - `slug` (string, in path, required): The workspace's slug or ID, such as acme. - `project` (string, in path, required): The project's slug, such as docs-launch. - `view` (string, in path, required): The view's slug, such as active. - `before` (string): The slug of the view to go right before. - `after` (string): The slug of the view to go right after. ### Returns Returns the [View](https://docs.clankership.com/api/views/object.md) object. The status is 200. ### Request ```bash curl -X POST https://api.clankership.com/v1/workspaces/{slug}/projects/{project}/views/{view}/reorder \ -H "Authorization: Bearer $CLANKER_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "before": "active" }' ``` ### Response ```json { "id": "Vw4AcT8nRk2P", "slug": "active", "name": "Active", "team": { "id": "Tm6PzN3kWq1J", "key": "WEB", "name": "Web" }, "project": null, "person": null, "filters": { "categories": [ "plan", "build", "review" ] }, "groupBy": "status", "orderBy": "manual", "layout": "board", "isDefault": false, "createdAt": "2026-10-01T16:20:00.000Z", "updatedAt": "2026-10-14T09:05:12.000Z" } ``` ### Errors - `400` `InvalidInput`: The request is malformed, or a value is not allowed. - `401` `Unauthorized`: The request has no valid API key. - `403` `Forbidden`: The key's user or role may not do this. - `404` `NotFound`: The workspace or object does not exist, or the caller cannot see it. - `409` `Conflict`: The change conflicts with current data, such as a slug that is already in use. - `500` `Internal`: Clanker Ship failed to handle the request. Retry, or report the response's x-request-id.