> ## 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.
# Patch Configuration (typed changes)
> Applies a list of **typed intent changes** to a company's FMV1 configuration
and commits them atomically. This is the compact alternative to sending the
whole configuration body to **import** — you describe WHAT to change
(`add-field`, `create-option-set`, …), not the full config.
The server compiles the changes into the COMPLETE assembled configuration and
runs the SAME pipeline (and gates) as a full-body import: the whole-config
semantic validators, the breaking-change gate, and the atomic wholesale
write. It is **all-or-nothing** — if any change fails to compile or the
assembled config fails validation, **nothing is written**. Errors speak
intent (e.g. "add-field: `vehicleCount` already exists on Exposure"), never a
key path.
A list of ONE change is the normal single-verb case. Send several when they
are genuinely multi-part — e.g. a `create-option-set` plus the `add-field`
that uses it — committed together as one future config state; a field that
references an option set neither present nor created in the same list is
rejected with a message telling you to create it first or send both in one
call.
`baseRevision` is OPTIONAL: omit it to apply against the current
configuration (the common case), or supply the `revision` from a prior
**export** or **describe** to guard against concurrent edits (a stale value
returns `409`).
`dryRun` is OPTIONAL: set it `true` to run the IDENTICAL pipeline (compile,
whole-config validation, the breaking-change gate) but stop **before the
write** — nothing is committed. The response reports the verdict, the would-be
change summaries, and the CURRENT (pre-image) `revision` (marked `dryRun:
true`), which you pass as `baseRevision` on the follow-up commit. A failing dry
run returns the SAME error a commit would (and a commit fails identically,
writing nothing) — so a clean dry run is a reliable pre-commit check.
**Required permission:** `company.configuration:import`.
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/patch
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/patch:
post:
tags:
- FMV1 Configuration
summary: Patch Configuration (typed changes)
description: >
Applies a list of **typed intent changes** to a company's FMV1
configuration
and commits them atomically. This is the compact alternative to sending
the
whole configuration body to **import** — you describe WHAT to change
(`add-field`, `create-option-set`, …), not the full config.
The server compiles the changes into the COMPLETE assembled
configuration and
runs the SAME pipeline (and gates) as a full-body import: the
whole-config
semantic validators, the breaking-change gate, and the atomic wholesale
write. It is **all-or-nothing** — if any change fails to compile or the
assembled config fails validation, **nothing is written**. Errors speak
intent (e.g. "add-field: `vehicleCount` already exists on Exposure"),
never a
key path.
A list of ONE change is the normal single-verb case. Send several when
they
are genuinely multi-part — e.g. a `create-option-set` plus the
`add-field`
that uses it — committed together as one future config state; a field
that
references an option set neither present nor created in the same list is
rejected with a message telling you to create it first or send both in
one
call.
`baseRevision` is OPTIONAL: omit it to apply against the current
configuration (the common case), or supply the `revision` from a prior
**export** or **describe** to guard against concurrent edits (a stale
value
returns `409`).
`dryRun` is OPTIONAL: set it `true` to run the IDENTICAL pipeline
(compile,
whole-config validation, the breaking-change gate) but stop **before the
write** — nothing is committed. The response reports the verdict, the
would-be
change summaries, and the CURRENT (pre-image) `revision` (marked
`dryRun:
true`), which you pass as `baseRevision` on the follow-up commit. A
failing dry
run returns the SAME error a commit would (and a commit fails
identically,
writing nothing) — so a clean dry run is a reliable pre-commit check.
**Required permission:** `company.configuration:import`.
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: patchFmv1Configuration
parameters:
- $ref: '#/components/parameters/companyId'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationTypedPatchRequest'
examples:
addField:
summary: Add a single field (one-change list)
value:
changes:
- kind: add-field
entity: Exposure
referenceId: vehicleCount
type: Number
cardinality: Single
dryRun:
summary: Validate a batch without committing (dry run)
value:
dryRun: true
changes:
- kind: create-option-set
name: Territory
options:
- key: north
label: North
- kind: add-field
entity: Exposure
referenceId: territory
type: OptionSet
typeArgs: '{"optionSetName":"Territory"}'
cardinality: Single
optionSetAndField:
summary: Create an option set and a field that uses it (one call)
value:
changes:
- kind: create-option-set
name: Territory
options:
- key: north
label: North
- key: south
label: South
- kind: add-field
entity: Exposure
referenceId: territory
type: OptionSet
typeArgs: '{"optionSetName":"Territory"}'
cardinality: Single
cardAndPlacement:
summary: Create a card, add a field, and place it (one call)
value:
changes:
- kind: add-card
entity: Exposure
cardKey: vehicleDetails
name: Vehicle Details
cardType: input
pages:
- exposureCreate
- kind: add-field
entity: Exposure
referenceId: vehicleCount
type: Number
cardinality: Single
- kind: add-field-to-card
cardKey: vehicleDetails
fieldReferenceId: vehicleCount
inputModality: Number Box
responses:
'200':
description: Patch committed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationPatchResponse'
examples:
success:
summary: Successful patch (committed)
value:
revision: >-
0ad20bcb624b094062818cd340dea962b6efa653f9494fdc2a3a44ea40cb095a
changes:
- kind: add-field
summary: >-
Added field `vehicleCount` (Number, Single) to
Exposure.
dryRun:
summary: Dry run — validated, nothing written (pre-image revision)
value:
revision: >-
3f8a1c0d9b7e5a24c6f1e8d20b3a49c7d5e6f80a1b2c3d4e5f60718293a4b5e2
dryRun: true
changes:
- kind: create-option-set
summary: Created option set `Territory` with 1 option(s).
- kind: add-field
summary: >-
Added field `territory` (OptionSet, Single) to
Exposure.
'400':
description: >
Bad Request — either the change list failed structural validation
(an
unknown `kind` or a change missing required args), or a change could
not
be compiled (invalid field type, unknown entity, duplicate reference
id,
a field whose option set does not exist, …), or the assembled config
failed the whole-config semantic validators. In every case **nothing
is
written**.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
invalidChange:
summary: A change could not be compiled (intent-level error)
value:
error:
code: InvalidConfigChange
message: 'add-field: `vehicleCount` already exists on Exposure.'
userMessages:
- 'add-field: `vehicleCount` already exists on Exposure.'
validationFailure:
summary: Assembled config failed validation (no changes applied)
value:
error:
code: config-validation-failed
message: Config validation failed
userMessages:
- Event is missing the spec-required field "eventType".
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: >
Conflict — nothing is written in any case. One of: a supplied
`baseRevision` no longer matches the current config revision
(`fmv1-config-revision-mismatch`); the assembled config has breaking
changes that would invalidate stored data and the instance holds
entity data (`fmv1-config-breaking-changes`); a concurrent
configuration write for this company committed first
(`fmv1-config-concurrent-write`) — retry the request; or the
resulting
configuration would hold duplicate rows that cannot derive unique
runtime identifiers (`fmv1-config-not-projectable`) — remove the
duplicate rows, then retry.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
revisionMismatch:
summary: baseRevision is stale (no changes applied)
value:
error:
code: fmv1-config-revision-mismatch
message: >-
Config revision mismatch: baseRevision "abc123" does not
match current revision "0ad20b...".
'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:
ConfigurationTypedPatchRequest:
type: object
description: >
A **typed-change patch** — the compact way to edit a company's
configuration
without sending the whole body. It is a list of TYPED INTENT changes
(never
raw key-addressed ops): the server compiles them into the complete
assembled
configuration and commits it through the SAME pipeline (and gates) as a
full-body **import** — atomically, all-or-nothing.
A one-change list is the normal single-verb case; a list of several is
used
when changes are genuinely multi-part (e.g. an option set plus a field
that
uses it), committed together as one future config state.
required:
- changes
properties:
baseRevision:
type: string
minLength: 1
description: >
OPTIONAL optimistic-concurrency token. Omit to apply against the
current
configuration (the normal case). Supply the `revision` from a prior
**describe** read (or a prior `dryRun`) to guard against concurrent
edits:
if the configuration changed since, the request is rejected `409`
(`fmv1-config-revision-mismatch`) naming the current revision, and
nothing
is applied.
dryRun:
type: boolean
description: >
OPTIONAL. When `true`, the server runs the IDENTICAL pipeline
(compile →
whole-config validation → breaking-change gate) but stops **before
the
write** — nothing is committed. The response reports the verdict,
the
would-be change summaries, and the CURRENT (pre-image) `revision`
(marked
`dryRun: true`), which you pass as `baseRevision` on the follow-up
commit
for check-then-commit. A dry run that fails compile/validation/the
gate
returns the SAME error a commit would (a commit fails identically
and also
writes nothing). Omit (or `false`) to commit.
changes:
type: array
minItems: 1
description: The ordered list of typed changes to apply (1..N).
items:
oneOf:
- $ref: '#/components/schemas/ConfigChangeAddField'
- $ref: '#/components/schemas/ConfigChangeCreateCustomObject'
- $ref: '#/components/schemas/ConfigChangeCreateOptionSet'
- $ref: '#/components/schemas/ConfigChangeAddOptionSetOption'
- $ref: '#/components/schemas/ConfigChangeUpdateOptionSetOption'
- $ref: '#/components/schemas/ConfigChangeAddCard'
- $ref: '#/components/schemas/ConfigChangeAddFieldToCard'
- $ref: '#/components/schemas/ConfigChangeUpdateFieldOnCard'
- $ref: '#/components/schemas/ConfigChangeRemoveFieldFromCard'
- $ref: '#/components/schemas/ConfigChangeRelayoutCard'
discriminator:
propertyName: kind
example:
changes:
- kind: create-option-set
name: Territory
options:
- key: north
label: North
- key: south
label: South
- kind: add-field
entity: Exposure
referenceId: territory
type: OptionSet
typeArgs: '{"optionSetName":"Territory"}'
cardinality: Single
ConfigurationPatchResponse:
type: object
description: >
The result of a typed-change patch. On a commit, `revision` is the NEW
configuration revision and `dryRun` is absent. On a dry run, `dryRun` is
`true`,
nothing was written, and `revision` is the CURRENT (pre-image) revision
— pass it
as the follow-up commit's `baseRevision`.
required:
- revision
- changes
properties:
revision:
type: string
description: >
On a commit: the new configuration revision (the token to pass as
the next
patch's `baseRevision`). On a dry run: the current (pre-image)
revision,
since nothing was written.
changes:
type: array
description: >
One human-readable summary per change, in request order — applied
changes on
a commit, would-be changes on a dry run.
items:
type: object
required:
- kind
- summary
properties:
kind:
type: string
summary:
type: string
dryRun:
type: boolean
description: >
Present and `true` only when the request set `dryRun: true`: the
changes
were validated but NOT written.
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
ConfigChangeAddField:
type: object
description: >
Add a field to a top-level entity OR a custom object. Args map 1:1 onto
the
Fields-sheet columns. `entity` names either a top-level/system entity (→
a
top-level field) or a custom-object key (→ a sub-field on that object).
Type +
args validity is decided by the same rules the spreadsheet uses. A
custom-object
target cannot be an `EmbeddedExposure`; `Pointer` is custom-object-only.
required:
- kind
- entity
- referenceId
- type
- cardinality
properties:
kind:
type: string
enum:
- add-field
entity:
type: string
description: A top-level/system entity name, or a custom-object key.
referenceId:
type: string
description: camelCase identifier, unique within the entity/custom object.
type:
type: string
description: The field type (the spreadsheet **Type** cell).
typeArgs:
type: string
description: >-
The type-specific args as JSON (the **Type Args** cell); omit for
argless types.
cardinality:
type: string
enum:
- Single
- List
calculatedValue:
type: string
description: Optional JEXL expression for a read-only computed value.
description:
type: string
description: Optional human-readable description.
ConfigChangeCreateCustomObject:
type: object
description: Create a custom object (its type metadata plus an empty field list).
required:
- kind
- key
- name
- pluralName
properties:
kind:
type: string
enum:
- create-custom-object
key:
type: string
description: The custom object key (referenced by `Object`-typed fields).
name:
type: string
pluralName:
type: string
displayNameExpression:
type: string
description: Optional JEXL expression rendering an instance's display name.
ConfigChangeCreateOptionSet:
type: object
description: Create an option set with its initial options.
required:
- kind
- name
- options
properties:
kind:
type: string
enum:
- create-option-set
name:
type: string
options:
type: array
minItems: 1
items:
$ref: '#/components/schemas/ConfigOptionInput'
ConfigChangeAddOptionSetOption:
type: object
description: Append a new option to an existing option set.
required:
- kind
- optionSetName
- key
- label
properties:
kind:
type: string
enum:
- add-option-set-option
optionSetName:
type: string
key:
type: string
label:
type: string
groupLabel:
type: string
description: Optional group label (defaults to "").
ConfigChangeUpdateOptionSetOption:
type: object
description: Update the label and/or group label of an existing option-set option.
required:
- kind
- optionSetName
- key
properties:
kind:
type: string
enum:
- update-option-set-option
optionSetName:
type: string
key:
type: string
label:
type: string
description: New label (omit to leave unchanged).
groupLabel:
type: string
description: New group label (omit to leave unchanged).
ConfigChangeAddCard:
type: object
description: >
Create a card and (unless embedded) attach it to one or more pages.
`pages`
(page keys from the fixed, uncreatable page registry) and `embedded` are
MUTUALLY EXCLUSIVE, and exactly one is required — attaching to a page is
the
common case, so `embedded: true` is the explicit opt-in for a card that
has no
page rows and renders only when a card-list field references its
`cardKey`. The
card's `entity` + `cardType` must be compatible with each host page
(readonly
cards fit any page; a viewEdit card needs a viewEdit page; an input card
needs
an input page).
required:
- kind
- entity
- cardKey
- name
- cardType
properties:
kind:
type: string
enum:
- add-card
entity:
type: string
description: The entity the card is in context of (e.g. Exposure, Event, Quote).
cardKey:
type: string
description: camelCase identifier, unique across cards.
name:
type: string
description: The card's display title.
cardType:
type: string
enum:
- input
- readonly
- viewEdit
description: >-
create-vs-view is a PAGE distinction; the card type must be
compatible with its host pages.
pages:
type: array
items:
type: string
description: >-
Page keys to attach the card to. Mutually exclusive with `embedded`;
provide exactly one of the two.
embedded:
type: boolean
enum:
- true
description: >-
Set true (instead of `pages`) to create an embedded card with NO
page rows — rendered only via a card-list field's `cardKeys`.
columnCount:
type: integer
minimum: 1
description: The card's grid width. Defaults to 4 when omitted.
ConfigChangeAddFieldToCard:
type: object
description: >
Place an existing field on a card. The placement APPENDS a new row at
the
bottom of the card (positions are absolute 1-indexed grid coordinates;
the
server appends deterministically with no gap-filling — use
`relayout-card` to
arrange coordinates). The input modality must be valid for the placed
field's
type and cardinality; `requiredCondition` is the UI conditional-required
JEXL
(a placement concern, distinct from the field's spec nullability).
required:
- kind
- cardKey
- fieldReferenceId
- inputModality
properties:
kind:
type: string
enum:
- add-field-to-card
cardKey:
type: string
fieldReferenceId:
type: string
description: >-
The reference id of the field to place (must already exist on the
card's entity).
subFieldReferenceId:
type: string
description: >-
For a sub-field placement (custom-object sub-field, or a Single
embedded exposure's field).
inputModality:
type: string
description: >-
The input modality — must be compatible with the field's type +
cardinality.
displayFormat:
type: string
description: Optional display format.
label:
type: string
description: Optional display label; defaults to the field reference id.
requiredCondition:
type: string
description: Optional JEXL — UI conditional-required (placement level only).
autoSetCalculation:
type: string
description: Optional JEXL that auto-sets the field value.
autoSetTrigger:
type: string
description: Optional trigger controlling when the auto-set calculation runs.
autoSetConfirmation:
type: string
description: >-
Optional confirmation message shown before applying an auto-set
value.
autoSetScope:
type: string
description: >
Optional client evaluation scope of the auto-set rule: `page`
(default)
runs it while its card's page is active; `entity-global` runs it on
every
surface editing the entity for the whole session. Server-side rating
evaluates all configured quote-level rules regardless of scope.
enum:
- page
- entity-global
ConfigChangeUpdateFieldOnCard:
type: object
additionalProperties: false
description: >
Update the PLACEMENT-LEVEL presentation of a field already on a card.
This verb
touches ONLY placement columns — a field-DEFINITION change (`type`,
`cardinality`, nullability, …) is not expressible here
(additional properties are rejected). `requiredCondition` is UI
conditional-required (placement scope) and cannot touch spec
nullability.
Provide at least one placement field to update.
required:
- kind
- cardKey
- fieldReferenceId
properties:
kind:
type: string
enum:
- update-field-on-card
cardKey:
type: string
fieldReferenceId:
type: string
subFieldReferenceId:
type: string
inputModality:
type: string
displayFormat:
type: string
label:
type: string
requiredCondition:
type: string
autoSetCalculation:
type: string
autoSetTrigger:
type: string
autoSetConfirmation:
type: string
autoSetScope:
type: string
description: >
New client evaluation scope: `page` (default) runs the rule while
its
card's page is active; `entity-global` runs it on every surface
editing
the entity for the whole session. Server-side rating evaluates all
configured quote-level rules regardless of scope.
enum:
- page
- entity-global
ConfigChangeRemoveFieldFromCard:
type: object
description: >
Remove a field's placement from a card. The field DEFINITION lives on —
placementless fields are legal (smart-tag-only, export-only, or
intermediate
calculation fields). `subFieldReferenceId` targets a specific sub-field
placement.
required:
- kind
- cardKey
- fieldReferenceId
properties:
kind:
type: string
enum:
- remove-field-from-card
cardKey:
type: string
fieldReferenceId:
type: string
subFieldReferenceId:
type: string
ConfigChangeRelayoutCard:
type: object
description: >
TOTAL replacement of the positions of a card's placements. Every field
currently placed on the card must appear exactly once (you own the
coordinates), each entry must fit within the card's `columnCount`, and
no two
may overlap. It re-positions existing placements only — add or remove a
placement with `add-field-to-card` / `remove-field-from-card`.
required:
- kind
- cardKey
- layout
properties:
kind:
type: string
enum:
- relayout-card
cardKey:
type: string
layout:
type: array
minItems: 1
description: >-
One entry per currently-placed field, with its new 1-indexed grid
coordinates.
items:
type: object
required:
- fieldReferenceId
- row
- column
properties:
fieldReferenceId:
type: string
subFieldReferenceId:
type: string
row:
type: integer
minimum: 1
column:
type: integer
minimum: 1
rowSpan:
type: integer
minimum: 1
columnSpan:
type: integer
minimum: 1
ConfigOptionInput:
type: object
description: One option of an option set.
required:
- key
- label
properties:
key:
type: string
label:
type: string
groupLabel:
type: string
description: Optional group label (defaults to "").
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`.
````