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.

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}}

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.