> ## Documentation Index
> Fetch the complete documentation index at: https://docs.usenexio.com/llms.txt
> Use this file to discover all available pages before exploring further.

# List Catalog Commission Terms

> Page through the term-first record your product commission scalars are projected from, each term citing the passage it was read from.

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

```json theme={null}
"citations": {
  "rate": {
    "source_blob_ref": "acuity/commission_schedule/9f2c...",
    "field_path": "commission_schedule/lines/2/verbatim_quote",
    "quote": "New business commission is 15% of written premium",
    "page": 4,
    "region": { "x": 0.11, "y": 0.42, "w": 0.63, "h": 0.03 },
    "grain": "region"
  }
}
```

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:

| Grain      | What is known                               | What you can render                                    |
| ---------- | ------------------------------------------- | ------------------------------------------------------ |
| `region`   | The quote was located in real page geometry | The page, and a highlight box over the exact words     |
| `page`     | The page, but no rectangle                  | The page, scrolled to it, with the quote shown as text |
| `document` | Only the document                           | The document, and the quote as text                    |

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


## OpenAPI

````yaml GET /api/v1/catalog/terms
openapi: 3.1.0
info:
  title: Nexio API
  version: '1.0'
  description: |
    Nexio agentic infrastructure API. Configure engines for placement,
    entity analysis, and other patterns. Submit runs, poll for results,
    or subscribe to signed webhook callbacks.
  contact:
    email: support@usenexio.com
    url: https://docs.usenexio.com
servers:
  - url: https://api.usenexio.com
    description: Production
security:
  - BearerAuth: []
tags:
  - name: EngineManagement
    description: Create, configure, and manage inference engines.
  - name: Engines
    description: Engine-scoped endpoints for submitting runs and retrieving results.
  - name: Runs
    description: Retrieve and reconcile submitted runs.
  - name: Catalog
    description: >-
      Read current markets and products extracted for the authenticated
      organization.
  - name: Environments
    description: Isolated tenancy scopes under your org (one live plus non-live sandboxes).
  - name: Webhooks
    description: Manage webhook endpoints for push-based delivery of terminal run events.
  - name: Converse
    description: The raw stateless conversational model turn (caller-owned state).
  - name: Conversations
    description: >-
      Conversation instances (orchestrators over engines) and their managed
      conversations, turns, annotations, evals, and exports.
paths:
  /api/v1/catalog/terms:
    get:
      tags:
        - Catalog
      summary: List Catalog Commission Terms
      description: |
        Returns one page of current commission terms for the authenticated
        organization's active data connection. Scoped credentials require
        `catalog:read`.

        Terms are the term-first record the product commission scalars are
        projected from: one row per term of a schedule version (base rate side,
        volume tier, rate modifier, conditional override, non-numeric
        authorization, contingent bonus, profit-share grid cell, factor, gate,
        cap, lifecycle event). `rate` is the figure AS STATED and
        `rate_is_percent` carries its unit; the product scalars normalize it.

        Each term carries a `citations` object keyed by the payload field it
        cites. That is where citation is field-grained: read `grain` before
        rendering, because a `document`-grain citation must never render as
        though it were a rectangle.

        This response carries no `facets`: the term corpus offers no facet
        vocabulary, and an empty facet list would read as an empty corpus.
      operationId: listCatalogTerms
      parameters:
        - $ref: '#/components/parameters/CatalogConnectionID'
        - name: market_entity_key
          in: query
          required: false
          description: >-
            Restrict to one market's terms (exact match on the served market
            key).
          schema:
            type: string
            maxLength: 500
        - $ref: '#/components/parameters/CatalogLine'
        - name: term_family
          in: query
          required: false
          description: >-
            Restrict to one term family. The families are projected and
            superseded independently, so this selects a different record set,
            not a display subset.
          schema:
            type: string
            enum:
              - commission
              - profit_share
        - $ref: '#/components/parameters/CatalogPage'
        - $ref: '#/components/parameters/CatalogPageSize'
      responses:
        '200':
          description: One page of current commission terms with their citations.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CatalogTermListResponse'
        '400':
          $ref: '#/components/responses/BadRequest'
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/RateLimited'
        '503':
          $ref: '#/components/responses/AuthUnavailable'
components:
  parameters:
    CatalogConnectionID:
      name: connection_id
      in: query
      description: >
        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`).
      schema:
        type: string
        format: uuid
    CatalogLine:
      name: line
      in: query
      description: >-
        Line-of-business filter matched against the product's `line` or
        `line_code`.
      schema:
        type: string
    CatalogPage:
      name: page
      in: query
      description: 1-based page number. Defaults to 1.
      schema:
        type: integer
        minimum: 1
        default: 1
    CatalogPageSize:
      name: page_size
      in: query
      description: Rows per page, clamped to 100. Defaults to 25.
      schema:
        type: integer
        minimum: 1
        maximum: 100
        default: 25
  schemas:
    CatalogTermListResponse:
      type: object
      additionalProperties: false
      required:
        - items
        - page
        - page_size
        - total_matched
        - total_corpus
      properties:
        items:
          type: array
          items:
            $ref: '#/components/schemas/CatalogTerm'
        page:
          type: integer
        page_size:
          type: integer
        total_matched:
          type: integer
        total_corpus:
          type: integer
    CatalogTerm:
      type: object
      additionalProperties: false
      required:
        - id
        - entity_key
        - market_entity_key
        - term_family
        - term_kind
        - business_basis
        - line
        - line_code
        - line_class
        - raw_label
        - states
        - program_parent
        - policy_condition
        - band_1
        - band_2
        - rate
        - rate_is_percent
        - rate_non_numeric
        - modifier_delta
        - conditions
        - effective_year
        - corrected
        - confidence
        - provenance
        - citations
      properties:
        id:
          type: string
        entity_key:
          type: string
          description: Stable term identity within the connection.
        market_entity_key:
          type: string
        term_family:
          type: string
          enum:
            - commission
            - profit_share
        term_kind:
          type: string
          description: >-
            The shape of the term (base rate side, tier, modifier, override,
            gate, cap, and so on), served verbatim.
        business_basis:
          type: string
          description: '`new`, `renewal`, `all`, or empty when the document states none.'
        line:
          type: string
        line_code:
          type: string
          nullable: true
        line_class:
          type: string
        raw_label:
          type: string
          description: The row or table label as printed.
        states:
          type: array
          items:
            type: string
        program_parent:
          type: string
        policy_condition:
          type: string
          description: The rate-selecting predicate as printed.
        band_1:
          $ref: '#/components/schemas/CatalogTermBand'
        band_2:
          $ref: '#/components/schemas/CatalogTermBand'
        rate:
          type: number
          format: double
          nullable: true
          description: The figure AS STATED; `rate_is_percent` carries its unit.
        rate_is_percent:
          type: boolean
        rate_non_numeric:
          type: string
          nullable: true
          description: The authorization as printed when the document states no number.
        modifier_delta:
          type: number
          format: double
          nullable: true
        conditions:
          type: string
        effective_year:
          type: integer
          nullable: true
        corrected:
          type: boolean
          description: True when a recorded correction applies to this document.
        confidence:
          type: number
          format: double
          nullable: true
        provenance:
          $ref: '#/components/schemas/CatalogProvenance'
        citations:
          allOf:
            - $ref: '#/components/schemas/CatalogCitations'
          description: >-
            This term's citation, keyed under every field the row actually
            states a value in: `rate`, `rate_non_numeric`, `modifier_delta`, or,
            for a term that states no figure, `conditions` or `raw_label`. A
            term has one evidence quote and it supports every value that term
            states, so the same citation legitimately appears under more than
            one key. Look it up by the field you are rendering; an empty object
            means the row states nothing a citation could attach to, and
            `provenance` still names the document.
    Error:
      type: object
      required:
        - code
        - message
      properties:
        code:
          type: string
          description: |
            Stable snake_case error identifier. Safe to match programmatically.

            Known codes: `invalid_request`, `invalid_input`, `unauthorized`,
            `auth_unavailable`, `rate_limited`, `missing_run_id`,
            `invalid_run_id`, `run_not_found`, `invalid_offerings`,
            `missing_input`, `queue_unreachable`,
            `engine_not_found`, `engine_slug_conflict`, `engine_archived`,
            `instance_not_found`, `instance_slug_conflict`, `instance_archived`,
            `instance_follows_canonical`, `instance_not_published`,
            `invalid_engine_type`, `validation_error`,
            `webhook_not_found`, `webhook_limit_exceeded`, `invalid_url`,
            `invalid_events`, `invalid_description`, `invalid_auth_token`,
            `missing_endpoint_id`, `invalid_endpoint_id`, `missing_delivery_id`,
            `invalid_delivery_id`, `delivery_not_found`,
            `delivery_not_resendable`, `insufficient_capability`,
            `engine_version_required`, `engine_version_exact_required`,
            `engine_version_not_found`, `engine_version_invalid_format`,
            `engine_version_draft_requires_sandbox_key`,
            `engine_version_none_released`, `test_scenario_sandbox_only`,
            `test_scenario_forbidden`, `test_scenario_exact_version_required`,
            `test_scenario_version_not_supported`, `invalid_test_scenario`,
            `request_bound_exceeded`, and `run_cap_exceeded`.
        message:
          type: string
          description: Human-readable error message. May change between versions.
        details:
          description: |
            Optional request-specific details. Request-bound failures use the
            `RequestBoundDetails` object. Validation failures may use an array
            of field issues or another documented object.
    CatalogTermBand:
      type: object
      additionalProperties: false
      required:
        - kind
        - min
        - max
        - unit
        - raw_label
      description: >-
        One band axis of a term as printed: the tier or window the rate applies
        within. Null bounds mean the document stated none (open-ended or
        unbanded), which is not the same as a zero bound.
      properties:
        kind:
          type: string
        min:
          type: number
          format: double
          nullable: true
        max:
          type: number
          format: double
          nullable: true
        unit:
          type: string
        raw_label:
          type: string
    CatalogProvenance:
      type: object
      additionalProperties: false
      required:
        - source_blob_ref
        - extraction_run_id
        - effective_from
      properties:
        source_blob_ref:
          type: string
          nullable: true
          description: Source document lineage reference. Null when no source was recorded.
        extraction_run_id:
          type: string
          format: uuid
          nullable: true
          description: The extraction run that produced this row. Null when unrecorded.
        effective_from:
          type: string
          format: date-time
          description: When this served head became current.
    CatalogCitations:
      type: object
      description: >-
        Citations keyed by the payload field they cite. Only fields that carry a
        quote or an anchor appear, so a missing key means "no citation beyond
        the document", never "no source".
      additionalProperties:
        $ref: '#/components/schemas/CatalogCitation'
    CatalogCitation:
      type: object
      additionalProperties: false
      required:
        - source_blob_ref
        - field_path
        - quote
        - page
        - region
        - grain
      description: >-
        One payload field's citation. The platform derives geometry from the
        document's own bytes rather than asking a model for it, so a region that
        is present located in real page geometry and a region that is absent
        means no match was found. There is no third state in which a rectangle
        was guessed.
      properties:
        source_blob_ref:
          type: string
          nullable: true
          description: The cited document. Null when no source was recorded.
        field_path:
          type: string
          nullable: true
          description: >-
            The canon address the quote was read from, in the platform's
            `<extractor_kind>/<token>...` field-path grammar. Null when the
            row's anchor is a fallback rather than the canon quote; the pointer
            is never fabricated.
        quote:
          type: string
          nullable: true
          description: >-
            The verbatim passage the extractor asserted and the platform
            verified against the document text. Present at every grain, so a
            consumer can always show the passage even when it cannot point at
            it.
        page:
          type: integer
          nullable: true
          description: >-
            1-based page. At `region` grain this is the locator's TRUE page (the
            page the rectangle is on), not the model's claim. Null at `document`
            grain.
        region:
          allOf:
            - $ref: '#/components/schemas/CatalogCitationRegion'
          nullable: true
          description: Null at `page` and `document` grain.
        grain:
          type: string
          enum:
            - region
            - page
            - document
          description: >-
            How precisely the citation locates the value: `region` (a rectangle
            on a page), `page` (the page is known, the rectangle is not), or
            `document` (only the document is known). Required precisely so a
            consumer cannot render a document-level citation as though it were a
            rectangle. Read as a widening union: treat an unrecognized value as
            `document`, never as a region.
    CatalogCitationRegion:
      type: object
      additionalProperties: false
      required:
        - x
        - 'y'
        - w
        - h
      description: >-
        A normalized rectangle on one page: 0-1, 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.
      properties:
        x:
          type: number
          format: double
        'y':
          type: number
          format: double
        w:
          type: number
          format: double
        h:
          type: number
          format: double
  responses:
    BadRequest:
      description: Invalid request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          examples:
            invalidRequest:
              summary: Malformed JSON
              value:
                code: invalid_request
                message: Request body is not valid JSON
            invalidInput:
              summary: Input validation failed
              value:
                code: invalid_input
                message: Input failed validation
                details:
                  - field: input.address.state
                    message: address.state is required for placement runs.
            invalidOfferings:
              summary: Placement run missing offerings
              value:
                code: invalid_offerings
                message: Inline offerings failed validation
                details:
                  - field: offerings
                    message: >-
                      Offerings are required for placement runs. Pass provider
                      offerings in the top-level offerings array.
    Unauthorized:
      description: Missing or invalid API key.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: unauthorized
            message: Missing or invalid API key
    Forbidden:
      description: Scoped key does not have the capability required by this operation.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: insufficient_capability
            message: API key does not have permission for this action
    NotFound:
      description: The requested resource does not exist in the authenticated org.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: not_found
            message: Market not found
    RateLimited:
      description: Rate limit exceeded. Retry after the window resets.
      headers:
        Retry-After:
          description: Seconds until the rate limit window resets.
          schema:
            type: integer
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: rate_limited
            message: Rate limit exceeded
    AuthUnavailable:
      description: API key authentication is temporarily unavailable.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
          example:
            code: auth_unavailable
            message: API key authentication is temporarily unavailable
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: |
        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.

````