Skip to main content

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/custom and POST /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:

ParameterValuesWhen it is omitted
orderByNAME or LAST_UPDATED, not case-sensitiveThe field of the saved order.
ascendingtrue or falseWith orderBy=NAME, true; with orderBy=LAST_UPDATED, false; without orderBy, the direction of the saved order.
  • NAME compares the workspace names in lower case, character by character, so a name that starts with an accented letter goes after the names that start with z.
  • LAST_UPDATED uses lastUpdated or, 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:

ValueMeaning
OWNOwned by the caller and not shared with other users.
SHARED_BY_MEOwned by the caller and shared with other users.
SHARED_WITH_MEOwned 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​

StatuserrorCodeWhen
400AE_ERR_401orderBy or ascending has a value that is not valid.
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​

Every workspace the caller can open, in the order saved by the caller or in the one requested with orderBy and ascending.