Publishes a content record, making it visible in the catalogue.
The content must be ready: every item has completed processing and the content has a thumbnail. Publishing anything else returns 409 with a message that says why — not ready yet, already published, or archived. Both a draft and a ready record read as created on GET /rest/v1/contents/{id}, so use the per-item status there to tell them apart: the content is ready once every item is ok and a thumbnail is set. The usual flow is: create with thumbnail and any upload items, PUT the image and the files to the signed URLs, poll the read until every item is ok, then publish.
This is one of three ways to publish. publishWhenReady on create publishes automatically; this endpoint publishes on demand; the authoring UI publishes manually. A fully API-driven integration never has to touch the UI, and a UI-first one is never forced to auto-publish.
authorRef is required and is recorded as the publisher. It is your organisation's reference for the acting user, who must exist and be active. Nothing is published until it resolves. collaborationId is not accepted: ownership is set on create and a publish never changes it, so the field could change nothing.
Skills and topics. The content is published with the skills and topics it was created with, unless the request sends a list. A sent skills list replaces the stored skills and keeps the stored topics; a sent topics list replaces the stored topics and keeps the stored skills. Send an empty list to publish without that group. Every sent skill must already exist in your organisation; a topic is a free name. A name cannot appear in both lists. This endpoint and create with publishWhenReady are the only two places skills and topics can be set.
Backdating. An optional publishedAt records an earlier publish date, for content that was originally published elsewhere. It cannot be in the future. The date is applied by a second write after the publish, and that second write is not atomic with the first: if it fails, the content is live with the publish time of the call, the failure is logged, and the response is still 200. The response then carries publishedAtApplied: false, which is the signal to read for this case; the backdate sets createdAt and contentBodyUpdatedAt, while contentHistory keeps the time of the call. There is no retry, and a repeat call answers 409 because the content is already published, so a date that was not applied cannot be repaired through this API today.
OAuth2 (Cognito) tokens need the api/write or api/all scope. API tokens are not scoped.
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
Publish with a backdated publish date
Publishes content that has reached ready, replacing the skills and topics it was created with and recording the date it was originally published elsewhere. Omit skills and topics to publish with the lists the content was created with.
{
"authorRef": "UID30084022",
"skills": [
"leadership"
],
"topics": [
"onboarding"
],
"publishedAt": "2024-03-01T00:00:00.000Z"
}Who is publishing, the skills and topics to publish with, and an optional earlier publish date. authorRef is validated in your organisation before anything is published. collaborationId is not accepted: ownership is set on create and a publish never changes it, so the field could change nothing.
Your organisation's reference for the acting user. The user is recorded as the publisher. The user must be active. A new, suspended, expired or deleted user is rejected.
The complete list of skills to publish with. Sending this field replaces the skills the content was created with and keeps its topics; omitting it keeps both. Each name must be an existing skill in your organisation, or the request is rejected with 422. An empty list publishes with no skills.
The complete list of topics to publish with. Sending this field replaces the topics the content was created with and keeps its skills; omitting it keeps both. Free names; a topic is not checked against your organisation's tags. An empty list publishes with no topics. A name cannot appear in both lists.
The publish date to record, for content that was originally published elsewhere. ISO-8601, not in the future. Applied by a second write after the publish; see the endpoint description for the failure mode. Defaults to the time of the call.
The published content. tags, skills and topics carry the list the content was published with.
Published with a backdated publish date
Every item has reached ok and the content is now live in the catalogue. The backdate set createdAt to the date sent, while the contentHistory entries keep the time of the call.
{
"id": "5f9d88d6e1b2a34c56d78902",
"title": "Onboarding pack",
"tags": [
"leadership",
"onboarding"
],
"skills": [
"leadership"
],
"topics": [
"onboarding"
],
"type": "mixed",
"createdAt": "2024-03-01T00:00:00.000Z",
"updatedAt": "2026-09-11T10:00:00.000Z",
"author": "5c69be0e3a38412f022b4719",
"isOfficial": false,
"duration": {
"value": 15,
"unit": "minutes"
},
"contentHistory": [
{
"action": "created",
"timestamp": "2026-09-11T10:00:00.000Z",
"performedBy": {
"type": "user",
"value": "5c69be0e3a38412f022b4719"
}
},
{
"action": "published",
"timestamp": "2026-09-11T10:00:00.000Z",
"performedBy": {
"type": "user",
"value": "5c69be0e3a38412f022b4719"
}
}
],
"lastUpdatedBy": {
"id": "5c69be0e3a38412f022b4719",
"email": "author@example.com",
"reference": "UID30084022"
},
"provider": {
"id": "thrive",
"name": "Thrive"
},
"status": "published",
"items": [
{
"id": "5c8936159ec2d00010cdd334",
"type": "elearning",
"status": "ok"
},
{
"id": "5c8936159ec2d00010cdd335",
"type": "rich_text",
"status": "ok"
}
]
}The published content, in the same shape as GET /contents/{id}. In the rare case that the content was published but could not be read back, the response is the minimal form: id and status only. The content is published in both cases — do not retry the request; a retry answers 409. A full body also satisfies the minimal shape, so this is anyOf. Both forms carry publishedAtApplied when the request sent publishedAt.
Whether the publishedAt you sent was written. Present only when the request carried the field. false says the content is published but keeps the publish time of the call: the second write failed, it is not retried, and a repeat of this request answers 409.
Unique identifier for the content
Title of the content
Detailed description of the content, may contain HTML
List of tags associated with this content. Omitted when the tag source cannot be read, so an absent field means "tags unavailable" rather than "no tags".
The tags entries that the taxonomy marks as a skill. Additive: every name is also in tags. A tag the taxonomy does not hold is in neither skills nor topics. Both fields are absent when the taxonomy cannot be read.
The tags entries that the taxonomy marks as a topic. Additive: every name is also in tags. A tag the taxonomy does not hold is in neither topics nor skills. Both fields are absent when the taxonomy cannot be read.
The kind of artifact associated with this content record.
Courses are represented as pathway. Pathways will be served by a dedicated Pathways API in a future release and will stop appearing on this endpoint at that point, so treat pathway as temporary here.
Timestamp when the content was created
Timestamp when the content was last updated
User ID who authored this content. Nullable for auto-curated content.
Whether the content has been recognized for its importance or validity by the customer organization
The CPD category the content is recorded against, or null when it has none. Present when a record is read by its id or returned by a v2 create or update, for content held by the content source that carries CPD data. The field is not present in the results of the list endpoint, nor on a record that exists only in the legacy content source.
The expected time to complete the content. Null for Event content types. For SAP-imported content, this value may reflect a system default rather than a precise measured duration.
Duration in the specified unit. Null when no duration is available (e.g. pathways).
The unit of the duration value. Always 'minutes'.
Chronological history of actions on this content (from content-service). May be empty when there is no recorded history.
Type of change or event recorded for the content.
When the action occurred.
Kind of actor (for example user or system).
Identifier or value associated with the actor.
Last actor who updated the content, derived from history (or author fallback). Null when neither history nor author resolves.
User ID or service identifier.
Email from the user view when available.
External reference (e.g. HR id) when stored on the user view.
The content provider. Defaults to Thrive for natively created content.
Provider identifier key.
Human-readable provider display name.
Lifecycle status of the content. A legacy (content-service) record derives the value: archived content reports archived, content with a publish time reports published, and all other content reports created. A content-core record maps its lifecycle status onto the same values, where draft and ready both report created. deleted is a filter value only and is never returned: a legacy record returned by a deleted status filter reports its pre-deletion state, and a deleted content-core record is physically gone.
The items that make up a content record, with per-item processing state. Only GET /contents/{id} returns this field, and only for records served from content-core; the GET /contents list never includes it.
One item within a content record, with its processing state.
Unique identifier for the item
The item type
The item's position within the content, lowest first
A short label for the item, shown to learners
The item's processing state. An item must reach ok before the content can become ready.
Why processing failed, when status is error
Unique identifier for the content
Bad Request — a name appears in both skills and topics, or the upstream content source rejected the payload (see violations when 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.
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 — no content with this id. Only content created through POST /contents or the authoring tool can be published here; legacy content of other types is not addressable by this endpoint.
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 cannot be published. The message says why: it is not ready yet (an item is still processing or failed, or there is no thumbnail), it is already published, or it is archived. Nothing is changed.
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. A body is required, because authorRef has no other transport.
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 — a field failed validation (see violations, for example a publishedAt in the future), authorRef does not match an active user in this organisation, or a skill is not an existing skill in this organisation. Nothing is published.
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 before the publish was sent. The content was not published.
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.
Bad Gateway. Read the message to learn what the state of the content is. When the message says the skills could not be verified, that the content could not be read, that the stored tags could not be classified, or that the tags could not be saved, the work ran before the publish and the content was not published. When the message names an upstream content source failure, the publish had already started: the upstream service sets the status before it announces the change, so the content may be live. Read it back before you retry — a retry answers 409 when the publish did land.
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