Asset API Technical Reference

The Prismic Asset API allows you to manage your repository assets in media library.

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

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.

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:

{
   "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.

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

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.

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.

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