Teams

A team is a group of workspace members that owns tickets. Its key, such as WEB, starts the IDs of its tickets (WEB-31), and each team has its own ticket statuses and views. Open teams are listed for everyone; private teams only for their members and for owners and admins.

The Team object

A group of workspace members that owns tickets and numbers them with its key, such as WEB-31.

Attributes

idstringRequired

Unique ID of the team.

keystringRequired

2 to 5 capital letters that start the team's ticket IDs, such as WEB.

namestringRequired

The team's display name.

visibilitystringRequired

Who sees the team: open teams are listed for everyone in the workspace, private teams only for their members and for owners and admins.

One ofopenprivate

archivedAtnullable stringRequired

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

membersarray of objectsRequired

The team's members, sorted by name.

joinedbooleanRequired

Whether the caller is a member. Always false for an account API key.

createdAtstringRequired

When it was created, as an ISO 8601 timestamp.

updatedAtstringRequired

When it last changed, as an ISO 8601 timestamp.

The Team object

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

List teams

GET/v1/workspaces/{slug}/teams

Returns open teams and the private teams the caller is in; owners, admins and account API keys see every team. Archived teams are left out unless archived asks for them.

Path parameters

slugstringRequired

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

Query parameters

archivedstring

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

One ofexcludeincludeonly

Returns

Returns an object with these fields. Status 200.

teamsarray of Team objectsRequired

The teams, 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}/teams

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

Response200

{  "teams": [    {      "id": "Tm6PzN3kWq1J",      "key": "WEB",      "name": "Web",      "visibility": "open",      "archivedAt": null,      "members": [        {          "id": "Us3NfP8kLq2V",          "name": "Maya Patel",          "email": "maya@acme.dev"        },        {          "id": "Us9DcT4wHn6R",          "name": "Sam Okafor",          "email": "sam@acme.dev"        }      ],      "joined": true,      "createdAt": "2026-10-01T16:20:00.000Z",      "updatedAt": "2026-10-14T09:05:12.000Z"    }  ]}

Create a team

POST/v1/workspaces/{slug}/teams

Owners and admins create teams. The key and name must be unused in the workspace. The team copies the workspace's ticket status template, starts with the default views, and the person who creates it joins it.

Path parameters

slugstringRequired

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

Body parameters

namestringRequired

The team's display name, up to 80 characters, unique in the workspace.

keystringRequired

2 to 5 letters that start the team's ticket IDs, such as WEB. Stored in capitals.

visibilitystring

open lists the team for everyone in the workspace; private only for its members and for owners and admins. Defaults to open.

One ofopenprivate

Returns

Returns the Team 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}/teams

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

Response201

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Get a team

GET/v1/workspaces/{slug}/teams/{team}

Returns one team, archived or not, with its members. A caller who cannot see a private team gets NotFound.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

Returns

Returns the Team object. Status 200.

Errors

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

GET/v1/workspaces/{slug}/teams/{team}

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

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Update a team

PATCH/v1/workspaces/{slug}/teams/{team}

Owners and admins change teams. Only the fields sent change. A new key or name must be unused, and the key changes only while the team has no tickets.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

Body parameters

namestring

The team's display name, up to 80 characters, unique in the workspace.

keystring

2 to 5 letters that start the team's ticket IDs, such as WEB. Changes only while the team has no tickets.

visibilitystring

open lists the team for everyone in the workspace; private only for its members and for owners and admins.

One ofopenprivate

Returns

Returns the Team 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}/teams/{team}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme/teams/{team} \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Web platform",6    "visibility": "private"7  }'

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Delete a team

DELETE/v1/workspaces/{slug}/teams/{team}

Owners and admins delete a team that has no tickets. A team with tickets fails with Conflict; archive it instead.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

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}/teams/{team}

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

Archive a team

POST/v1/workspaces/{slug}/teams/{team}/archive

Owners and admins archive teams. The team leaves lists, and its tickets stay readable but take no changes until it is restored. Archiving an archived team changes nothing.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

Returns

Returns the Team object. Status 200.

Errors

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

POST/v1/workspaces/{slug}/teams/{team}/archive

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

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Restore a team

POST/v1/workspaces/{slug}/teams/{team}/restore

Owners and admins bring an archived team back, so its tickets take changes again. Restoring an active team changes nothing.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

Returns

Returns the Team object. Status 200.

Errors

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

POST/v1/workspaces/{slug}/teams/{team}/restore

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

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Join a team

POST/v1/workspaces/{slug}/teams/{team}/join

Adds the caller to an open team. Owners and admins can also join private teams, and an account API key cannot join any. Joining a team twice changes nothing.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

Returns

Returns the Team object. Status 200.

Errors

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

POST/v1/workspaces/{slug}/teams/{team}/join

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

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Add a team member

POST/v1/workspaces/{slug}/teams/{team}/members

Adds a workspace member to the team, which is how private teams grow. The team's members and workspace owners and admins add people; viewers cannot. Adding a member twice changes nothing.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

Body parameters

personstringRequired

The workspace member to add, by user ID or email address.

Returns

Returns the Team object. Status 200.

Errors

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

POST/v1/workspaces/{slug}/teams/{team}/members

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/teams/{team}/members \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "person": "sam@acme.dev"6  }'

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

Remove a team member

DELETE/v1/workspaces/{slug}/teams/{team}/members/{person}

Removes a person from the team. Anyone can leave a team; removing someone else takes a member of the team or a workspace owner or admin, and viewers cannot.

Path parameters

slugstringRequired

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

teamstringRequired

The team's key, such as WEB.

personstringRequired

The member's user ID or email address, such as sam@acme.dev.

Returns

Returns the Team 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.

DELETE/v1/workspaces/{slug}/teams/{team}/members/{person}

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

Response200

{  "id": "Tm6PzN3kWq1J",  "key": "WEB",  "name": "Web",  "visibility": "open",  "archivedAt": null,  "members": [    {      "id": "Us3NfP8kLq2V",      "name": "Maya Patel",      "email": "maya@acme.dev"    },    {      "id": "Us9DcT4wHn6R",      "name": "Sam Okafor",      "email": "sam@acme.dev"    }  ],  "joined": true,  "createdAt": "2026-10-01T16:20:00.000Z",  "updatedAt": "2026-10-14T09:05:12.000Z"}

NextProjects