Get Catalog Source Document
Mint a short-lived URL for the original bytes of one cited source document, so a user can check a value against the page it was read from.
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 inprovenance.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 oncatalog: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.
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 returns501 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
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
The document's content-addressed reference, exactly as it appears in provenance.source_blob_ref or citations.*.source_blob_ref.
500Query Parameters
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.
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.
The document's stored media type, which the presign also forces on the response.
Pages recorded by the document's text derivation. Null when the derivation recorded no page signal; a count is never fabricated.