Skip to main content
GET
List Catalog Commission Terms

Terms, not scalars

A product carries one commission figure per side. A schedule states much more than that: a base rate per line, volume tiers, rate modifiers, conditional overrides, non-numeric authorizations, contingent bonuses, and profit-share grid cells, factors, gates and caps. Terms are that record, one row per stated term of a schedule version, and the product scalars on GET /api/v1/catalog/products are a derived projection of them. rate is the figure as stated, and rate_is_percent carries its unit. A term that states no figure carries rate: null and states its content somewhere else: rate_non_numeric for a printed authorization, modifier_delta for a plus-or-minus adjustment, conditions for a prose gate. Read the field that is populated rather than assuming rate. term_family selects a different record set, not a display subset. Commission terms and profit-share terms are projected and superseded independently, so filtering to one is a real question about which record you want.

Citations

Every term carries a citations object. It is how a user checks a number against the paper it came from without leaving your product.
The citation is keyed by the payload field it cites, and it appears under every field the term actually states a value in. One term has one evidence quote and that quote supports every value the term states, so the same citation legitimately appears under both rate and modifier_delta on a term that states both. Look it up by the field you are rendering. An empty object means the term states nothing a citation could attach to, and provenance still names the document.

Read grain before you draw anything

grain is required on every citation and it is the field to branch on: region is null at page and document grain; page is null at document grain. Treat an unrecognized grain as document. A document-grain citation must not render like a region-grain one. The platform derives geometry from the document’s own bytes rather than asking a model for it, so a rectangle that is present located in real page geometry and a rectangle that is absent means no match was found. There is no third state in which a box was guessed, and a surface that renders the two identically throws away that distinction. The region rectangle is normalized 0-1 with a top-left origin. Multiply it by the rendered page box, never by a point size, so a viewer at any zoom draws the same box over the same words.

Pagination

Page-numbered, like the rest of the catalog browse family: page and page_size, with total_matched and total_corpus alongside. All three come from one database snapshot, so the counts always describe the same catalog as the items. This response carries no facets. The term corpus offers no facet vocabulary, and an empty facet list would read as an empty corpus.

Connection pinning

Reads pin one data connection. connection_id is optional when your organization has a single active connection and required when it has more than one; an ambiguous request returns catalog_connection_ambiguous. All reads are current heads only.

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.

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).

market_entity_key
string

Restrict to one market's terms (exact match on the served market key).

Maximum string length: 500
line
string

Line-of-business filter matched against the product's line or line_code.

term_family
enum<string>

Restrict to one term family. The families are projected and superseded independently, so this selects a different record set, not a display subset.

Available options:
commission,
profit_share
page
integer
default:1

1-based page number. Defaults to 1.

Required range: x >= 1
page_size
integer
default:25

Rows per page, clamped to 100. Defaults to 25.

Required range: 1 <= x <= 100

Response

One page of current commission terms with their citations.

items
object[]
required
page
integer
required
page_size
integer
required
total_matched
integer
required
total_corpus
integer
required