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

# List record configurations

> Returns all record configurations in the account. Each configuration defines the schema (field names, types, validation rules) and UI hints for a category of records. Call this first to discover available record types before listing or querying records. Pass `ids` to batch-fetch specific configurations instead of all.



## OpenAPI

````yaml /api-reference/endpoint/records/openapi.json get /records/config
openapi: 3.1.0
info:
  title: Records API
  version: 1.1.0
  description: >-
    Record configurations (schemas, views, versions) and the records that
    conform to them. Record IDs are server-generated, config IDs are
    client-supplied (`^[a-zA-Z0-9_-]+$`). Configs and records are updated with
    PUT: a config update applies only the fields sent, a record update merges
    `data`. Editing a config schema does not retroactively re-validate existing
    records. Publish a config version to snapshot the stored config; list and
    read versions to see its history.
servers:
  - url: https://api.quiva.ai
    description: Production API server
security:
  - bearerAuth: []
  - apiKeyAuth: []
tags:
  - name: Record Configs
    description: >-
      Manage record configuration schemas. Each configuration defines the
      structure (fields, types, validation rules) that records must conform to.
  - name: Records
    description: >-
      Manage individual data records. Each record belongs to exactly one
      configuration and its data is validated against that configuration's
      schema.
  - name: Record Config Collections
    description: Groups of record configs.
  - name: Record Config Versions
    description: Published snapshots of a record config.
  - name: Record History
    description: The change history of a record.
  - name: Record Assessment
  - name: Strategy and Simulation
  - name: Record Metrics
paths:
  /records/config:
    get:
      tags:
        - Record Configs
      summary: List record configurations
      description: >-
        Returns all record configurations in the account. Each configuration
        defines the schema (field names, types, validation rules) and UI hints
        for a category of records. Call this first to discover available record
        types before listing or querying records. Pass `ids` to batch-fetch
        specific configurations instead of all.
      operationId: listRecordConfigs
      parameters:
        - name: collection_id
          in: query
          required: false
          schema:
            type: string
          description: >-
            Only configs in this collection. With summary, ~default lists the
            configs in no collection.
        - name: summary
          in: query
          required: false
          schema:
            type: string
            enum:
              - '1'
              - 'true'
          description: >-
            Answer one page of summary rows (id, name, description,
            collection_id, updated_at, has_source, resolution_error) by name
            from the index, with total_hits. No schema or views.
        - name: search
          in: query
          required: false
          schema:
            type: string
          description: >-
            With summary: each word must prefix a word of the name or
            description.
        - name: limit
          in: query
          required: false
          schema:
            type: integer
          description: Page size. With summary, default 25, at most 1000.
        - name: offset
          in: query
          required: false
          schema:
            type: integer
          description: 'With summary: rows to skip.'
        - name: cursor
          in: query
          required: false
          schema:
            type: string
          description: 'Without summary: the next_cursor of a truncated reply.'
      responses:
        '200':
          description: List of record configurations
          content:
            application/json:
              schema:
                allOf:
                  - $ref: '#/components/schemas/Response'
                  - properties:
                      body:
                        $ref: '#/components/schemas/RecordConfigList'
components:
  schemas:
    Response:
      type: object
      properties:
        status_code:
          type: integer
          description: HTTP status code echoed in the response body.
        body:
          type: object
          description: Response payload.
    RecordConfigList:
      type: object
      properties:
        results:
          type: array
          items:
            $ref: '#/components/schemas/RecordConfig'
        results_total:
          type: integer
          description: Total number of record configurations.
    RecordConfig:
      type: object
      required:
        - id
        - name
        - schema
      properties:
        id:
          type: string
          pattern: ^[a-zA-Z0-9_-]+$
          description: >-
            Unique identifier. Immutable after creation. Allowed characters:
            alphanumeric, underscore, hyphen.
        name:
          type: string
          description: Human-readable name for this configuration.
        description:
          type: string
          description: Optional longer description of what this configuration represents.
        label:
          type: string
          description: Optional short label, e.g. for UI badges or tabs.
        schema:
          $ref: '#/components/schemas/RecordSchema'
        views:
          $ref: '#/components/schemas/RecordViews'
        index_fields:
          type: array
          description: >-
            Payload fields lifted into the search index: the only ones a query,
            filter or metric can use. Replaced wholesale on update; an added or
            changed field, or a journey edit under a derived field, starts a
            background reindex.
          items:
            $ref: '#/components/schemas/RecordIndexField'
        created_at:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 timestamp set automatically on creation.
        updated_at:
          type: string
          format: date-time
          readOnly: true
          description: ISO 8601 timestamp updated automatically on every modification.
    RecordSchema:
      type: object
      description: >-
        A JSON Schema document describing the record structure. Always a
        top-level object. UI and display hints (`ui`, `display`) are embedded
        directly in each field definition.
      required:
        - type
        - properties
      properties:
        $schema:
          type: string
          description: >-
            Optional JSON Schema dialect URI (e.g.
            "https://json-schema.org/draft/2020-12/schema").
        type:
          type: string
          enum:
            - object
          description: >-
            Must be "object" — a record schema always describes a top-level
            object.
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RecordSchemaField'
          description: Top-level field definitions keyed by field name.
        required:
          type: array
          items:
            type: string
          uniqueItems: true
          description: Names of required top-level fields.
      additionalProperties: false
    RecordViews:
      type: object
      description: >-
        UI layout definitions for different rendering contexts. `forms`
        (multiple named forms) is the current model. `form` (singular) is the
        deprecated legacy single form — the server still accepts it, but the
        frontend migrates it to `forms: [{ id: "default", ... }]` on read and
        never writes it back.
      properties:
        forms:
          type: array
          description: Current model — multiple named forms per config.
          items:
            $ref: '#/components/schemas/RecordForm'
        form:
          $ref: '#/components/schemas/ViewGridNode'
          deprecated: true
          description: Deprecated legacy single form. Use `forms` instead.
        table:
          $ref: '#/components/schemas/ViewTableNode'
      additionalProperties: false
    RecordIndexField:
      type: object
      required:
        - field
      properties:
        field:
          type: string
          description: >-
            Dotted path into the record's data; also accepted as `key`. Indexed
            as `data_<path with dots as underscores>`.
        type:
          type: string
          enum:
            - keyword
            - text
            - text_sortable
            - number
            - numeric
            - date
            - datetime
          description: Empty means keyword.
        sortable:
          type: boolean
          description: Usable as sort_by.
        derive:
          $ref: '#/components/schemas/IndexDerive'
    RecordSchemaField:
      type: object
      description: >-
        Definition of a single field at any depth of the schema tree. Recurses
        via `properties` (objects) and `items` (arrays). Only `type` is
        required. Input config for a placed form field belongs on the view node
        (ViewFieldNode.inputType/props), NOT here; the legacy `ui` hint is a
        fallback only.
      required:
        - type
      properties:
        type:
          oneOf:
            - $ref: '#/components/schemas/RecordPropType'
            - type: array
              items:
                $ref: '#/components/schemas/RecordPropType'
              uniqueItems: true
          description: >-
            JSON type(s) for this field. Use an array to allow multiple types
            (e.g. ["string", "null"]).
        label:
          type: string
          description: Human-readable label shown in UI.
        title:
          type: string
          description: JSON Schema title.
        description:
          type: string
        minimum:
          type: number
        maximum:
          type: number
        exclusiveMinimum:
          type: number
        exclusiveMaximum:
          type: number
        minLength:
          type: integer
          minimum: 0
        maxLength:
          type: integer
          minimum: 0
        pattern:
          type: string
        format:
          type: string
        enum:
          type: array
          items: {}
        default: {}
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/RecordSchemaField'
          description: Nested field definitions for object-typed fields.
        required:
          type: array
          items:
            type: string
          uniqueItems: true
          description: >-
            Names of required nested fields. Only meaningful when `type` is
            "object".
        items:
          $ref: '#/components/schemas/RecordSchemaField'
          description: Item schema for array-typed fields.
        ui:
          $ref: '#/components/schemas/FieldUi'
          description: >-
            LEGACY UI fallback (not standard JSON Schema). Prefer node-level
            inputType/props on the view field node; this is only read for
            descendants that are not their own view node and is stripped from
            placed fields on save.
        display:
          $ref: '#/components/schemas/FieldDisplay'
      additionalProperties: false
    RecordForm:
      type: object
      description: >-
        One named form for a config: metadata plus a grid layout tree. `id` is
        unique within the config and appears in the app URL; the migrated legacy
        single form always gets id "default".
      required:
        - id
        - title
        - layout
      properties:
        id:
          type: string
          description: Unique within the config.
        title:
          type: string
        description:
          type: string
        layout:
          $ref: '#/components/schemas/ViewGridNode'
      additionalProperties: false
    ViewGridNode:
      type: object
      description: A grid layout container that arranges child nodes in CSS grid columns.
      required:
        - type
        - props
        - children
      properties:
        type:
          type: string
          enum:
            - grid
        props:
          $ref: '#/components/schemas/ViewGridProps'
        children:
          type: array
          items:
            $ref: '#/components/schemas/ViewNode'
        rules:
          type: array
          description: >-
            Conditional rules for this container. Only the `visible` property is
            honoured on a grid.
          items:
            $ref: '#/components/schemas/ElementRule'
      additionalProperties: false
    ViewTableNode:
      type: object
      description: A table view that lists columns to display and their order.
      required:
        - type
        - columns
      properties:
        type:
          type: string
          enum:
            - table
        columns:
          type: array
          items:
            $ref: '#/components/schemas/ViewTableColumn'
      additionalProperties: false
    IndexDerive:
      type: object
      description: >-
        Computes the field's value when the record is indexed instead of reading
        `data[field]`. The field must be a keyword, a single name, and not a
        schema property. A metric can filter on it and group by it; a run
        grouped by it is refused when it cannot be pushed down to the index.
      required:
        - kind
      properties:
        kind:
          type: string
          enum:
            - journey_round
            - member_progress
          description: >-
            `journey_round`: `turn` or `handed` for an open round of the journey
            the record runs (`views.forms[].journey`); absent once the round is
            ended, closed or at an unknown stage. `member_progress`: how far a
            member's form row has got, by the rule's other fields: `done`,
            `done_agreed`, `to_confirm`, `answered_sent`, `answered_unsent`,
            `sent` or `open`, on the member's one row only (see `anchor`).
        done_field:
          type: string
          description: >-
            `member_progress`: filled once the row is finished. Without it, the
            record's `completed` flag.
        answer_fields:
          type: array
          items:
            type: string
          description: >-
            `member_progress`: the dotted fields that count as answers. Wins
            over `answer_prefix`.
        answer_prefix:
          type: string
          description: >-
            `member_progress`: top-level keys starting with this are answers.
            Without either, every key but bookkeeping and `sent_field` is.
        form:
          type: string
          description: >-
            `member_progress`: a finished row with readiness gaps on this form
            (`state.readiness[form].missing`) is `to_confirm`.
        sent_field:
          type: string
          description: >-
            `member_progress`: filled when the row was sent. Without it, no row
            reads as sent.
        agreed_field:
          type: string
          description: >-
            `member_progress`: a finished row whose field holds a number is
            `done_agreed`.
        reset_on_send:
          type: array
          items:
            type: string
          description: >-
            `member_progress`: fields a send clears to `false`. `false` in one
            of them is no answer; `false` elsewhere is.
        anchor:
          type: boolean
          description: >-
            `member_progress`: the members' own anchor config, whose row is each
            member's anchor record (filed under a parent folder, at a bare
            member folder). Without it, only the row at the member's fixed id
            gets a value.
    RecordPropType:
      type: string
      description: Allowed JSON primitive/composite types for a schema field.
      enum:
        - string
        - number
        - integer
        - boolean
        - object
        - array
        - 'null'
    FieldUi:
      type: object
      description: >-
        LEGACY per-schema-field renderer hint. The current model places
        `inputType`/`props` on the view field node instead (see ViewFieldNode);
        the renderer reads node config first and only falls back to this
        schema-level `ui` for nested object-group members and array-item leaves
        that are not their own view node, and the frontend strips `ui` from
        placed fields on save. Prefer node-level config.
      properties:
        inputType:
          $ref: '#/components/schemas/InputType'
        props:
          $ref: '#/components/schemas/FieldProps'
      additionalProperties: false
    FieldDisplay:
      type: object
      description: Display configuration embedded in a schema field.
      properties:
        formatter:
          $ref: '#/components/schemas/FieldFormatter'
      additionalProperties: false
    ViewGridProps:
      type: object
      description: CSS Grid container properties.
      required:
        - gridTemplateColumns
      properties:
        gridTemplateColumns:
          type: string
          description: CSS grid-template-columns value (e.g. "1fr 1fr", "repeat(3, 1fr)").
        gap:
          type: number
          description: Gap between grid cells in pixels.
      additionalProperties: false
    ViewNode:
      description: >-
        A node in the view tree — a grid container, a field leaf, an array-field
        repeater, or a table.
      oneOf:
        - $ref: '#/components/schemas/ViewGridNode'
        - $ref: '#/components/schemas/ViewFieldNode'
        - $ref: '#/components/schemas/ViewArrayFieldNode'
        - $ref: '#/components/schemas/ViewTableNode'
    ElementRule:
      type: object
      description: >-
        A conditional rule attached to a view node. `logic` is a
        json-logic-engine expression evaluated against the live form value ({
        "var": "FieldPath" } reads another field; dotted paths allowed); at the
        form root it reads the whole record, inside an array-field item it reads
        that item. `logic` may also be a bare boolean for an unconditional
        state. The result sets `property` (booleans are coerced; `value` keeps
        the raw computed value).
      required:
        - id
        - property
        - logic
      properties:
        id:
          type: string
          description: Convention "<FieldPath>.<property>", e.g. "email.required".
        property:
          $ref: '#/components/schemas/RuleProperty'
        logic:
          description: A json-logic-engine expression object, or a boolean.
          oneOf:
            - type: object
            - type: boolean
        description:
          type: string
          description: >-
            One plain-English sentence describing the condition and outcome.
            Does not affect evaluation.
      additionalProperties: true
    ViewTableColumn:
      type: object
      description: A column descriptor in a table view.
      required:
        - field
        - order
      properties:
        field:
          type: string
          description: Schema field key this column displays.
        order:
          type: integer
          description: Display order of this column (ascending).
      additionalProperties: false
    InputType:
      type: string
      description: Input widget type for form rendering.
      enum:
        - array
        - checkbox
        - country
        - currency
        - date
        - date-range
        - dropdown
        - key-value
        - multi-country
        - multi-select
        - multi-toggle
        - number
        - phone
        - slider
        - tags
        - text
        - textarea
        - toggle
    FieldProps:
      type: object
      additionalProperties: true
      description: >-
        Display / configuration props forwarded to the input widget. `label`
        should always be set. Which props apply depends on the input type (e.g.
        `options`/`sort` for dropdown, `min`/`max`/`decimalPlace` for
        number/currency, `minDate`/`maxDate` for date,
        `includedCountries`/`showNativeName` for country, `maxItems` for
        multi-select).
      properties:
        label:
          type: string
          description: Display label shown above/beside the input. Always set this.
        placeholder:
          type: string
          description: Placeholder text shown inside the input when empty.
        helpText:
          type: object
          description: Optional help text rendered below the input.
          properties:
            markdown:
              type: string
              description: Help text content in Markdown format.
          additionalProperties: false
        options:
          type: array
          description: >-
            Choices for dropdown / multi-select / multi-toggle. Seed from the
            schema field's enum.
          items:
            type: object
            required:
              - text
              - value
            properties:
              text:
                type: string
                description: Human-readable label for the option.
              value:
                type: string
                description: Machine value submitted when this option is selected.
              note:
                type: string
                description: Optional extra description shown alongside the option.
            additionalProperties: false
        sort:
          type: boolean
          description: When `true`, options are sorted alphabetically before rendering.
        minDate:
          type: string
          format: date-time
          description: >-
            Earliest selectable date (ISO 8601). Applies to `date` /
            `date-range` inputs.
        maxDate:
          type: string
          format: date-time
          description: >-
            Latest selectable date (ISO 8601). Applies to `date` / `date-range`
            inputs.
        min:
          type: number
          description: >-
            Minimum allowed numeric value. Applies to `number` / `currency` /
            `slider` inputs.
        max:
          type: number
          description: >-
            Maximum allowed numeric value. Applies to `number` / `currency` /
            `slider` inputs.
        decimalPlace:
          type: integer
          description: >-
            Number of decimal places displayed. Applies to `number` / `currency`
            inputs.
        maxItems:
          type: integer
          description: Maximum number of selections. Applies to `multi-select`.
        includedCountries:
          type: array
          items:
            type: string
          description: >-
            Restrict the country list to these ISO codes (e.g. ["uk","ua"]).
            Applies to `country` / `multi-country`.
        showNativeName:
          type: boolean
          description: >-
            Show each country's native name. Applies to `country` /
            `multi-country`.
    FieldFormatter:
      type: object
      description: Formatter applied when displaying a field value.
      required:
        - type
      properties:
        type:
          $ref: '#/components/schemas/FormatterType'
        props:
          type: object
          additionalProperties: true
          description: Extra props forwarded to the formatter.
      additionalProperties: false
    ViewFieldNode:
      type: object
      description: >-
        A leaf node that binds an input to a schema field via a dotted path.
        Input config lives HERE on the node — `inputType`, `props`, and `rules`
        — not on the schema, so one schema can back several forms with different
        config. Omit `inputType` to accept the type default (string→text,
        number/integer→number, boolean→toggle, array→tags, object→key-value).
      required:
        - type
        - field
      properties:
        type:
          type: string
          enum:
            - field
        field:
          type: string
          description: >-
            Dotted path to the schema field (e.g. "name", "address.city"). The
            property key is `field` (a `ref` key is ignored by the engine).
        inputType:
          $ref: '#/components/schemas/InputType'
        props:
          $ref: '#/components/schemas/FieldProps'
        rules:
          type: array
          description: >-
            Conditional rules for this field. Field nodes support all five rule
            properties.
          items:
            $ref: '#/components/schemas/ElementRule'
      additionalProperties: false
      example:
        type: field
        field: policyNumber
        inputType: text
        props:
          label: Policy number
    ViewArrayFieldNode:
      type: object
      description: >-
        A repeating container (Repeater) bound to an array-of-object schema
        field. `children` is a builder-authored template of view nodes for one
        item; each child's `field` is ELEMENT-RELATIVE — resolved against the
        array field's `items.properties`, not the top-level schema (e.g. for
        array field "products", a child field "title" means "products[].title",
        not "products.title"). `props` (label, required, minItems, maxItems,
        collapsible, defaultCollapsed) is UI-only and not enforced by
        records-service; array size limits still come from the schema field's
        own JSON Schema minItems/maxItems if set there.
      required:
        - type
        - field
        - children
      properties:
        type:
          type: string
          enum:
            - array-field
        field:
          type: string
          description: Dotted path to an array-of-object schema field.
        props:
          type: object
          description: >-
            UI-only container config: label, required (at least one item),
            minItems, maxItems, collapsible, defaultCollapsed.
        children:
          type: array
          description: >-
            View nodes for one item, with element-relative `field` refs. Child
            field nodes carry their own node-level inputType/props/rules.
          items:
            $ref: '#/components/schemas/ViewNode'
        rules:
          type: array
          description: >-
            Reserved — array-field rules are NOT evaluated in v1. Put rules on
            the child field nodes instead.
          items:
            $ref: '#/components/schemas/ElementRule'
      additionalProperties: false
      example:
        type: array-field
        field: products
        props:
          label: Products
          itemLabel: Product
          required: true
          minItems: 1
        children:
          - type: field
            field: title
            inputType: text
            props:
              label: Title
          - type: field
            field: price
            inputType: currency
            props:
              label: Price
              min: 0
              decimalPlace: 2
    RuleProperty:
      type: string
      description: >-
        The element property a rule drives. Field nodes support all five; grid
        (container) nodes support `visible` only.
      enum:
        - visible
        - required
        - disabled
        - readonly
        - value
    FormatterType:
      type: string
      description: Display formatter applied when rendering a field value.
      enum:
        - text
        - number
        - currency
        - percent
        - date
        - datetime
        - time
        - boolean
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
    apiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.