Tags

A tag is a colored label on tickets, such as bug. Workspace tags work on every ticket and belong to owners and admins; team tags work only on their team's tickets, and the team's members manage them too.

The Tag object

A colored label on tickets. Workspace tags work on every ticket; team tags only on their team's tickets.

Attributes

idstringRequired

Unique ID of the tag.

namestringRequired

The tag's name, such as bug.

colorstringRequired

The tag's color.

One ofgrayredorangeambergreentealcobaltirispink

teamnullable objectRequired

The team a team tag belongs to; null for a workspace tag.

The Tag object

{  "id": "Tg3FtR7nWq2K",  "name": "feature",  "color": "cobalt",  "team": null}

List tags

GET/v1/workspaces/{slug}/tags

Returns workspace tags and the team tags of every team the caller sees or, with team, workspace tags and that team's tags.

Path parameters

slugstringRequired

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

Query parameters

teamstring

A team's key, such as WEB, for the tags that team's tickets can use.

Returns

Returns an object with these fields. Status 200.

tagsarray of Tag objectsRequired

The tags, sorted by name.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

GET/v1/workspaces/{slug}/tags

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

Response200

{  "tags": [    {      "id": "Tg3FtR7nWq2K",      "name": "feature",      "color": "cobalt",      "team": null    }  ]}

Create a tag

POST/v1/workspaces/{slug}/tags

Owners and admins create workspace tags, and a team's members also create its team tags; viewers cannot. A workspace tag's name must differ from every tag's, and a team tag's from the workspace tags and the team's own.

Path parameters

slugstringRequired

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

Body parameters

namestringRequired

The tag's name, up to 40 characters, such as bug.

colorstringRequired

The tag's color.

One ofgrayredorangeambergreentealcobaltirispink

teamnullable string

The key of the team a team tag belongs to, such as WEB. Leave it out for a workspace tag.

Returns

Returns the Tag object. Status 201.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

POST/v1/workspaces/{slug}/tags

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/tags \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "search",6    "color": "teal",7    "team": "WEB"8  }'

Response201

{  "id": "Tg3FtR7nWq2K",  "name": "feature",  "color": "cobalt",  "team": null}

Update a tag

PATCH/v1/workspaces/{slug}/tags/{tag}

Renames or recolors a tag; only the fields sent change. Saved view filters follow a new name. The people who can create the tag can change it.

Path parameters

slugstringRequired

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

tagstringRequired

The tag's ID.

Body parameters

namestring

The tag's name, up to 40 characters.

colorstring

The tag's color.

One ofgrayredorangeambergreentealcobaltirispink

Returns

Returns the Tag object. Status 200.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

PATCH/v1/workspaces/{slug}/tags/{tag}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/tags/{tag} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "color": "iris"6  }'

Response200

{  "id": "Tg3FtR7nWq2K",  "name": "feature",  "color": "cobalt",  "team": null}

Delete a tag

DELETE/v1/workspaces/{slug}/tags/{tag}

Takes the tag off every ticket and out of saved view filters. The people who can create the tag can delete it.

Path parameters

slugstringRequired

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

tagstringRequired

The tag's ID.

Returns

Returns no content. Status 204.

Errors

400: InvalidInputThe request is malformed, or a value is not allowed.
401: UnauthorizedThe request has no valid API key.
403: ForbiddenThe key's user or role may not do this.
404: NotFoundThe workspace or object does not exist, or the caller cannot see it.
409: ConflictThe change conflicts with current data, such as a slug that is already in use.
500: InternalClanker Ship failed to handle the request. Retry, or report the response's x-request-id.

DELETE/v1/workspaces/{slug}/tags/{tag}

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

NextViews