> ## Documentation Index
> Fetch the complete documentation index at: https://developers.perform.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Retrieve Shipment documents

> Download documents attached to Shipments — one by UUID, or across up to ten Shipments at once.

Shipments carry documents — shipping labels, invoices, customs declarations — added by you at creation, generated by Perform.AI, or issued by carriers through booking. Two endpoints retrieve them; full specs in the API reference: [List Documents](/api-reference/v5/documents/list-documents) and [Retrieve a Document](/api-reference/v5/documents/retrieve-a-document).

## List documents across Shipments

`GET /v5/shipments/documents/` returns the documents of up to **10** Shipments per request. Identify them with **either** `shipment_uuids` **or** `shipment_ids` — never both — comma-joined without spaces:

```bash theme={null}
curl --request GET \
  --url 'https://api.perform.ai/v5/shipments/documents/?shipment_ids=SHP-2026-000002,SHP-2026-000003' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

Each document comes with its Shipment context, metadata (`name`, `type`, `file_format`, `created_date`, `additional_info`), and a `download_url`. Results are page-based: `limit` 25–100 (default 25), `page` from 1, with `total_pages` in the response. No matching documents returns HTTP 200 with an empty `data` array.

## Retrieve one document

`GET /v5/shipments/documents/{document_uuid}/` fetches a single document by the `document_uuid` you got from a listing, a Shipment's details, or a booking response:

```bash theme={null}
curl --request GET \
  --url 'https://api.perform.ai/v5/shipments/documents/c49ff8f4-33c1-4c5f-a1c5-cfa84c18d305/' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN'
```

This endpoint returns the document **two ways**: the `download_url` *and* a `base64_content` string — use the latter when you want the bytes without a second fetch. An unknown UUID returns HTTP 404 (`"No document is found"`).

## Rules to build around

<Warning>
  **Every `download_url` expires after 1 hour**, and each call generates a fresh one. Never store the URL — store the `document_uuid` and fetch a new link when you need the file.
</Warning>

* Providing both `shipment_uuids` and `shipment_ids` in one listing call fails validation: `Please provide either shipment_uuids or shipment_ids to proceed.`
* Document `type` values such as `shipping_label` and `shipping_label_qr` are how label filtering works — the Retrieve Labels endpoint (Booking section) is this listing pre-filtered to label types.
* `additional_info` often carries format details worth reading before printing — label size (A6, 4x6) or ZPL dialect.

## Next steps

* Labels specifically: the Retrieve Labels guide (Booking & labels section).
* Attach your own documents at [creation](/guides/create-shipment) or by [update](/guides/update-shipment) — via public or allowlisted URLs.