Workspaces

A workspace holds a company's products, environments, planning, test runs and secrets, and the people who work on them. Every other resource belongs to one workspace, named in paths by its slug or ID.

The Workspace object

A workspace you belong to, with your role in it.

Attributes

idstringRequired

Unique ID of the workspace.

namestringRequired

The workspace's display name.

slugstringRequired

The workspace's URL name: 2 to 48 lowercase letters, digits and hyphens, such as acme.

iconUrlnullable stringRequired

URL of the workspace's icon image, or null.

rolestringRequired

Your role in the workspace: owner, admin, member or viewer.

One ofowneradminmemberviewer

The Workspace object

{  "id": "Wk7Qm2RtXa9L",  "name": "Acme",  "slug": "acme",  "iconUrl": "https://images.clankertest.com/workspaces/Wk7Qm2RtXa9L/icon-Ic5TfR2mWq8Z.png",  "role": "owner"}

List workspaces

GET/v1/workspaces

Returns the workspaces you are an active member of, with your role in each. An account API key sees only its own workspace.

Returns

Returns an array of Workspace objects. 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

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

Response200

[  {    "id": "Wk7Qm2RtXa9L",    "name": "Acme",    "slug": "acme",    "iconUrl": "https://images.clankertest.com/workspaces/Wk7Qm2RtXa9L/icon-Ic5TfR2mWq8Z.png",    "role": "owner"  }]

Create a workspace

POST/v1/workspaces

Creates a workspace with you as its owner, plus the default ticket statuses and tags. Fails with Conflict when another workspace uses the slug. Account API keys cannot create workspaces.

Body parameters

namestringRequired

The workspace's display name. Surrounding spaces are removed.

slugstringRequired

The workspace's URL name: 2 to 48 lowercase letters, digits and hyphens, such as acme. It is trimmed and lowercased, and must be unused.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the workspace was created.

Always true

workspaceobjectRequired

The new workspace.

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

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

Response200

{  "ok": true,  "workspace": {    "id": "Wk7Qm2RtXa9L",    "name": "Acme",    "slug": "acme",    "creatorUserId": "Us3NfP8kLq2V"  }}

Check a workspace slug

GET/v1/slugs/{slug}

Tells whether any workspace uses the slug, ignoring case. It does not check that the slug is well formed.

Path parameters

slugstringRequired

The slug to check, such as acme.

Query parameters

excludeWorkspaceIdstring

A workspace ID, such as Wk7Qm2RtXa9L, whose own slug counts as free.

Returns

Returns an object with these fields. Status 200.

availablebooleanRequired

Whether the slug is free to use.

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/slugs/{slug}

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

Response200

{  "available": true}

Get a workspace

GET/v1/workspaces/{slug}

Returns the workspace with its allowed domains and your role in it. Fails with NotFound unless you are an active member, or the account API key belongs to the workspace.

Path parameters

slugstringRequired

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

Returns

Returns an object with these fields. Status 200.

A workspace with its settings, and who is calling: your user ID or account API key and your role.

workspaceIdstringRequired

Unique ID of the workspace.

namestringRequired

The workspace's display name.

slugstringRequired

The workspace's URL name: 2 to 48 lowercase letters, digits and hyphens, such as acme.

iconUrlnullable stringRequired

URL of the workspace's icon image, or null.

allowedDomainsarray of stringsRequired

Email domains, such as acme.dev, whose people join the workspace as members automatically. Invites must use one of them. Empty allows any address.

rolestringRequired

Your role in the workspace: owner, admin, member or viewer.

One ofowneradminmemberviewer

userIdnullable stringRequired

Your user ID, or null when an account API key is calling.

accountApiKeyIdstring

The account API key's ID. Present only when an account API key is calling.

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}

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

Response200

{  "workspaceId": "Wk7Qm2RtXa9L",  "name": "Acme",  "slug": "acme",  "iconUrl": "https://images.clankertest.com/workspaces/Wk7Qm2RtXa9L/icon-Ic5TfR2mWq8Z.png",  "allowedDomains": [    "acme.dev"  ],  "role": "owner",  "userId": "Us3NfP8kLq2V"}

Update a workspace

PATCH/v1/workspaces/{slug}

Sets the workspace's name, slug and allowed domains, and records a workspace.updated event. Send name and slug every time. Only owners and admins can update a workspace.

Path parameters

slugstringRequired

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

Body parameters

namestringRequired

The workspace's display name. Surrounding spaces are removed.

slugstringRequired

The workspace's URL name: 2 to 48 lowercase letters, digits and hyphens. It is trimmed and lowercased, and no other workspace may use it.

allowedDomainsstring

Email domains separated by commas, spaces or semicolons, such as acme.dev, acme.com. Leaving it out or sending an empty string clears the list.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the change was made.

Always true

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}

1curl -X PATCH https://api.qa.clankership.net/v1/workspaces/acme \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -H "Content-Type: application/json" \4  -d '{5    "name": "Acme",6    "slug": "acme",7    "allowedDomains": "acme.dev"8  }'

Response200

{  "ok": true}

Check a new slug for a workspace

GET/v1/workspaces/{slug}/slug-availability

Tells whether the workspace could change to the slug in newSlug, ignoring case. The workspace's own slug counts as free. Any member can check.

Path parameters

slugstringRequired

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

Query parameters

newSlugstringRequired

The slug to check, such as acme-labs.

Returns

Returns an object with these fields. Status 200.

availablebooleanRequired

Whether the slug is free to use.

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}/slug-availability

1curl "https://api.qa.clankership.net/v1/workspaces/acme/slug-availability?newSlug=acme-labs" \2  -H "Authorization: Bearer $CLANKER_API_KEY"

Response200

{  "available": true}

Upload a workspace icon

POST/v1/workspaces/{slug}/icon

Replaces the workspace's icon with a PNG, JPEG or WebP image under 256 KB, and records a workspace.icon_updated event. Only owners and admins can change the icon.

Path parameters

slugstringRequired

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

Body parameters

iconfileRequired

A PNG, JPEG or WebP image under 256 KB for the workspace icon.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: the icon was replaced.

Always true

iconUrlstringRequired

URL of the new icon image.

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

1curl -X POST https://api.qa.clankership.net/v1/workspaces/acme/icon \2  -H "Authorization: Bearer $CLANKER_API_KEY" \3  -F "icon=@icon.png"

Response200

{  "ok": true,  "iconUrl": "https://images.clankertest.com/workspaces/Wk7Qm2RtXa9L/icon-Ic5TfR2mWq8Z.png"}

List seeded workspaces

GET/v1/workspaces/{slug}/seeds

Returns the seeded local development workspace when this database has it, and whether you have joined it. You must belong to the workspace in the path; it does not filter the results.

Path parameters

slugstringRequired

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

Returns

Returns an array of objects with these fields. Status 200.

The seeded workspace, or nothing when this database does not have it.

idstringRequired

Unique ID of the seeded workspace.

namestringRequired

The workspace's display name.

slugstringRequired

The workspace's URL name: 2 to 48 lowercase letters, digits and hyphens, such as acme.

descriptionstringRequired

What the seeded workspace is for.

joinedbooleanRequired

Whether you are an active member of it.

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

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

Response200

[  {    "id": "localClanker",    "name": "Clanker Ship",    "slug": "clanker-ship",    "description": "Clanker Ship's own products and environments, with sample teams, projects and tickets.",    "joined": false  }]

Join a seeded workspace

POST/v1/seeds/{workspaceId}/join

Makes you an owner of a seeded local development workspace. Fails with InvalidInput when the ID is not a seeded workspace or the workspace is missing from this database.

Path parameters

workspaceIdstringRequired

The seeded workspace's ID, such as localClanker.

Returns

Returns an object with these fields. Status 200.

okbooleanRequired

Always true: you joined.

Always true

slugstringRequired

The seeded workspace's slug, such as clanker-ship.

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/seeds/{workspaceId}/join

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

Response200

{  "ok": true,  "slug": "clanker-ship"}

NextMembers