HTTP API Reference

Assets API reference

Upload images and files to Content Lake, and link Media Library assets to your dataset.

Use the Assets API to upload and manage assets in your Content Lake datasets. For assets stored in Media Library, use the Media Library API.

Want to get started with assets?

Assets

Sanity provides extensible UI for managing assets, and an API for dealing with storage, resizing and deletion.

Authentication

Base API server URL

Assets API base URL

https://{projectId}.api.sanity.io/{apiVersion}/assets

Variables

  • apiVersionstringdefault: "v2024-06-24"

    API version

  • projectIdstringdefault: "your-project-id"

    Sanity project ID

Endpoints

Upload an image asset

post/images/{dataset}

Upload an image asset to Content Lake. This uploads an image and creates a linked sanity.imageAsset document containing the image metadata.

Path parameters

Query parameters

  • filenamestring

    Filename for this file (optional)

  • titlestring

    Optional title for the asset

  • descriptionstring

    Optional description for the asset

  • metaarraydefault: ["palette","lqip","blurhash"]

    Array of metadata to extract from asset

    items
    • itemsstring
  • labelstring

    Optional freeform label for the asset.

  • tagstring

    Optional request tag for the upload. Learn more in the request tag documentation.

  • creditLinestring

    The credit to person(s) and/or organization(s) required by the supplier of the asset to be used when published.

  • sourceNamestring

    The name of the source if asset is from an external service.

  • sourceIdstring

    Use with sourceName. The id of the asset within the external source.

  • sourceUrlstring

    Use with sourceName. The url of the asset within the external source.

Request body image/*

  • string (binary)

    The image file to upload.

Responses

200

Upload successful

Upload a file asset

post/files/{dataset}

Upload an file asset to Content Lake. This uploads an file and creates a linked sanity.fileAsset document containing the file metadata.

Path parameters

Query parameters

  • filenamestring

    Filename for this file (optional)

  • titlestring

    Optional title for the asset

  • descriptionstring

    Optional description for the asset

  • labelstring

    Optional freeform label for the asset.

  • tagstring

    Optional request tag for the upload. Learn more in the request tag documentation.

  • creditLinestring

    The credit to person(s) and/or organization(s) required by the supplier of the asset to be used when published.

  • sourceNamestring

    The name of the source if asset is from an external service.

  • sourceIdstring

    Use with sourceName. The id of the asset within the external source.

  • sourceUrlstring

    Use with sourceName. The url of the asset within the external source.

Request body image/*

  • string (binary)

    The file binary to upload.

Responses

200

Upload successful

Upload an image asset from a URL

post/images/{dataset}/from-url

Upload an image asset from a public or preauthorized HTTPS URL and create a sanity.imageAsset document in Content Lake.

Sanity fetches the source without forwarding your API token, cookies, or request headers. The source and each redirect destination must use HTTPS without embedded credentials and pass the source policy. Up to three redirects are followed. The source is limited to 50 MiB (52,428,800 bytes), and fetching may take up to 300 seconds. The JSON request body is limited to 4 KiB.

Provide filename in the JSON body; the filename query parameter is not accepted. The other upload metadata parameters work as on the ordinary upload endpoint. Provide sourceName and sourceId together; sourceUrl is attribution metadata, not the URL to fetch.

Allow more than 300 seconds for the client request. If the connection closes or the request times out, check the dataset before retrying: the asset may already have been created. Use the returned document._id as the asset reference in an image or file field.

Path parameters

Query parameters

  • titlestring

    Optional title for the asset

  • descriptionstring

    Optional description for the asset

  • metaarraydefault: ["palette","lqip","blurhash","thumbhash"]

    Image metadata to extract. Repeat the parameter for multiple values, such as meta=palette&meta=lqip.

    items
    • itemsstring
  • labelstring

    Optional freeform label for the asset.

  • tagstring

    Optional request tag for the upload. Learn more in the request tag documentation.

  • creditLinestring

    The credit to person(s) and/or organization(s) required by the supplier of the asset to be used when published.

  • sourceNamestring

    The name of the source if asset is from an external service.

  • sourceIdstring

    Use with sourceName. The id of the asset within the external source.

  • sourceUrlstring

    Use with sourceName. The url of the asset within the external source.

Request body application/json

  • urlstring (uri)required

    Public or preauthorized HTTPS URL returning the asset bytes. URLs with embedded usernames or passwords are not supported.

  • filenamestring

    Optional original filename, including the extension. Must not contain path separators or a null character.

Examplesapplication/json
{
  "url": "https://example.com/chair.jpg",
  "filename": "chair.jpg"
}

Responses

200

Upload successful

Upload a file asset from a URL

post/files/{dataset}/from-url

Upload a file asset from a public or preauthorized HTTPS URL and create a sanity.fileAsset document in Content Lake.

Sanity fetches the source without forwarding your API token, cookies, or request headers. The source and each redirect destination must use HTTPS without embedded credentials and pass the source policy. Up to three redirects are followed. The source is limited to 50 MiB (52,428,800 bytes), and fetching may take up to 300 seconds. The JSON request body is limited to 4 KiB.

Provide filename in the JSON body; the filename query parameter is not accepted. The other upload metadata parameters work as on the ordinary upload endpoint. Provide sourceName and sourceId together; sourceUrl is attribution metadata, not the URL to fetch.

Allow more than 300 seconds for the client request. If the connection closes or the request times out, check the dataset before retrying: the asset may already have been created. Use the returned document._id as the asset reference in an image or file field.

Path parameters

Query parameters

  • titlestring

    Optional title for the asset

  • descriptionstring

    Optional description for the asset

  • labelstring

    Optional freeform label for the asset.

  • tagstring

    Optional request tag for the upload. Learn more in the request tag documentation.

  • creditLinestring

    The credit to person(s) and/or organization(s) required by the supplier of the asset to be used when published.

  • sourceNamestring

    The name of the source if asset is from an external service.

  • sourceIdstring

    Use with sourceName. The id of the asset within the external source.

  • sourceUrlstring

    Use with sourceName. The url of the asset within the external source.

Request body application/json

  • urlstring (uri)required

    Public or preauthorized HTTPS URL returning the asset bytes. URLs with embedded usernames or passwords are not supported.

  • filenamestring

    Optional original filename, including the extension. Must not contain path separators or a null character.

Examplesapplication/json
{
  "url": "https://example.com/manual.pdf",
  "filename": "manual.pdf"
}

Responses

200

Upload successful

Link a Media Library asset to a document

post/media-library-link/{dataset}

Creates a linked Media Library asset in your dataset. To support features like preview, Media Library assets need to be linked to a local asset document. Pair with mutate to attach linked Media Library assets to documents.

Path parameters

Request body application/json

  • assetIdstring

    The asset ID of the Media Library asset. This comes from the asset._id field returned as part of the response when uploading an asset to the library.

  • mediaLibraryIdstring

    The id of the Media Library.

  • assetInstanceIdstring

    The asset instance ID of the Media Library asset. This comes from the assetInstance._id field returned as part of the response when uploading an asset to the library.

Responses

200

Link created successfully