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
| Field | Required | Max length |
|---|---|---|
name | Yes, not empty | 250 |
title | No | 250 |
description | No | 500 |
Unknown fields are ignored.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | VAL_ERR_001 | name is missing or empty, or a field is longer than allowed. |
| 400 | E400 | The body is not valid JSON. |
| 400 | AE_ERR_400 | The body is a JSON array, or a value has the wrong JSON type, such as an array in name. The message names the field. |
| 400 | TW_ERR_500 | The X-API-Key value does not identify a TOM user. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 500 | GEN_ERR_500 | Unexpected error. |
Request
Responses
- 200
- 400
- 401
- 500
The workspace was created. Use id as {workspaceId}. title and description are null when they were not sent, and lastUpdated is null.
The request cannot be processed. VAL_ERR_001: name is missing or empty, or a field is longer than allowed. E400: the body is not valid JSON. AE_ERR_400: the body is a JSON array, or a value has the wrong JSON type. TW_ERR_500: the X-API-Key value does not identify a TOM user.
The X-API-Key header is missing or empty.
Unexpected error.