List workspaces
GET/api/v2/workspaces
Returns every workspace the caller can open: the ones they own and the ones other users have shared with them. The list is complete and is not paginated.
A workspace is the container where TOM keeps saved elements (tabulations, Reach tables, targets and user variables) and the surveys attached to it.
Use a workspace's id as {workspaceId} in:
GET /api/v2/workspace/{workspaceId}, to list its elements and surveys;- the workspace-scoped endpoints:
.../survey/{surveyCode}/tabulation/{elementId},.../user-vars,.../targets,.../target,.../tree/query/customandPOST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId}.
surveyCode and surveyDescription describe the survey currently active in the workspace (the one selected in the TOM web application). They are empty strings when the workspace has no active survey, for example right after POST /api/v2/workspace. surveyDescription is the name you see for the survey, as description in GET /api/v2/users/surveys; when the survey is no longer available to you, it is the name saved with the workspace. The full list of surveys attached to a workspace is returned by GET /api/v2/workspace/{workspaceId}.
Order
By default the list follows the order the caller chose in the workspaces view of the TOM web application, so that both show the workspaces in the same order. The web application saves that order when the user leaves the view. The filters and the search of the view are not applied. When the caller never chose an order, or it cannot be read, the list is sorted by last update, most recent first.
Two optional parameters ask for another order. Each one that is sent replaces the saved one:
| Parameter | Values | When it is omitted |
|---|---|---|
orderBy | NAME or LAST_UPDATED, not case-sensitive | The field of the saved order. |
ascending | true or false | With orderBy=NAME, true; with orderBy=LAST_UPDATED, false; without orderBy, the direction of the saved order. |
NAMEcompares the workspace names in lower case, character by character, so a name that starts with an accented letter goes after the names that start withz.LAST_UPDATEDuseslastUpdatedor, for a workspace without it,creationDate. A workspace without either date goes last in both directions.- Workspaces that tie keep their relative order: the caller's own workspaces by name, then the ones shared with them.
Last update and ownership
lastUpdated is the last update of the workspace itself, for example a rename, not of the elements saved in it. A workspace that was never updated also has it, set when the workspace was created. It is omitted only in some older workspaces that do not have it.
ownership tells who owns each workspace:
| Value | Meaning |
|---|---|
OWN | Owned by the caller and not shared with other users. |
SHARED_BY_ME | Owned by the caller and shared with other users. |
SHARED_WITH_ME | Owned by the user named in ownerName, who shares it with the caller. It is read only: only the owner can create, edit or delete its elements. |
lastUpdated, ownership and ownerName are returned only by this list, not by GET /api/v2/workspace/{workspaceId}.
Side effect on shared workspaces
Calling this endpoint discards your unsaved per-user changes in the workspaces shared with you, including the surveys you added to them with POST /api/v2/workspace/{workspaceId}/source, and can reset a TOM web application session that is open at the same time.
Errors
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_401 | orderBy or ascending has a value that is not valid. |
| 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
Every workspace the caller can open, in the order saved by the caller or in the one requested with orderBy and ascending.
orderBy or ascending has a value that is not valid (AE_ERR_401), or the X-API-Key value does not identify a TOM user (TW_ERR_500).
The X-API-Key header is missing or empty.
Unexpected error.