> ## 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 Configuration JSON Schema
> Returns the machine-readable **JSON Schema** (Draft 2020-12) for the FMV1
JSON configuration contract — the exact body that **import**, **validate**,
and **compare** accept and **export** returns.
The schema is **derived directly from the server's single source-of-truth
validation schema**, so it cannot drift from what those endpoints enforce.
Fetch it once to learn the shape, the per-slice structure, and the allowed
enum values **before** editing a configuration — it is the resource an
automated agent (e.g. an MCP server) stands on to author config edits.
The schema is a framework constant (identical for every company), so the
request needs **no body** — POST an empty object. The response is the literal
JSON Schema document, ready to hand to any JSON-Schema validator.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the **FMV1_CONFIGURATION_MANAGER** 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/schema
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/schema:
post:
tags:
- FMV1 Configuration
summary: Get Configuration JSON Schema
description: >
Returns the machine-readable **JSON Schema** (Draft 2020-12) for the
FMV1
JSON configuration contract — the exact body that **import**,
**validate**,
and **compare** accept and **export** returns.
The schema is **derived directly from the server's single
source-of-truth
validation schema**, so it cannot drift from what those endpoints
enforce.
Fetch it once to learn the shape, the per-slice structure, and the
allowed
enum values **before** editing a configuration — it is the resource an
automated agent (e.g. an MCP server) stands on to author config edits.
The schema is a framework constant (identical for every company), so the
request needs **no body** — POST an empty object. The response is the
literal
JSON Schema document, ready to hand to any JSON-Schema validator.
**Required permission:** `company.configuration:export`
This endpoint requires an API key created with the
**FMV1_CONFIGURATION_MANAGER** role.
See [Authentication](/api-reference/authentication) for how to create
API keys with specific roles.
operationId: getFmv1ConfigurationSchema
parameters:
- $ref: '#/components/parameters/companyId'
requestBody:
required: false
content:
application/json:
schema:
type: object
description: >-
No input is required; the schema is a framework constant. An
empty object is accepted.
examples:
default:
summary: Fetch the configuration JSON Schema
value: {}
responses:
'200':
description: The JSON Schema for the FMV1 configuration contract
content:
application/json:
schema:
type: object
description: >
A JSON Schema (Draft 2020-12) document describing the FMV1
configuration body. Treated as an opaque schema document — its
top-level keys are the JSON-Schema keywords (`$schema`,
`type`,
`properties`, …), not config fields.
examples:
success:
summary: The config JSON Schema (abridged)
value:
$schema: https://json-schema.org/draft/2020-12/schema
type: object
properties:
fields:
type: array
optionSets:
type: array
fieldLocations:
type: array
'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
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.
schemas:
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
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`.
````