Skip to main content

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​

TypeWhere to find its id
TABULATIONtabulations in GET /api/v2/workspace/{workspaceId}
REACH_TABLEreachTables in GET /api/v2/workspace/{workspaceId}
TARGETtargets in GET /api/v2/workspace/{workspaceId}, or the id returned by POST /api/v2/workspace/{workspaceId}/survey/{surveyCode}/target
USER_VARuserVars in GET /api/v2/workspace/{workspaceId}
Saved evaluationThe 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 id twice. 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.

StatuserrorCodeWhen
400AE_ERR_420The element exists but its type cannot be deleted through the API. The message names the type.
401E401The X-API-Key header is missing or empty.
403AE_ERR_418The workspace is shared with you; only its owner can delete its elements.
404AE_ERR_417The workspace does not exist, is not visible to you, or was already deleted.
404AE_ERR_419The element does not exist in that workspace, or was already deleted.
500GEN_ERR_500Unexpected error. Check the workspace before retrying.

Request​

Responses​

The element was deleted and removed from the menu of the workspace. The response has no body.