Asset API Technical Reference

The Prismic Asset API allows you to manage your repository assets in media library. This documentation provides details about the available endpoints, authentication requirements, request parameters, response models, and error handling.

Migrating to Prismic?

For a better understanding of how to work with the Asset API in the context of a migration, see the dedicated Migration article.

Limits

Each request to the API can contain one asset.

Requests are limited to one per second.

Headers

These headers should be included with each request to the Asset API.

repository

String (required)

The repository ID (e.g. your-repo-name).

authorization

String (required)

A permanent token or user session token from the Authentication API.

origin

String

The origin URL for your request.

Methods

GET

Retrieve a list of assets from the media library.

Copy

https://asset-api.prismic.io/assets

The url parameters of the request accept the following properties:

assetType

String

Filter assets by type (e.g., "all", "image").

limit

Number

Maximum number of assets to be returned (e.g. 100).

cursor

String

ID of the asset after which to start the query (e.g. "1682333764A").

keyword

String

A string to filter assets by keyword (in title, filename, alt, notes or credits fields).

An example GET response:

Copy

{
   "id":"Zestwpsz31z-H2JI",
   "url":"https://prismic-io.imgix.net/yourrepo/yourpng.png?auto=format,compress",
   "filename":"example file name.png",
   "size":157432,
   "width":2960,
   "height":1318,
   "last_modified":1709911490751,
   "kind":"image",
   "extension":"png",
   "notes":"notes text",
   "credits":"credits text",
   "alt":"alt text",
   "created_at":1709911490751
}

POST

Upload a new asset to the media library.

Copy

https://asset-api.prismic.io/assets

The body must be multipart/form-data with the asset.

It also accepts optional metadata properties of notes, credits and alt listed in PATCH below.

Example Upload Asset File query

Copy

const uploadFile = async (filePath: fs.PathLike, token: string) => {
    const formData = new FormData();
    formData.append('file', fs.createReadStream(filePath));

    const response = await axios.post(assetUrl, formData, {
        headers: {
            Authorization: `Bearer ${token}`,
            'x-api-key': apiKey,
            'Content-Type': 'multipart/form-data',
            'repository': instanceRepository,
            'Accept': "application/json"
        },
    });

    await delay(2000);
    return response
};

PATCH

Update the metadata of an existing asset.

Copy

https://asset-api.prismic.io/assets/{{asset-id}}

The body must be JSON. It accepts the following properties:

notes

text

Notes about the asset. Limit: 500 characters

credits

text

Credit for the asset. Limit: 500 characters

alt

text

Alt text for the asset. Limit: 500 characters

DELETE

Deletes an existing asset.

Deleting assets that are already added to published documents will result in broken files.

Copy

https://asset-api.prismic.io/assets/{{asset-id}}

Can't find what you're looking for?

Need technical Support? Spot an error in the documentation? Get in touch with us on our Community Forum.