---
title: "Mint Asset URLs"
method: POST
path: "/v3/collections/{collection_name}/documents/{document_id}/asset-urls"
tags: ["file-search"]
---

# Mint Asset URLs

`POST /v3/collections/{collection_name}/documents/{document_id}/asset-urls`

Mint short-lived presigned URLs for a document's figure crops.

Supply the figure ids (`regions[].figure_id`) to mint URLs for. When batch
requested, each item degrades on its own: a figure with no crop does not fail
the whole request.

## Path parameters

- `collection_name` string, required
- `document_id` string, required

## Request body

- AssetUrlsRequestV3
  - `asset_ids` string[], required — Figure ids to mint URLs for, from `regions[].figure_id`. Stable and safe to store, unlike the URLs they mint. Up to 100; duplicates each return their own item.
  - `ttl_seconds` integer, nullable — How long each URL stays valid, in seconds. Default 900 (15 min); min 60, max 604800 (7 days).

## Response `200`

Successful Response

- AssetUrlsResponseV3
  - `asset_urls` AssetUrlV3[]
    - `asset_id` string, required — Echoes the requested id, so a response can be keyed or positionally indexed. For figures this is `regions[].figure_id`.
    - `bbox` object, nullable
    - `content_type` string, nullable
    - `expires_at` string, nullable — RFC 3339 UTC instant after which `image_url` stops working.
    - `image_url` string, nullable
    - `kind` string — The kind of asset this id addresses, from its prefix. Currently always `figure`. Treat unknown values as opaque.
    - `message` string, nullable
    - `page` integer, nullable — The figure's page in the source document, 1-based. On a document split for parallel parsing this can differ from `regions[].page` (the page within the split as the parser saw it). This field is the one that matches the image.
    - `reason` string, nullable — Set when status is `unavailable`. Open-ended: treat unknown values as generic failures. Current values: `no_crop_available` (document indexed before figure cropping; re-index to generate crops), `figure_not_found` (no figure in this document has that id), `ocr_unavailable` (layout data could not be read; retry, do not discard the id), `signing_unavailable` (crop signing not configured on this deployment).
    - `status` 'signed' | 'unavailable', required
  - `collection_name` string, required
  - `document_id` string, required
  - `expires_at` string, nullable — Earliest expiry across all signed items, so a client can schedule a single refresh instead of one timer per image. Null when nothing was signed.
  - `expires_in_seconds` integer, nullable — Same deadline as a duration. Provided because browser clocks are routinely wrong, which makes an absolute-only expiry unreliable.
  - `signed_count` integer
  - `unavailable_count` integer
  - `warnings` string[]

## Other responses

- `403` — The API key does not have query permission on this collection.
- `404` — Collection or document not found.
- `422` — asset_ids missing, empty, over the batch limit, or malformed; or ttl_seconds out of range.

---

[API](https://skmtc.dev/runcaptain/apis/api-reference.md) · [All operations](https://skmtc.dev/runcaptain/apis/api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/runcaptain/api-reference/revisions/fe4649e3f4aa/schema)