---
title: "Asset API Technical Reference"
description: "The Prismic Asset API allows you to manage your repository assets in media library."
meta_title: "Asset API Technical Reference"
audience: developers
lastUpdated: "2025-11-06T01:07:50.000Z"
---

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.

> <CalloutHeading>**Migrating to Prismic?**</CalloutHeading>
>
> For a better understanding of how to work with the Asset API in the context of a migration, [see the dedicated Migration article](https://prismic.io/docs/migration-api-technical-reference.md).

# 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.

<Table>
  <tbody>
    <tr>
      <TableCell>`repository` String (required)</TableCell> <TableCell>The repository ID (e.g. `your-repo-name`).</TableCell>
    </tr>

    <tr>
      <TableCell>`authorization` String (required)</TableCell>

      <TableCell>
        A [permanent token](https://prismic.io/docs/custom-types-api.md) or [user session token](https://prismic.io/docs/authentication-api-technical-reference.md) from the Authentication API.
      </TableCell>
    </tr>

    <tr>
      <TableCell>`origin` String</TableCell> <TableCell>The origin URL for your request.</TableCell>
    </tr>
  </tbody>
</Table>

# 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:

<Table>
  <tbody>
    <tr>
      <TableCell>`assetType` String</TableCell> <TableCell>Filter assets by type (e.g., `"all"`, `"image"`).</TableCell>
    </tr>

    <tr>
      <TableCell>`limit` Number</TableCell>

      <TableCell>
        Maximum number of assets to be returned (e.g. `100`).
      </TableCell>
    </tr>

    <tr>
      <TableCell>`cursor` String</TableCell>

      <TableCell>
        ID of the asset after which to start the query (e.g. `"1682333764A"`).
      </TableCell>
    </tr>

    <tr>
      <TableCell>`keyword` String</TableCell>

      <TableCell>
        A string to filter assets by keyword (in `title`, `filename`, `alt`, `notes` or `credits` fields).
      </TableCell>
    </tr>
  </tbody>
</Table>

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.<br /> It also accepts optional metadata properties of `notes`, `credits` and `alt` listed in PATCH below.

```tsx filename=Example Upload Asset File query
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}`,
      "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:

<Table>
  <tbody>
    <tr>
      <TableCell>`notes` text</TableCell> <TableCell>Notes about the asset. Limit: 500 characters</TableCell>
    </tr>

    <tr>
      <TableCell>`credits` text</TableCell> <TableCell>Credit for the asset. Limit: 500 characters</TableCell>
    </tr>

    <tr>
      <TableCell>`alt` text</TableCell> <TableCell>Alt text for the asset. Limit: 500 characters</TableCell>
    </tr>
  </tbody>
</Table>

# DELETE

Deletes an existing asset.

> **Important**
>
> Deleting assets that are already added to published pages will result in broken files.

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