Teams and tickets

A team is a group of workspace members that numbers its own tickets. Its key starts each ticket's ID: the Web team, key WEB, owns WEB-31 Add docs search. Each team has its own statuses and can have its own tags and views.

Teams

• key: 2–5 capital letters, unique in the workspace, such as WEB. Lowercase input is raised. Because it prefixes ticket IDs, it changes only while the team has no tickets.
• name: 1–80 characters, unique in the workspace ignoring case.
• visibility: an open team is listed for everyone, and anyone in the workspace can join it. A private team is listed only for its members and for owners and admins, and grows when a member or an admin adds people.

The person who creates a team joins it. A new team copies the workspace's status template and owns its copy, so later template changes reach only teams created afterwards. A team without tickets can be deleted; a team with tickets is archived instead, which keeps its tickets readable and takes no changes until it is restored.

Tickets

The ID is the team key and the team's next number, and numbers are never reused. Tickets are never deleted: Canceled and Duplicate are statuses.

Moving a ticket to another team gives it that team's next number and records the old ID, which still finds it. Its status follows by name, then by category, else the new team's default. The old team's tags come off, and it leaves its project unless the new team is linked to that project.

Ordering. Tickets have one workspace-wide order. Every view ordered by hand shows it, and reordering places a ticket right before or right after another.

Statuses

Every status belongs to one of five fixed categories:

Owners and admins add, rename, reorder and delete statuses, in the workspace's template or in one team's set. A status keeps its category. Every category keeps at least one status, and the default status for new tickets is a Backlog or Unstarted status, deleted only after another status becomes the default. Deleting a status that tickets use moves them to another status of the same team, named with moveTo.

Tags

New workspaces start with the tags bug, feature and tech debt. A tag belongs to the workspace and works on every ticket, or belongs to one team and works only on that team's tickets. A tag name names one tag on any ticket, so a team tag cannot share a workspace tag's name. Colors are gray, red, orange, amber, green, teal, cobalt, iris and pink.

Renaming or deleting a status, a tag, a project slug or a team key updates the saved view filters that name it.

Create and change tickets

Paths are relative to https://api.clankertest.com/v1/workspaces/{slug}. Teams are named by key, projects by slug and tickets by ID. PATCH changes only the fields you send, and null clears an optional field.

Create a ticket:

curl https://api.clankertest.com/v1/workspaces/acme/tickets \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "team": "WEB",
    "title": "Add docs search",
    "summary": "Readers cannot find a page without browsing the sidebar. Add a search box to the docs header.",
    "project": "docs-launch",
    "tags": ["feature"]
  }'

The response is the ticket, with status 201, its identifier such as WEB-31, and its status, tags and project. Change its status by name with Update a ticket:

curl -X PATCH https://api.clankertest.com/v1/workspaces/acme/tickets/WEB-31 \
  -H "Authorization: Bearer $CLANKER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "status": "In Progress" }'

Lists return every ticket the caller can read, without plans; see Pagination.

CLI

clanker team list
clanker team create WEB --name Web
clanker ticket create --team WEB --title "Add docs search" --project docs-launch --tag feature
clanker ticket update WEB-31 --status "In Progress"
clanker ticket list --team WEB --owner mine --category unstarted,started
clanker ticket move WEB-31 --team DOCS
clanker ticket reorder WEB-31 --before WEB-29
clanker status create "In QA" --category started --team WEB
clanker tag create search --color teal --team WEB

Agents

Agents use create_ticket, update_ticket, move_ticket and the other planning tools with their person's role. An agent names itself as a ticket's owner with "owner": "me". A ticket an agent creates takes the status, tags and owner it leaves out from the team's agent instructions, and a ticket with no team goes to the agent's default team.