Skip to main content
GET
Get Catalog Source Document

What this is for

A citation names a document, a page, and a rectangle. This endpoint returns the bytes behind it, so a user can see the paper with the cited passage highlighted instead of taking an extracted number on trust. Pass the reference exactly as it appears in provenance.source_blob_ref or citations.*.source_blob_ref. It is a content-addressed path (carrier/class/sha), and the route accepts it with the slashes either literal or percent-encoded.

This grant is separate, and you do not have it yet

Reading a market’s numbers and reading a carrier’s contract are different acts, so this route is gated on catalog:documents:read, not on catalog:read. No key carries it by default. Granting it is an explicit act per key: a key that browses your catalog does not acquire document bytes as a side effect, and a legacy full-access key is denied here rather than admitted by the compatibility window that covers other routes. Two further gates apply after the capability, both server-side and both evaluated against one database snapshot:
  • Backing. The reference must back at least one current served row for your organization and connection. The servable set is therefore a subset of what you already read, and this route can never widen the set of documents your organization knows about. A reference that backs nothing you can see returns 404, which never distinguishes “does not exist” from “belongs to someone else”.
  • Document type. Only carrier paper is servable: agency agreements, commission schedules, appetite guides, name changes, and lock-ins. Anything else returns 403 document_type_not_servable. Production reports are excluded because they are your own book production rather than carrier paper, and documents nothing has classified are excluded because a route must not serve bytes whose sensitivity nothing has judged.
The type is read from the passes that accepted the document, not from every pass that looked at it. A misfiled document can leave a record under a pass that examined it and concluded it was something else; that record does not lend the document its type.

Fetch it server-side

source_url is a presigned URL scoped to that one object and valid for expires_in_seconds (five minutes). Bytes never pass through the platform API process. Proxy the URL to the browser or stream it through your own handler; do not ship your API credential to a client in order to fetch it, and do not persist the URL past its expiry. page_count is null when the document’s text derivation recorded no page signal, which is normal for office formats. Paginate by what your viewer renders rather than treating null as zero pages.

When there is no object store

A deployment without a durable object store returns 501 object_store_unconfigured rather than a broken URL. Render your citation at its stated grain with the quote as text and no page view.

Authorizations

Authorization
string
header
required

Send the credential as Authorization: Bearer <key>.

Scoped partner credentials use the exclusive nxsk_v1_... namespace. Each scoped key is bound at issuance to one organization, one canonical named environment, an explicit engine set, and a least-privilege capability set. A malformed, unknown, rotated, or revoked nxsk_ key fails closed and is never retried as a legacy key.

Capabilities used by this API are runs:write, runs:read, engines:read, catalog:read, webhooks:manage, runs:defensibility:read, runs:test, conversations:use, and conversations:export. Operation descriptions name the required capability. Grandfathered nx_live_... and nx_test_... keys retain their existing broad access during the compatibility window.

Path Parameters

source_blob_ref
string
required

The document's content-addressed reference, exactly as it appears in provenance.source_blob_ref or citations.*.source_blob_ref.

Maximum string length: 500

Query Parameters

connection_id
string<uuid>

Pin the browse to one active data connection. Optional when the org has a single active connection; required when it has more than one (an ambiguous request returns catalog_connection_ambiguous).

Response

A short-lived presigned URL for the document's original bytes.

source_url
string
required

A presigned URL scoped to this one object, valid for expires_in_seconds. Fetch it server-side and proxy to the browser; never ship the API credential to a client.

media_type
string
required

The document's stored media type, which the presign also forces on the response.

page_count
integer | null
required

Pages recorded by the document's text derivation. Null when the derivation recorded no page signal; a count is never fabricated.

expires_in_seconds
integer
required