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

# Get Policy Configuration

> Returns a JSON Schema describing the fields available for a Field Model V1
Policy. Policy is separately owned and has its own dedicated configuration
endpoint rather than riding the parametric
`entities/{entityType}/configuration` route (whose `entityType` covers only
the six CRUD entity types).

The `fields` schema is a standard JSON Schema (draft 2020-12) that can be
used directly with validation libraries like Ajv or Zod. The `required`
array lists fields that must be provided.

Calculated (JEXL-derived) and other server-managed fields — e.g.
`policyPremium` — are included in the schema (so they are discoverable and
overridable) but annotated with `readOnly: true` and `x-calculated: true`
so consumers can tell them apart from ordinary inputs. The annotation means
"server-managed", not "rejected on write".

**Required permission:** `company.policy:read`




## OpenAPI

````yaml /openapi/generated-external-api.yaml get /api/v1/companies/{companyId}/policies/configuration
openapi: 3.0.3
info:
  title: AI Insurance External API
  description: External API for AI Insurance platform
  version: 1.0.0
  contact:
    email: support@aiinsurance.io
servers:
  - url: https://go.aiinsurance.io
    description: Production
security:
  - ApiKeyAuth: []
paths:
  /api/v1/companies/{companyId}/policies/configuration:
    get:
      tags:
        - Field Model Policy Configuration
      summary: Get Policy Configuration
      description: >
        Returns a JSON Schema describing the fields available for a Field Model
        V1

        Policy. Policy is separately owned and has its own dedicated
        configuration

        endpoint rather than riding the parametric

        `entities/{entityType}/configuration` route (whose `entityType` covers
        only

        the six CRUD entity types).


        The `fields` schema is a standard JSON Schema (draft 2020-12) that can
        be

        used directly with validation libraries like Ajv or Zod. The `required`

        array lists fields that must be provided.


        Calculated (JEXL-derived) and other server-managed fields — e.g.

        `policyPremium` — are included in the schema (so they are discoverable
        and

        overridable) but annotated with `readOnly: true` and `x-calculated:
        true`

        so consumers can tell them apart from ordinary inputs. The annotation
        means

        "server-managed", not "rejected on write".


        **Required permission:** `company.policy:read`
      operationId: getPolicyV1Configuration
      parameters:
        - $ref: '#/components/parameters/companyId'
      responses:
        '200':
          description: Configuration for the policy's fields
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EntityV1ConfigurationResponse'
              examples:
                withCalculatedFields:
                  summary: Configuration with a calculated field
                  value:
                    fields:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      type: object
                      properties:
                        policyName:
                          type: string
                          title: policyName
                        policyPremium:
                          type: number
                          title: policyPremium
                          readOnly: true
                          x-calculated: true
                      required:
                        - policyName
                emptySchema:
                  summary: No fields configured
                  value:
                    fields:
                      $schema: https://json-schema.org/draft/2020-12/schema
                      type: object
                      properties: {}
                      required: []
        '401':
          $ref: '#/components/responses/Unauthorized'
        '403':
          $ref: '#/components/responses/Forbidden'
        '500':
          $ref: '#/components/responses/InternalServerError'
components:
  parameters:
    companyId:
      name: companyId
      in: path
      required: true
      schema:
        type: string
        format: uuid
      description: Company identifier
  schemas:
    EntityV1ConfigurationResponse:
      type: object
      description: >
        Configuration response for a Field Model V1 entity (Event, Exposure,
        Quote,

        Submission, Person, Organization, or read-only Policy). Returns a JSON
        Schema

        describing the fields available for creating or updating that entity.
        For

        entities that embed exposures (Quote),

        the embedded exposure schema is nested under the corresponding join
        field

        (e.g. `exposures`) rather than returned as a separate top-level key.
      required:
        - fields
      properties:
        fields:
          $ref: '#/components/schemas/FieldModelV1DataSchema'
    FieldModelV1DataSchema:
      type: object
      description: |
        Standard JSON Schema (draft 2020-12) describing field definitions
        for Field Model V1 entities. Includes a `required` array listing
        fields that must be provided.
      required:
        - $schema
        - type
        - properties
        - required
      properties:
        $schema:
          type: string
          enum:
            - https://json-schema.org/draft/2020-12/schema
          description: JSON Schema version identifier
        type:
          type: string
          enum:
            - object
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonSchemaProperty'
          description: Map of field keys to their JSON Schema definitions
        required:
          type: array
          items:
            type: string
          description: |
            Field keys that are unconditionally required. Only fields with
            `requiredCondition.expression === "true"` are listed here.
            Fields with conditional JEXL expressions are not included since
            they cannot be evaluated at configuration time.
    ErrorResponse:
      type: object
      description: Standard error response for all external API endpoints
      required:
        - error
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: Machine-readable error code
              example: VALIDATION_ERROR
            message:
              type: string
              description: Human-readable error message
              example: 'submissionId: Required field is missing'
            userMessages:
              type: array
              description: >-
                Clean, verbatim-displayable messages — one entry per failure,
                free of error-code tags, field paths, and internal noise.
                Suitable for showing to end users as-is.
              items:
                type: string
              example:
                - Exposures of type 'company' require an address
            details:
              type: array
              description: Additional details for validation errors (field-level errors)
              items:
                type: object
                properties:
                  field:
                    type: string
                    description: The field that caused the error
                    example: submissionId
                  message:
                    type: string
                    description: Description of the field error
                    example: Required field is missing
    JsonSchemaProperty:
      type: object
      description: |
        A JSON Schema property definition describing a single field.
        Uses standard JSON Schema (draft 2020-12) format for compatibility
        with validation libraries (Ajv, Zod) and OpenAPI tooling.
      required:
        - title
      properties:
        type:
          type: string
          enum:
            - string
            - number
            - integer
            - boolean
            - array
            - object
          description: JSON Schema data type
        title:
          type: string
          description: Human-readable field label
        readOnly:
          type: boolean
          description: >
            `true` for fields the caller should not supply. For a calculated or

            system-owned field it means "server-managed": the field is still
            returned

            in the configuration schema and the create/update write path still
            accepts

            a supplied value — the calculated expression itself decides whether
            that

            value is honored or recomputed. For a GENERATED field
            (`x-generated`) it is

            stronger: a value the platform did not originate is REJECTED with a

            `400 GeneratedFieldWrite` rather than overwritten. Read the
            companion `x-*`

            mark to tell the two apart. Absent for ordinary input fields.
        x-calculated:
          type: boolean
          description: >
            Explicit companion to `readOnly`: `true` iff the field has a

            `calculatedValue` expression. Standard JSON Schema tooling keys off

            `readOnly`; consumers wanting the precise "this is a calculated
            field"

            signal can key off this instead.
        x-computed-default:
          type: boolean
          description: >
            `true` iff the field is calculated by the self-referential

            keep-if-supplied idiom (`IS_PRESENT(<field>) ? <field> :
            <default>`), e.g.

            `quoteNumber`, `quoteStatus`. Such a field is calculated yet
            SETTABLE — the

            server fills a default only when the caller omits it, and a supplied
            value

            is kept — so it deliberately does NOT carry `readOnly`.
        x-system-owned:
          type: boolean
          description: >
            `true` iff the platform owns the value (the `referencing*`
            reverse-listing

            joins it resolves on read). Set alongside `readOnly`. System
            ownership wins

            over every other mark.
        x-generated:
          type: boolean
          description: >
            `true` iff the platform ORIGINATES the value at its trigger — a
            sequence

            number minted when a policy binds, or an identifier composed from
            other

            fields — and then freezes it on the bound policy. Set alongside
            `readOnly`,

            and the only mark whose `readOnly` means "rejected" rather than

            "overwritten": supplying a value the platform did not originate
            fails the

            request with a `400 GeneratedFieldWrite`. An exact unchanged echo is

            tolerated on an update, but omitting the field is always safe.
        x-optionSetName:
          type: string
          description: >
            On an Option Set field, the NAME of the option set the inline
            `oneOf` was

            built from — the natural key of the option-value catalogue

            (`POST /configuration/describe/option-set/{name}`). A consumer that
            slims or

            truncates the inline `oneOf` uses it to fetch the full set (with
            search /

            paging) by name.
        description:
          type: string
          description: Additional context about the field
        format:
          type: string
          description: >
            Semantic format hint for the field value. Common formats:

            - `date` - ISO 8601 date (YYYY-MM-DD)

            - `email` - Email address

            - `phone` - Phone number

            - `currency` - Monetary value

            - `percent` - Percentage value

            - `address` - Physical address

            - `entity:{target}` - Reference to another entity type (via a Join
            field, or a custom-object Pointer field)
        const:
          type: string
          description: |
            Exact value match. Used inside `oneOf` entries for Option Set values
            to represent the machine-readable key.
        enum:
          type: array
          items:
            oneOf:
              - type: string
              - type: number
          description: >
            Allowed values for legacy SelectField / RadioSelect /
            MultiSelectField /

            AsyncMultiSelectField fields. Each entry is a machine-readable
            option

            `value`. For MultiSelect-style fields the `enum` appears inside
            `items`

            (since the field stores an array of selected values); for
            single-select

            fields it appears at the top level. Pair with `enumLabels` to render

            human-readable labels.
        enumLabels:
          type: object
          additionalProperties:
            type: string
          description: >
            Optional companion to `enum`: a map from each enum `value`
            (stringified)

            to its human-readable label, so consumers can render labels without

            a second round-trip. Keys are always strings even if the underlying

            `enum` values are numbers — look up labels with `String(value)`.
        oneOf:
          type: array
          description: |
            Allowed values for Option Set fields (FMV1). Each entry provides a
            machine-readable key (`const`) and a human-readable label (`title`).
            Legacy MultiSelect/Select fields use `enum` + `enumLabels` instead.
          items:
            type: object
            required:
              - const
              - title
            properties:
              const:
                type: string
                description: Machine-readable key stored as the field value
              title:
                type: string
                description: Human-readable display label
        properties:
          type: object
          additionalProperties:
            $ref: '#/components/schemas/JsonSchemaProperty'
          description: |
            Nested property definitions for object-type fields (e.g. the object
            primitives Date, Currency, Address, and custom objects such as a
            tenant-defined NumberLimit). Also used inside `items` for legacy
            GroupField outputs to describe each row's subfield shape.
        required:
          type: array
          items:
            type: string
          description: >
            Required sub-fields within an object-type field. Only sub-fields
            with

            unconditional required conditions are listed.
        items:
          $ref: '#/components/schemas/JsonSchemaProperty'
          description: >
            Schema for array element items. Present for:

            - FMV1 "Object List" fields, producing `{ type: 'array', items: {
            type: 'object', properties: ... } }`

            - Legacy MultiSelectField / AsyncMultiSelectField, producing `{
            type: 'array', items: { type: 'string', enum: [...], enumLabels:
            {...} } }`

            - Legacy GroupField, producing `{ type: 'array', items: { type:
            'object', properties: {...subfields} } }`
  responses:
    Unauthorized:
      description: Unauthorized - Invalid or missing API key
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            missingApiKey:
              summary: Missing API key
              value:
                error:
                  code: AuthenticationError
                  message: API key authentication required
                  userMessages:
                    - API key authentication required
            invalidApiKey:
              summary: >-
                Invalid API key (e.g. unknown key, or a Bearer token used
                instead of an API key)
              value:
                error:
                  code: AuthenticationError
                  message: Invalid API key
                  userMessages:
                    - Invalid API key
    Forbidden:
      description: Forbidden - Insufficient permissions
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            insufficientPermissions:
              summary: Insufficient permissions
              value:
                error:
                  code: AuthorizationError
                  message: User is not authorized to perform the requested action
                  userMessages:
                    - User is not authorized to perform the requested action
            companyMismatch:
              summary: A valid API key naming another company in the URL
              value:
                error:
                  code: AuthorizationError
                  message: API key is not scoped to the requested company
                  userMessages:
                    - API key is not scoped to the requested company
    InternalServerError:
      description: Internal Server Error - Unexpected error occurred
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/ErrorResponse'
          examples:
            internalError:
              summary: Unexpected server error
              value:
                error:
                  code: UncaughtActionError
                  message: Uncaught error occurred in <actionName>
                  userMessages:
                    - An unexpected error occurred. Please try again later.
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: Authorization
      description: >-
        API key authentication. Send your raw API key as the `Authorization`
        header value with NO scheme prefix — `Authorization: YOUR-API-KEY`. Do
        NOT prefix it with `Bearer ` or `ApiKey `, and do not use an `X-API-Key`
        header; those are not accepted.

````