Delete an element of a workspace
DELETE/api/v2/workspace/:workspaceId/element/:elementId
Deletes one element of a workspace you own and answers 204 without a body. The element also disappears from the menu of the workspace.
The deletion is physical and irreversible: there is no recycle bin and nothing can be restored afterwards. It is the same deletion the TOM web application performs.
Element types you can delete
| Type | Where to find its id |
|---|---|
TABULATION | tabulations in GET /api/v2/workspace/{workspaceId} |
REACH_TABLE | reachTables in GET /api/v2/workspace/{workspaceId} |
TARGET | targets in GET /api/v2/workspace/{workspaceId}, or the id returned by POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/target |
USER_VAR | userVars in GET /api/v2/workspace/{workspaceId} |
| Saved evaluation | The id returned when it was saved with POST /api/v2/survey/{surveyCode}/evaluation/save/{workspaceId}. Saved evaluations are not listed by GET /api/v2/workspace/{workspaceId}, so keep that id. |
Any other element cannot be deleted through the API, including the folders and the menu of the workspace and elements of types this API does not publish. They answer 400 (AE_ERR_420) and nothing is deleted.
Before you call it
workspaceId: a workspace you own. If it is shared with you (SHARED_WITH_ME), nothing can be deleted from it: only its owner can.elementId: an element of that workspace. An element that belongs to another workspace is reported as not found.- Check the
idtwice. Nothing asks for confirmation.
Behaviour
- No dependencies are checked. Deleting a target does not change the evaluations or tables that used it: they keep the result they saved and its target label, and they are not recalculated with that target.
- Deleting an element of a workspace you own and have shared with others (
SHARED_BY_ME) is allowed; the others stop seeing the element. - Repeating a deletion that already succeeded answers
404, whenever you repeat it. - It does not require any application module: owning the workspace is enough, also to delete a saved evaluation.
- The checks run in a fixed order and the first one that fails is reported: the workspace exists and is visible (
404,AE_ERR_417), it is yours (403,AE_ERR_418), the element exists in it (404,AE_ERR_419) and its type can be deleted (400,AE_ERR_420).
Errors
errorMessage is meant for people and may change. Base your error handling on errorCode.
| Status | errorCode | When |
|---|---|---|
| 400 | AE_ERR_420 | The element exists but its type cannot be deleted through the API. The message names the type. |
| 401 | E401 | The X-API-Key header is missing or empty. |
| 403 | AE_ERR_418 | The workspace is shared with you; only its owner can delete its elements. |
| 404 | AE_ERR_417 | The workspace does not exist, is not visible to you, or was already deleted. |
| 404 | AE_ERR_419 | The element does not exist in that workspace, or was already deleted. |
| 500 | GEN_ERR_500 | Unexpected error. Check the workspace before retrying. |
Request
Responses
- 204
- 400
- 401
- 403
- 404
- 500
The element was deleted and removed from the menu of the workspace. The response has no body.
The element exists but its type cannot be deleted through the API: folders, the workspace menu, maps and any type not listed as deletable (AE_ERR_420).
The X-API-Key header is missing or empty.
The workspace is shared with the user: only its owner can delete its elements (AE_ERR_418).
The workspace does not exist, is not visible to the user or was already deleted (AE_ERR_417), or the element does not exist in that workspace or was already deleted (AE_ERR_419).
Unexpected error.