Coming soon. This endpoint is not available yet, and the details below may change before release.
Submits an asynchronous job that creates up to 100 content records.
The endpoint responds immediately with 202 Accepted and a jobId; the records are created in the background. Poll GET /contents/bulk/{jobId} for progress and per-item results. Each successful result carries the new content's id and its presigned upload URLs, so a single poll gives you everything you need to start uploading.
Validation happens to the whole batch, up front
The batch is validated before any job is created, so a malformed request never half-runs:
- every entry invalid —
422, no job created; - some entries invalid —207, no job created, with a breakdown of which entries were rejected and why. Correct them and resubmit the whole batch.
Failures that only show up while the job is running — a bad upload, an unresolvable author — are reported per item in the job's results[] instead, and do not stop the rest of the batch.
Resubmitting is safe, but only with the same key
Every submission must carry an Idempotency-Key header. Replaying a request with the same key returns the job that already exists rather than starting a second one, which is what makes a retry after a timeout safe. Note this deduplicates submissions, not content — two submissions with different keys will create two sets of records.
Each entry takes the same body as POST /contents, so the same rules apply per entry: the item cap, the one-e-learning-item limit, and skills and topics requiring publishWhenReady.
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.
Caller-generated idempotency key for the submission. Generate it once per logical submission and reuse it on retries — replaying the same key returns the existing job instead of creating a duplicate. Requests without the header are rejected with 422.
Create two records in one submission
Each entry is the same body POST /contents takes. Remember the Idempotency-Key header — without it the submission is rejected.
{
"contents": [
{
"title": "Fire safety",
"primaryCategory": "article",
"authorRef": "UID30084022",
"languageCode": "en-gb",
"items": [
{
"type": "rich_text",
"rank": "0",
"summary": "Fire safety basics",
"meta": {
"body": "Fire safety basics.
"
}
}
]
},
{
"title": "Data protection",
"primaryCategory": "elearning",
"authorRef": "UID30084022",
"languageCode": "en-gb",
"items": [
{
"type": "elearning",
"rank": "0",
"meta": {
"name": "gdpr.zip",
"uploadId": "1a2b3c4d-5e6f-4708-9a0b-1c2d3e4f5a6b"
}
}
]
}
]
}The content records to create.
The content records to create, at most 100 per submission
The content record to create, along with its initial items.
Title of the content
How the content should be categorised in the catalogue. Taken as you declare it — it is not inferred from the items you send.
The language of the content. Normalised before it is stored: en and en-GB both resolve to en-gb, de-at resolves to de. A language the platform does not support is rejected.
Publish the content automatically as soon as it becomes ready. Because readiness waits on item processing and the thumbnail, this normally happens some time after this request returns.
How a learner completes this content. auto, confirm and external apply to any content; on_elearning_completion requires an e-learning item; on_passing_quizzes, on_passing_observer_completed_quizzes and on_passing_assessments apply to quiz and assessment items, which are not yet supported by this API.
Note that on_elearning_completion combined with a web-format e-learning package can never reach ready.
Skills to associate with the content. Only stored when publishWhenReady is also set — sending skills without it is rejected with 422. Otherwise set them on the publish call.
Topics to associate with the content. Only stored when publishWhenReady is also set — sending topics without it is rejected with 422. Otherwise set them on the publish call.
A publicly reachable image we should fetch and use as the content thumbnail. Content cannot reach ready without a thumbnail, so either supply this or upload your own image to the thumbnailUploadUrl returned in the response. Either way the image is processed asynchronously.
The items that make up the content. Optional, but content with no items can never reach ready and so can never be published.
At most one upload item (e-learning, file, video, audio, image) plus one non-upload item (rich text, url) per request. Add further items later with PATCH /contents/{id}.
One item within a content record. The type decides which meta fields apply.
Upload items — elearning, file, video, audio and image — are two-phase: you declare the item here with an uploadId you generate, then PUT the file to the matching URL returned in signedPutUrls. The item stays at processing until the platform has handled the file.
Non-upload items — rich_text is ready immediately; url is scraped asynchronously for its title, description and image.
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
The file name, including its extension. The extension must match the item type you declared — a .pdf sent as a video is rejected.
A UUID you generate for this upload. It is echoed back in signedPutUrls so you can tell which URL belongs to which item, and must be unique within the content.
Whether learners may download the original file
The package format. Normally detected while the package is unpacked, so you rarely need to send it. A web package cannot be used with a completionType of on_elearning_completion.
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
The file name, including its extension. The extension must match the item type you declared — a .pdf sent as a video is rejected.
A UUID you generate for this upload. It is echoed back in signedPutUrls so you can tell which URL belongs to which item, and must be unique within the content.
Whether learners may download the original file
The document's page count, used to estimate its duration.
This field is under review. It is currently required, but the page count cannot be known until after the file has been uploaded. Document items are therefore not yet usable end to end, and this requirement is expected to be relaxed before release.
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
The file name, including its extension. The extension must match the item type you declared — a .pdf sent as a video is rejected.
A UUID you generate for this upload. It is echoed back in signedPutUrls so you can tell which URL belongs to which item, and must be unique within the content.
Whether learners may download the original file
The spoken language of the video
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
The file name, including its extension. The extension must match the item type you declared — a .pdf sent as a video is rejected.
A UUID you generate for this upload. It is echoed back in signedPutUrls so you can tell which URL belongs to which item, and must be unique within the content.
Whether learners may download the original file
The audio duration in milliseconds.
This field is under review. It is currently required, but the duration cannot be known until after the file has been uploaded. Audio items are therefore not yet usable end to end, and this requirement is expected to be relaxed before release.
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
The file name, including its extension. The extension must match the item type you declared — a .pdf sent as a video is rejected.
A UUID you generate for this upload. It is echoed back in signedPutUrls so you can tell which URL belongs to which item, and must be unique within the content.
Whether learners may download the original file
Alternative text, used by screen readers
A caption shown beneath the image
A link to open when the image is selected
Whether ctaUrl opens in a new tab
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
The rich text body as HTML
The item's position within the content, lowest first. Required, and every item in a content record must have a different rank.
A short label for the item, shown to learners. Optional on upload items; required on rich text and link items.
Either an external link or a reference to other content on the platform. External links must be publicly reachable — those resolving to internal or private addresses are rejected.
Accepted — a bulk create job was created (or an existing job was matched by idempotency key). Poll pollUrl for progress and per-item results.
Job accepted
The batch was accepted. Poll pollUrl for progress and per-entry results.
{
"jobId": "6863f9a2c1d2e3f4a5b6c7d8",
"status": "pending",
"pollUrl": "/rest/v2/contents/bulk/6863f9a2c1d2e3f4a5b6c7d8"
}Returned when a bulk content job has been accepted for processing.
The id of the job processing the batch
The processing status of a bulk job
The path to poll for progress and per-item results
Multi-Status — some entries failed validation, so no job was created. The envelope lists the entries that passed and the ones that were rejected, so the batch can be corrected and resubmitted.
Some entries rejected, no job created
Entry 2 failed validation, so nothing was submitted. Correct it and resubmit the whole batch.
{
"success": {
"count": "2",
"entities": [
{
"reference": "contents[0]"
},
{
"reference": "contents[1]"
}
]
},
"failure": {
"count": "1",
"entities": [
{
"reference": "contents[2]",
"message": "title is required"
}
]
}
}A multi-status envelope returned when some entries in the batch failed validation. No job is created — correct the failed entries and resubmit the whole batch.
The entries that passed validation
The number of entries that passed validation
The entry's position in the submitted array
The entries that failed validation
The number of entries that failed validation
The entry's position in the submitted array
The reason the entry was rejected
Unauthorized
Unauthorized
Forbidden
Forbidden
Unsupported Media Type — Content-Type must be application/json
The request could not be processed due to a validation error
Unprocessable Content — the submission was rejected before any job was created. This happens when the batch array is missing or empty, contains more than 100 entries, or no entry in it passed validation; and when the Idempotency-Key header is absent.
A batch in which only some entries fail validation returns 207 instead, so that you can see which ones to correct.
The request could not be processed due to a validation error
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