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.

Limits

Each request to the API can contain one asset.

Requests are limited to one per second.

Headers

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 JSON body of the request accepts 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.

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.

credits

text

Credit for the asset.

alt

text

Alt text for the asset.

Was this article helpful?

Not really

Yes, Thanks

Can't find what you're looking for? Spot an error in the documentation? Get in touch with us on our Community Forum or using the feedback form above.