> ## 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.
# Describe Configuration Entity (fields of one entity or custom object)
> Returns the **fields of ONE top-level entity or custom object**: each field's
`referenceId`, structured `typeInfo`, `cardinality`, and a `frameworkLocked`
marker. Deliberately minimal — the full field rows (placements, calculated /
auto-set expressions, descriptions) are a separate, richer read.
The `{entityOrObjectKey}` path segment is the **natural key** verbatim — a
top-level entity name (e.g. `Exposure`, `Quote`, `Policy`) or a custom-object
key (e.g. `Coverage`, `FullTermPricingInfo`) — never a configuration-row id.
It resolves either kind; an unknown key returns `404` naming the valid keys
(call the run-down `describe` endpoint to list them).
This is **not** the entity CRUD data-shape endpoint
(`GET /entities/{type}/configuration`, which returns a record's JSON Schema) —
this is the config-authoring view of one entity's fields. The request needs
**no body** — POST an empty object.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER**
or **CARRIER_ADMIN** role.
See [Authentication](/api-reference/authentication) for how to create API keys with specific roles.
## OpenAPI
````yaml /openapi/generated-external-api.yaml post /api/v1/companies/{companyId}/configuration/describe/{entityOrObjectKey}
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}/configuration/describe/{entityOrObjectKey}:
post:
tags:
- FMV1 Configuration
summary: Describe Configuration Entity (fields of one entity or custom object)
description: >
Returns the **fields of ONE top-level entity or custom object**: each
field's
`referenceId`, structured `typeInfo`, `cardinality`, and a
`frameworkLocked`
marker. Deliberately minimal — the full field rows (placements,
calculated /
auto-set expressions, descriptions) are a separate, richer read.
The `{entityOrObjectKey}` path segment is the **natural key** verbatim —
a
top-level entity name (e.g. `Exposure`, `Quote`, `Policy`) or a
custom-object
key (e.g. `Coverage`, `FullTermPricingInfo`) — never a configuration-row
id.
It resolves either kind; an unknown key returns `404` naming the valid
keys
(call the run-down `describe` endpoint to list them).
This is **not** the entity CRUD data-shape endpoint
(`GET /entities/{type}/configuration`, which returns a record's JSON
Schema) —
this is the config-authoring view of one entity's fields. The request
needs
**no body** — POST an empty object.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the
**FMV1_CONFIGURATION_MANAGER**
or **CARRIER_ADMIN** role.
See [Authentication](/api-reference/authentication) for how to create
API keys with specific roles.
operationId: describeFmv1ConfigurationEntity
parameters:
- $ref: '#/components/parameters/companyId'
- name: entityOrObjectKey
in: path
required: true
description: >
The natural key of the entity or custom object to describe — a
top-level
entity name (e.g. `Exposure`) or a custom-object key (e.g.
`Coverage`).
schema:
type: string
requestBody:
required: false
content:
application/json:
schema:
type: object
description: No input is required — an empty object (or no body) is accepted.
examples:
default:
summary: Describe an entity's fields
value: {}
responses:
'200':
description: The entity's or custom object's fields.
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationDescribeEntityResponse'
examples:
entity:
summary: A top-level entity (fields truncated)
value:
key: Exposure
kind: entity
fields:
- referenceId: exposureName
typeInfo:
kind: Text
cardinality: Single
frameworkLocked: true
- referenceId: exposureType
typeInfo:
kind: OptionSet
optionSetName: Exposure Types
cardinality: Single
frameworkLocked: true
customObject:
summary: A custom object
value:
key: Coverage
kind: customObject
fields:
- referenceId: name
typeInfo:
kind: Text
cardinality: Single
frameworkLocked: false
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: >
The key matched no top-level entity or custom object. Call the
run-down
`describe` endpoint to list the valid keys.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
'500':
$ref: '#/components/responses/InternalServerError'
security:
- BearerAuth: []
- ApiKeyAuth: []
components:
parameters:
companyId:
name: companyId
in: path
required: true
schema:
type: string
format: uuid
description: Company identifier
schemas:
ConfigurationDescribeEntityResponse:
type: object
description: >
The fields of ONE top-level entity or custom object: each field's
natural key,
structured type, cardinality, and a framework-locked marker.
Deliberately
minimal — the full field rows (placements, expressions, descriptions)
are a
separate, richer read.
required:
- key
- kind
- fields
properties:
key:
type: string
description: The resolved natural key (an entity name or a custom-object key).
kind:
type: string
enum:
- entity
- customObject
description: Whether the key resolved to a top-level entity or a custom object.
fields:
type: array
items:
type: object
required:
- referenceId
- typeInfo
- frameworkLocked
properties:
referenceId:
type: string
description: The field's natural key.
typeInfo:
type: object
description: >
The structured field type — the `kind` plus any type-specific
args
(e.g. an option-set name, an object key, a join descriptor).
properties:
kind:
type: string
description: >-
The field-type kind (e.g. `Text`, `OptionSet`, `Object`,
`Join`).
cardinality:
type: string
enum:
- Single
- List
description: |
Whether the field holds one value or many. Omitted only when a
custom-object sub-field carries no cardinality on the wire.
frameworkLocked:
type: boolean
description: >
`true` when the field is framework-required — renaming,
retyping, or
removing it breaks the platform (the import validator rejects
it).
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
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
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.
BearerAuth:
type: http
scheme: bearer
bearerFormat: JWT
description: >-
User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0
access token (audience = the app API audience) as `Authorization: Bearer
`. The request resolves to the user's identity and is authorized by
their Role on the `{companyId}` in the path — the same role-based
permissions the web app enforces. This is the path the MCP connector
uses to act on a user's behalf; endpoints that accept it list both
`BearerAuth` and `ApiKeyAuth`.
````