Skip to main content

Create a workspace

POST 

/api/v2/workspace

Creates an empty workspace owned by the caller and returns its identifier.

The owner is the user identified by X-API-Key; you do not send it.

Only name is required. Names do not need to be unique, so every successful call creates a new workspace. Do not retry blindly after a timeout: check GET /api/v2/workspaces first.

After creating it​

The response echoes name, title and description. title and description are null when they were not sent, and lastUpdated is null.

The new workspace has no surveys and no active survey (surveyCode is empty in GET /api/v2/workspaces). Attach a survey with POST /api/v2/workspace/{workspaceId}/source. Use the returned id as {workspaceId} in the workspace endpoints, for example to create targets or save evaluations.

Request rules​

FieldRequiredMax length
nameYes, not empty250
titleNo250
descriptionNo500

Unknown fields are ignored.

Errors​

StatuserrorCodeWhen
400VAL_ERR_001name is missing or empty, or a field is longer than allowed.
400E400The body is not valid JSON.
400AE_ERR_400The body is a JSON array, or a value has the wrong JSON type, such as an array in name. The message names the field.
400TW_ERR_500The X-API-Key value does not identify a TOM user.
401E401The X-API-Key header is missing or empty.
500GEN_ERR_500Unexpected error.

Request​

Responses​

The workspace was created. Use id as {workspaceId}. title and description are null when they were not sent, and lastUpdated is null.