Served data

Served data is the platform’s model for records extracted from documents. The extraction pipeline reads your connected documents and projects what it finds into served records: effective-dated, traced to the document they came from, and cited field by field, so your application can show a user the page behind a value instead of asking them to trust it. Served records are read through read-only GET routes. Which record families exist is decided by the connection’s document profile: a fixed set, with the families and their fields fixed in code for each profile. This page describes the model every family follows.

Effective-dated versions

Served records are effective-dated. When a record changes, the platform closes the current version by setting its end date and writes a new version. The current version of a record is the one with no end date. Nothing is deleted: a version that is closed stays as history. Reads serve current versions only. With delivery, your warehouse keeps each version it received and closes it when a newer one arrives.

Provenance

A served record carries a provenance object that traces it to its source:

Field	Meaning
`source_blob_ref`	The document the record came from. Null when no source was recorded. Pass it unchanged to open the document (below).
`extraction_run_id`	The extraction that produced the record. Null when none was recorded.
`effective_from`	When this version became current.
`source_removed_at`	Present when every copy of the source document was removed from your library. See Why a field is null.

Credentials

Route	Organization API key (`nx_<environment>_...`)	Scoped key (`nxsk_v1_...`)
Served-record reads	Admitted	Needs `catalog:read`
Document listing and opening (`GET /api/v1/catalog/documents` and `GET /api/v1/catalog/documents/{source_blob_ref}`)	Admitted for the `live` environment key only. Any other environment’s key gets `403 scoped_key_required`.	Needs `catalog:documents:read`, which no key carries by default. Nexio adds it to a key on request.

See Authentication for both credential types.

Connection pinning

Every served-data read reads one active document library connection.

One active connection: connection_id is optional.
More than one: connection_id is required. Without it, the request fails with 400 catalog_connection_ambiguous.
A connection_id that is not an active connection of your organization fails with 404 not_found. A pinned client never silently reads zero rows.
No active connection: list routes return an empty page, and routes that read one record or one document return 404.

Pagination

Most list routes use page numbers. The document listing pages by cursor instead (limit and page.next_cursor).

Parameter	Default	Bounds
`page`	1	1 to 10,000,000. Outside that range: `400`.
`page_size`	25	Values above 100 are clamped to 100. Below 1: `400`.

A route’s compact view can allow larger pages with a different bound; its endpoint page states it. Each numbered page carries page, page_size, total_matched (rows matching your filters) and total_corpus (rows in the whole connection). The counts and the items are separate reads, so a change served during the request can leave them briefly out of step. Some list routes also return facets: the labels available to filter on across the connection, computed without your filters.

Freshness

Most served-data reads are cached on the server for up to 30 seconds per organization and connection, so a change is visible to readers within 30 seconds of being served. Some reads are computed on every request instead; each endpoint page says whether its read is cached. How quickly a change in your source library becomes served is covered in Sync health. Served-data GET requests share the data-reads budget of 30,000 requests per minute per organization with the /api/v1/records reads. See Limits.

Citations

A served record whose fields can be cited carries a citations object. It is how a user checks a value against the page it came from without leaving your product. This section is the one definition of citations; the endpoint pages link here. The object is keyed by the response field it cites, so you look it up by the field you are rendering. One passage that states two fields appears under both keys. An empty object means the record states nothing a citation could attach to; provenance.source_blob_ref can still name the document. Each endpoint page lists the keys its records can carry.

Field	Type	Meaning
`source_blob_ref`	string or null	The document. Pass it unchanged to open the document.
`field_path`	string or null	Where the value sits in the extraction.
`quote`	string or null	The evidence text stored for the value: the passage read from the document, or a label where no passage was stored. Some families store none, so it is always null there.
`page`	integer or null	1-based page number. Null at `document` grain.
`region`	object or null	`{x, y, w, h}`, normalized 0 to 1 with a top-left origin. Null unless `grain` is `region`.
`grain`	string	How precisely the passage was located. Always present.

Read `grain` before you render

`grain`	What is known	What to render
`region`	The passage was located in the page’s word geometry.	The page, with a box over the exact words.
`page`	The page, but not the rectangle.	The page, with the evidence text.
`document`	Only the document.	The document, with the evidence text when there is one.

Not every family reaches every grain. Handle all three.
A rectangle is never guessed. The platform computes it from the document’s own word positions; a model never supplies coordinates. A missing rectangle means the platform could not place the passage on a page, so never draw a document citation as if it were a region one.
Multiply the rectangle by the rendered page box, never by a point size, so the box covers the same words at any zoom.
Treat an unrecognized grain value as document.

Field removal for an acting person

When your server asserts X-Nexio-Acting-Principal (the person a request acts for), reads that apply field removal are narrowed to what that person’s seat may see. Field removal is applied route by route, and a route that applies none serves the same body with or without the header.

Read	What is removed for a restricted seat
Served records	On reads that apply field removal: the fields the seat’s policy denies, and the citations and document references of document classes the seat cannot open. Other extracted values stay. A read that applies none serves its values and citations to a restricted seat unchanged.
Document listing	Documents of classes the seat cannot open are not listed.
Opening a document	The request is refused with `403 document_class_not_open`, or with `403 document_unclassified` when no accepting pass has classified the document.

A seat whose policy cannot be read is served with every restricted field removed. How a seat’s policy follows from your own systems is on Access plane.

Why a field is null

Served data never fills a gap with a guess.

A value is null when the document does not state it. A zero placeholder is never served as a value.
An empty list means no document stating it was found, not a verified absence.
provenance.source_removed_at, when present, is when every copy of the source document was removed from your library. Removing a document closes the current records traced to it, so reads stop serving them, and an earlier version from another document can become current in their place. Records of a family the removal step does not close stay served, and some of those families carry source_removed_at. Closed records are kept as history. See Indexing and extraction.

Example: a served record with its citations

Every served record follows the same shape: the family’s own fields, a provenance object and a citations object keyed by the field each citation supports. The two fields rate_new and rate_renewal stand in for any family’s fields.

Served record

{
  "id": "9932cf92-4c53-460f-ab67-b538786663c6",
  "rate_new": 15,
  "rate_renewal": 12.5,
  "provenance": {
    "source_blob_ref": "harbor-supply/price_schedule/1ceeae2456181c3ea9c33b0adbf78fb332a98d361fa603ffb665da4f8ab538a1",
    "extraction_run_id": "a81d9ebb-90dd-45ee-a922-35fc9a1c461f",
    "effective_from": "2026-09-02T14:05:11Z"
  },
  "citations": {
    "rate_new": {
      "source_blob_ref": "harbor-supply/price_schedule/1ceeae2456181c3ea9c33b0adbf78fb332a98d361fa603ffb665da4f8ab538a1",
      "field_path": "price_schedule/lines/2/verbatim_quote",
      "quote": null,
      "page": 4,
      "region": { "x": 0.11, "y": 0.42, "w": 0.63, "h": 0.03 },
      "grain": "region"
    },
    "rate_renewal": {
      "source_blob_ref": "harbor-supply/price_schedule/1ceeae2456181c3ea9c33b0adbf78fb332a98d361fa603ffb665da4f8ab538a1",
      "field_path": "price_schedule/lines/2/verbatim_quote",
      "quote": null,
      "page": 4,
      "region": { "x": 0.11, "y": 0.42, "w": 0.63, "h": 0.03 },
      "grain": "region"
    }
  }
}

The two fields are stated in one passage, so both citation keys point to the same region on page 4.

Open the document behind a citation

Opening a document returns a short-lived URL for the file named by source_blob_ref. Request it from your server, then hand the URL to your viewer. Never send your API key to a browser. The URL is valid for 300 seconds; do not store it. The credentials the request needs are in Credentials, and the refusals are in Errors. page_count in the answer is null when the document’s text recorded no page signal, which is normal for Office files. Render by what your viewer shows rather than treating null as zero pages.

Errors

Every error uses the standard envelope. See Errors.

Status	Code	Cause	Fix
400	`invalid_request`	A parameter is out of bounds (page, page size, a two-letter state, a UUID, a length limit, an unknown `view`).	Correct the parameter named in the message.
400	`catalog_connection_ambiguous`	Your organization has more than one active connection.	Pass `connection_id`.
401	`unauthorized`	Missing or invalid key.	Send a valid key as `Authorization: Bearer`.
403	`insufficient_capability`	A scoped key lacks `catalog:read` (or `catalog:documents:read` on documents).	Ask Nexio to add the capability.
403	`scoped_key_required`	Documents route called with a non-live environment key.	Use the live key or a scoped key with `catalog:documents:read`.
403	`document_type_not_servable`	A call with no acting person asked for a document that is not classified as one of the classes open to calls without an acting person.	Show the citation as text, or send the acting person.
403	`document_class_not_open`	The acting person’s seat may not open this class of document.	Show the citation as text.
403	`document_unclassified`	An acting person asked for a document whose class must be confirmed by an accepting extraction pass, and no such pass has classified it.	Show the citation as text.
404	`not_found`	Unknown record key, unbacked document, inactive `connection_id`, or no active connection on a single-record read.	Check the key or `connection_id`.
429	`rate_limited`	Over the data-reads budget.	Wait for `Retry-After` seconds.
500	`presign_failed`	The object store could not sign a document URL.	Retry with backoff.
501	`object_store_unconfigured`	Documents route on a deployment with no object store.	Show the citation at its grain, as text.
503	`auth_unavailable`	Key verification is temporarily unavailable.	Retry with backoff.

Indexing and extraction

How documents become served records.

Review

What stands behind each served value.

Start here

Engines

Conversations

Connections and data

Records

Events and webhooks

Platform

Reference

Effective-dated versions

Provenance

Credentials

Connection pinning

Freshness

Citations

Read `grain` before you render

Field removal for an acting person

Why a field is null

Example: a served record with its citations

Open the document behind a citation

Errors

Indexing and extraction

Review

​Effective-dated versions

​Provenance

​Credentials

​Connection pinning

​Pagination

​Freshness

​Citations

​Read grain before you render

​Field removal for an acting person

​Why a field is null

​Example: a served record with its citations

​Open the document behind a citation

​Errors

Indexing and extraction

Review

Effective-dated versions

Provenance

Credentials

Connection pinning

Pagination

Freshness

Citations

Read `grain` before you render

Field removal for an acting person

Why a field is null

Example: a served record with its citations

Open the document behind a citation

Errors