---
title: "List page images"
method: GET
path: "/documents/{documentId}/pages"
tags: ["Documents"]
---

# List page images

`GET /documents/{documentId}/pages`

## Request

- Base URL: `https://inkseal.net/api/v1`
- URL: `https://inkseal.net/api/v1/documents/{documentId}/pages`
- Auth: HTTP bearer

The page images available for a document, with the pixel dimensions of each and the path to fetch it from.

`source` says which stored set answered. `signing_render` is the full-resolution set rasterized when an envelope is sent, pixel for pixel what a signer sees. `preview` is the small set written during conversion, which covers only the first few pages and is all that exists before a send, so `imageCount` can be smaller than `documentPageCount`.

Every `url` is a path on this API, never a storage URL, and the caller re-presents its credential for each image. The storage key behind an image is never returned.

A ready document with no images at all answers 409 `pages_not_rendered` rather than an empty list, which would read as "this document has zero pages".

## Query parameters

- `from` integer
- `limit` integer

## Response `200`

The window of page images requested.

- object
  - `data` DocumentPageList, required
    - `documentId` string, required: A document's public id: a 21-character URL-safe nanoid. Internal row ids and storage keys are never exposed.
    - `source` 'signing_render' | 'preview', required: Which stored set the images came from. `signing_render` is the full-resolution set rasterized when an envelope is sent, pixel for pixel what a signer sees. `preview` is the small set written during conversion, covering only the first few pages.
    - `imageCount` integer, required: How many pages have images. Smaller than `documentPageCount` while only previews exist.
    - `documentPageCount` integer, nullable, required: How many pages the document has.
    - `from` integer, required: The page index this window starts at, echoed from the request.
    - `limit` integer, required: The window size, echoed from the request.
    - `pages` DocumentPageImage[], required
      - `pageIndex` integer, required: 0-based page index, the same space field coordinates use.
      - `width` integer, required: The image's width in pixels.
      - `height` integer, required: The image's height in pixels.
      - `url` string, required: The authenticated path this image is fetched from. A path on this API, never a storage URL; the credential is presented again on each fetch.

## Other responses

- `400`: The request is malformed or the resource is in the wrong state for a synchronous check. Codes: `validation_error`, `invalid_body`, `invalid_parameter`, `invalid_idempotency_key`, `invalid_event_id`, `invalid_file`, `invalid_url`, `invalid_status`, `key_mismatch`, `no_signers`, `not_completed`, `envelope_exists`, `document_not_ready`, `upload_failed`.
- `401`: The credential is missing, malformed, unknown, expired, revoked, or past its rotation grace window. Code: `unauthorized`. Every authentication failure is deliberately indistinguishable.
- `403`: The credential is valid but may not do this. Codes: `insufficient_scope` (the route's scopes are not all held; `details` names `requiredScopes` and `missingScopes`), `forbidden` (the capability check on the resolved resource failed), `scope_escalation` (a grant wider than the caller's own was requested).
- `404`: The resource does not exist, was deleted, or belongs to another workspace. Code: `not_found`. The three cases are answered identically on purpose, so a 404 never confirms that an identifier exists elsewhere.
- `409`: The resource's state forbids this transition, or another request owns the work. Codes: `invalid_state`, `invalid_status`, `credential_state`, `limit_exceeded`, `envelope_missing`, `not_retryable`, `owner_unavailable`, `workspace_unavailable`, `detection_not_completed`, `document_in_use`, `version_conflict`, `document_processing`, `document_processing_failed`, `normalized_pdf_unavailable`, `pages_not_rendered`, `document_not_ready`, `idempotency_in_progress` (which also carries `Retry-After`), `payment_replayed` (a USDC payment signature presented twice), `payment_pending` (a USDC settlement whose outcome is not yet known).
- `429`: A limit was reached. Codes: `rate_limited` (the credential's per-bucket HTTP limit, or the per-workspace detection throttle), `workspace_limit_exceeded` (a workspace content or send limit; `details.limit` names it), `daily_budget_exceeded` (the workspace's daily detection budget). The four rate-limit headers are sent on this response and on no successful one, so a client cannot read its remaining budget without being refused. Retrying after `Retry-After` is always safe: a rate-limit refusal happens before the handler runs.
- `503`: A dependency the request needs is unreachable and nothing was changed. Codes: `queue_unavailable` (a background job could not be enqueued; retry the call), `billing_unavailable` (Stripe would not open a checkout session; nothing was charged, retry the call), `service_unavailable` (the rate-limit store is down, so the request was refused before running).

---

[API](https://skmtc.dev/inkseal/apis/inkseal-api.md) · [All operations](https://skmtc.dev/inkseal/apis/inkseal-api/llms.txt) · [OpenAPI document](https://skmtc.dev/inkseal/apis/inkseal-api/revisions/c440c981d578?raw)