> ## 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 (run-down)
> Returns the configuration **run-down** — a small orientation summary of the
company's FMV1 configuration: every top-level entity (with a one-line
description and field count), every custom object (with its name and
sub-field count), and every option set (with its option count), plus a
`revision` string identifying the stored configuration.
This is the first read for an automated config editor: call `describe` to
learn what exists, then the per-entity describe endpoint
(`describe/{entityOrObjectKey}`) to see one entity's or custom object's
fields. It does **not** list individual fields.
The run-down reads the whole configuration from the database (resolved from
the API key's tenant), so 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
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:
post:
tags:
- FMV1 Configuration
summary: Describe Configuration (run-down)
description: >
Returns the configuration **run-down** — a small orientation summary of
the
company's FMV1 configuration: every top-level entity (with a one-line
description and field count), every custom object (with its name and
sub-field count), and every option set (with its option count), plus a
`revision` string identifying the stored configuration.
This is the first read for an automated config editor: call `describe`
to
learn what exists, then the per-entity describe endpoint
(`describe/{entityOrObjectKey}`) to see one entity's or custom object's
fields. It does **not** list individual fields.
The run-down reads the whole configuration from the database (resolved
from
the API key's tenant), so 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: describeFmv1Configuration
parameters:
- $ref: '#/components/parameters/companyId'
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 the configuration
value: {}
responses:
'200':
description: The configuration run-down.
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationDescribeResponse'
examples:
success:
summary: Run-down (arrays truncated)
value:
revision: >-
3f8a1c0d9b7e5a24c6f1e8d20b3a49c7d5e6f80a1b2c3d4e5f60718293a4b5e2
entities:
- key: Exposure
description: The insurable thing a policy covers; the shared hub.
fieldCount: 13
- key: Quote
description: A priced offer that belongs to a submission.
fieldCount: 31
customObjects:
- key: Coverage
name: Coverage
fieldCount: 11
optionSets:
- name: Exposure Types
optionCount: 2
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'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:
ConfigurationDescribeResponse:
type: object
description: >
The configuration **run-down** — a small orientation summary of the
company's
FMV1 configuration. Lists every top-level entity, custom object, and
option set
with a count; it does not list individual fields (use the per-entity
describe
endpoint for those).
required:
- revision
- entities
- customObjects
- optionSets
properties:
revision:
type: string
description: >
Identifies the exact stored configuration this run-down was built
from (a
hash over the full config body; the same token the patch
optimistic-concurrency check uses as `baseRevision`).
entities:
type: array
description: The fixed top-level entities, each with its field count.
items:
type: object
required:
- key
- fieldCount
properties:
key:
type: string
description: The entity name (a natural key, e.g. `Exposure`).
fieldCount:
type: integer
description: The number of fields defined on the entity.
customObjects:
type: array
description: The company's custom objects, each with its sub-field count.
items:
type: object
required:
- key
- name
- fieldCount
properties:
key:
type: string
description: The custom-object key (a natural key, e.g. `Coverage`).
name:
type: string
description: The custom object's human display name.
fieldCount:
type: integer
description: The number of sub-fields on the custom object.
optionSets:
type: array
description: >-
The company's option sets, each with its option count and lock
state.
items:
type: object
required:
- name
- optionCount
- frameworkLocked
properties:
name:
type: string
description: The option set name (a natural key, and its label).
optionCount:
type: integer
description: >
The number of options — the option values themselves are not
inlined.
frameworkLocked:
type: boolean
description: >
`true` when the platform requires this exact set — its options
may
not be renamed, retyped, or removed (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`.
````