Permanently deletes a content record. This cannot be undone.
Deletion removes the content, every file uploaded to it, and everything derived from them. There is no recoverable state. For a reversible take-down use POST /contents/{id}/archive instead.
Only content created through POST /contents or the authoring tool can be deleted here; legacy content of other types answers 404, as does an id that has already been deleted.
Published content must be archived first — deleting a published record returns 409. Any other record can be deleted directly: one that reads as created on GET /contents/{id}, which covers both a draft and a ready record, or one that is archived. The check belongs to the content source, which applies it as it deletes, so archiving and deleting in quick succession is safe.
Deletion is not atomic, and the content source removes the record before the files and the data derived from them. A failure therefore does not tell you how far it got: the record can still be there, or it can be gone with its files left behind. Re-sending the same delete is safe — it deletes a record that is still there, and returns 404 once the record has gone — but it cannot clear what a failed deletion left behind. Report a failed deletion to support so the leftovers are removed.
The V1 reads are updated asynchronously, so for a short time after the delete a record can still appear in GET /rest/v1/contents, and its id can still answer 200 from GET /rest/v1/contents/{id}. Take the 200 from this delete as the outcome; do not confirm it with a V1 read.
authorRef is required. It is your organisation's reference for the acting user, and the deletion is recorded against that user. It is validated before anything is deleted — a reference that does not resolve answers 422 with the record untouched. collaborationId is not accepted: a delete records no authorship of its own, so the field could change nothing.
The body is required, so this route needs a Content-Type of application/json and a body on the DELETE; there is no header or query alternative. A client that cannot send a body on a DELETE cannot call this route.
OAuth2 (Cognito) tokens need the api/write or api/all scope. API tokens are not scoped, so any API key with access to the organisation can call this route.
HTTP Basic authentication using your Tenant ID and API secret.
- Username is the Tenant ID (i.e.
eu-west-2_AbcdEfghI) - Password is the API secret you would have received.
You can also authenticate using OAuth 2.0 client credentials (oauth2 security scheme) instead of Basic auth.
OAuth 2.0 client credentials authentication.
Use the following token endpoints (replace :tenantId with your Tenant ID):
Public API access tokens
- Staging:
https://public.api.learnstaging.link/oauth2/token/:tenantId - Production:
https://public.api.learn.link/oauth2/token/:tenantId - Staging MEA:
https://public.api.meastaging.learn.tech/oauth2/token/:tenantId - Production MEA:
https://public.api.mea.learn.tech/oauth2/token/:tenantId
- Staging:
Webhooks access tokens
- Staging:
https://user.api.learnstaging.link/oauth2/token/:tenantId - Production:
https://user.api.learn.link/oauth2/token/:tenantId - Staging MEA:
https://user.api.meastaging.learn.tech/oauth2/token/:tenantId - Production MEA:
https://user.api.mea.learn.tech/oauth2/token/:tenantId
- Staging:
All access tokens must be sent using the Authorization: Bearer <access_token> header.
Scopes
For API access (non-webhooks), the following scopes are available:
api/all– Full read and write access to the API.api/read– Read-only access to the API.api/write– Write access to the API.
For webhooks, the following scopes are available:
api/webhooks– Access to webhook functionality.api/all– Full read and write access to the API, including webhooks.
Tokens must include appropriate scopes for the endpoints you wish to call.
Unique identifier of the content item
Identify the acting user
The deletion must say who is performing it. authorRef is the only field.
{
"authorRef": "UID30084022"
}Who is performing the deletion. There is nothing else to say about a delete — no field here selects what is removed, or overrides the rule that a published record must be archived first. authorRef is validated in your organisation before anything is deleted. collaborationId is not accepted: a delete records no authorship of its own, so the field could change nothing.
Your organisation's reference for the acting user. The deletion is recorded against this user. A suspended or deleted user is rejected.
The content was deleted. The response carries the id only — there is no record left to return.
The id of the deleted content, echoed so that a caller logging the response has the subject of the delete in it.
Unauthorized
Unauthorized
Forbidden — the OAuth2 token does not carry the api/write or api/all scope
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Not Found — the id does not match a content record in your organisation, the record is legacy content of another type, or the record has already been deleted
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Conflict — the content is published and must be archived before it can be deleted
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Unsupported Media Type — Content-Type must be application/json
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Unprocessable Content — the body is missing, or a field failed validation (see violations), or authorRef does not match an active user in this organisation. Nothing was deleted.
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Too Many Requests — the upstream content source is rate limiting this organisation. Retry after the Retry-After header when it is present.
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Internal Server Error — the request failed inside the API service. When the message says the content was not deleted, nothing was sent upstream and the record is untouched. Otherwise the delete may have run — a re-send is safe, and answers 404 once the record is gone.
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
Upstream content source failure — the delete may not have run at all, or it may have removed the record and failed before the rest. A re-send is safe, but it cannot finish a deletion that failed part-way. See the endpoint description.
The error envelope of the V2 endpoints.
Present on field validation failures. One entry per failed rule.
One failed validation rule.
The dotted path of the field that failed, for example items.0.meta.body. Empty for a body-level rule.
Why the field failed.
An unexpected error has occurred
When any default error occurs it may be a system failure and persistent errors may require support.
The server is unable to process the request