Upload Assets endpoint

Upload assets directly to Learnosity cloud storage in bulk.

Endpoints:

Upload Assets

Usage

The format of requests to the Data API use the following syntax:

https://data.learnosity.com/{LTS_VERSION}/{endpoint}

For example, to use the v2025.1.LTS version and the itembank/items endpoint, you would create a request like so:

https://data.learnosity.com/v2025.1.LTS/itembank/items

Important Data API is not a REST API. All requests must use the POST method with the action request body parameter specifying the operation to use. The Learnosity SDK must be used to make requests to Data API.

Note Data API usage is subject to rate limits.

Getting Started with the Data API
See Release Cadence and Version Lifecycle for more information on available LTS versions.

Upload Assets

Generate a set of pre-signed upload URLs (one per asset requested), which can then be used to upload the asset files themselves. The upload is done by sending an HTTP PUT request to each of the signed URLs.

The endpoint also returns the public URLs for each file so that you can retrieve the uploaded assets.

The endpoint detects the media type (MIME type) for each file based on the filename extension, for example, image/jpeg for .jpg, image/png for .png. You can override or directly specify the media type if required.

Endpoint	/{LTS_VERSION}/itembank/upload/assets
HTTP method	POST
Action type	`"get"`

Request body parameters

Body content type: application/json

subkeys array[string]

A list of the desired names for the assets. These names (or "subkeys") are used in the resulting path of the assets' public URL.

The following characters are forbidden in the asset's name:
- leading or trailing forward slash (/),
- backslash (\),
- path elements that are either . or ..,
- consecutive slashes (//), or
- empty strings.
subkey_types object

(optional) Specifies the media types for the files that can't be auto-detected.

Each file is listed as a key which corresponds to an entry in the subkeys list and the values are media types.

This can be used to indicate the required media type for files which:
- Have no filename extension, or
- Have a filename extension or media type that is not in Learnosity's default mappings.
Every key in this object must exactly match an element in the subkeys array.
organisation_id integer

Specifies the Item bank for uploading assets.

The API consumer making the request will need to have access to the Item bank. This access can be checked via the API consumers configuration in the Learnosity Console.

Default: the primary Item bank associated with the API consumer.

Request body example

{
    "organisation_id": 1,
    "subkeys": [
        "path/to/content1.jpg",
        "path/to/content2.jpg",
        "other/content3.jpg",
        "other/legacy_content"
    ],
    "subkey_types": {
        "other/legacy_content": "image/png"
    }
}

Responses

This endpoint returns an array of objects, where each object represents one of the files to be uploaded. Each object contains the following keys:

"upload": the URL for a PUT request to upload a file. This URL is accessible for a limited time (60 minutes) after which it expires and can no longer be used.
"public": the final publicly accessible URL for the file. This URL can be used as soon as the file upload is completed.
"content_type": the specified or inferred media type for this resource. This value must be included as the Content-Type header in the PUT request to the upload URL.

Uploading Asset Files Using Signed URLs

After retrieving signed upload URLs from this endpoint, files can be uploaded by sending PUT requests to those URLs.

This can be performed using a curl call, or a HTTP client of your choice. For example, the following command will upload a sample JPEG file called content1.jpg from a curl-enabled terminal to a pre-signed URL:

$ curl --request PUT \
--header "Expect: 100-continue" \
--header "Content-Type: image/jpeg" \
--data-binary "@content1.jpg" \
"https://s3.amazonaws.com/assets.learnosity.com/organisations/1/path/to/content1.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=uULtl3Yqh1UVxX6RxhCDVprxqqg%3D&x-amz-acl=public-read"

When making the PUT request:

Set the Content-Type header to the appropriate content_type value provided by the endpoint for its subkey.
Set the Expect: 100-continue header if your HTTP client supports it, to avoid transmitting unnecessary data in certain error cases. See the Expect-continue handshake optimization introduced in HTTP 1.1.

Note Since this is a PUT operation, if a signed URL is generated for an existing asset key, uploading a file will overwrite any existing content.

The signed upload URLs will expire 60 minutes after they're issued. If one or more signed URLs have expired, call this endpoint again to obtain new upload URLs.

The request will fail if the Content-Type header is omitted, or if it is not set to the exact value provided in the response from the endpoint for the corresponding subkey.

Response example

{
    "meta": {
        "status": true,
        "timestamp": 1485320066,
        "records": 3
    },
    "data": [
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/path/to/content1.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=uULtl3Yqh1UVxX6RxhCDVprxqqg%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/path/to/content1.jpg",
            "content_type": "image/jpeg"
        },
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/path/to/content2.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=IrUFv0HqVSX7c0KiiQmBTuPMjds%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/path/to/content2.jpg",
            "content_type": "image/jpeg"
        },
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/other/content3.jpg?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=X%2BfVesr8am%2FTcmlBnyT3RpWOigY%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/other/content3.jpg",
            "content_type": "image/jpeg"
        },
        {
            "upload": "https://s3.amazonaws.com/assets.learnosity.com/organisations/1/other/legacy_content?AWSAccessKeyId=AKIAJB5XQL2VQTD4KG6Q&Expires=1485323666&Signature=X%2BfVesr8am%2FTcmlBnyT3RpWOigY%3D&x-amz-acl=public-read",
            "public": "//assets.learnosity.com/organisations/1/other/legacy_content",
            "content_type": "image/png"
        }
    ]
}