> ## 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.
# Seed Configuration
> Seeds the company's FMV1 configuration from code-defined starter content. The
server materializes the selected starter modules in-memory and runs them
through the same import pipeline: validate, parse, compare, and apply changes.
Seed builds the configuration from the framework's own code-defined starter
content. Use it to put a company into a usable FMV1 configuration state
without supplying a configuration body of your own.
Choose what gets seeded with **one** of two mutually-exclusive fields
(supplying both is a `400`):
- `starterSheet` — a single named variant that expands to a complete,
importable out-of-box config (base + exposure scheme + rater + every
default feature module).
- `modules` — an EXPLICIT starter-module selection (checkbox granularity,
#3428). The list is authoritative for every axis and feature: the server
unions it with the always-on base (`core` + `default`) but appends no
default feature modules. Discover the valid module ids and their axis
groups via `GET /configuration/seed/options`.
Supplying neither seeds the product default (`single-exposure-list`).
By default, seeding a company that **already** has a non-empty configuration
is refused with a `409` (`ConfigAlreadyExists`). Re-send with `replace: true`
to overwrite the existing configuration (#3428).
On success the response returns `success: true`. If the starter content fails
validation, **no changes are applied** and the endpoint returns a `400` with
an error describing the failure (it does not return `success: false`).
**Required permission:** `company.configuration:import`
This endpoint modifies the company's FMV1 configuration. Changes take effect immediately
and affect all users of the company. The seed runs a destructive smart import: configuration
rows present in the company but not in the starter content are removed.
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/seed
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/seed:
post:
tags:
- FMV1 Configuration
summary: Seed Configuration
description: >
Seeds the company's FMV1 configuration from code-defined starter
content. The
server materializes the selected starter modules in-memory and runs them
through the same import pipeline: validate, parse, compare, and apply
changes.
Seed builds the configuration from the framework's own code-defined
starter
content. Use it to put a company into a usable FMV1 configuration state
without supplying a configuration body of your own.
Choose what gets seeded with **one** of two mutually-exclusive fields
(supplying both is a `400`):
- `starterSheet` — a single named variant that expands to a complete,
importable out-of-box config (base + exposure scheme + rater + every
default feature module).
- `modules` — an EXPLICIT starter-module selection (checkbox
granularity,
#3428). The list is authoritative for every axis and feature: the server
unions it with the always-on base (`core` + `default`) but appends no
default feature modules. Discover the valid module ids and their axis
groups via `GET /configuration/seed/options`.
Supplying neither seeds the product default (`single-exposure-list`).
By default, seeding a company that **already** has a non-empty
configuration
is refused with a `409` (`ConfigAlreadyExists`). Re-send with `replace:
true`
to overwrite the existing configuration (#3428).
On success the response returns `success: true`. If the starter content
fails
validation, **no changes are applied** and the endpoint returns a `400`
with
an error describing the failure (it does not return `success: false`).
**Required permission:** `company.configuration:import`
This endpoint modifies the company's FMV1 configuration. Changes take
effect immediately
and affect all users of the company. The seed runs a destructive smart
import: configuration
rows present in the company but not in the starter content are removed.
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: seedFmv1Configuration
parameters:
- $ref: '#/components/parameters/companyId'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationSeedRequest'
examples:
default:
summary: Seed with the product-default starter content
value: {}
withVariant:
summary: Seed a specific starter sheet variant
value:
starterSheet: standalone-primary-insured
withModules:
summary: Seed an explicit starter-module selection (#3428)
value:
modules:
- standalone-primary-insured
- policy-number-auto
replaceReseed:
summary: Overwrite an already-configured company
value:
starterSheet: single-exposure-list
replace: true
responses:
'200':
description: Seed completed successfully
content:
application/json:
schema:
$ref: '#/components/schemas/ConfigurationImportResponse'
examples:
success:
summary: Successful seed
value:
success: true
message: Successfully imported configuration.
'400':
description: >-
Bad Request. Returned for a malformed selection — an unknown
`starterSheet` variant (`UnknownStarterSheet`), an unknown `modules`
id (`UnknownStarterModule`), supplying both `starterSheet` and
`modules`, or a colliding pick-one axis selection such as two raters
or two exposure schemes (`InvalidModuleSelection`) — or when the
resolved starter content fails config validation (no changes
applied).
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unknownStarterSheet:
summary: Unknown starter sheet variant
value:
error:
code: UnknownStarterSheet
message: >-
Unknown starter sheet "definitely-not-a-real-variant".
Available starter sheets: default-rater,
single-exposure-list, standalone-primary-insured.
userMessages:
- >-
Unknown starter sheet "definitely-not-a-real-variant".
Available starter sheets: default-rater,
single-exposure-list, standalone-primary-insured.
unknownStarterModule:
summary: Unknown module id in `modules`
value:
error:
code: UnknownStarterModule
message: >-
Unknown starter module(s): not-a-module. Valid modules:
core, default, default-rater, example-rater,
policy-number-manual, policy-number-auto,
single-exposure, standalone-primary-insured,
no-rater-billing.
userMessages:
- >-
Unknown starter module(s): not-a-module. Valid
modules: core, default, default-rater, example-rater,
policy-number-manual, policy-number-auto,
single-exposure, standalone-primary-insured,
no-rater-billing.
bothSelections:
summary: >-
Both `starterSheet` and `modules` supplied (mutually
exclusive)
value:
error:
code: InvalidModuleSelection
message: >-
Provide either `modules` or `starterSheet`, not both —
they are mutually exclusive ways to choose a starter
selection.
userMessages:
- >-
Provide either `modules` or `starterSheet`, not both —
they are mutually exclusive ways to choose a starter
selection.
collidingModules:
summary: Two modules from the same pick-one axis (e.g. two raters)
value:
error:
code: InvalidModuleSelection
message: >-
Duplicate starter row key "Quote::defaultRater" in slice
"fields" — declared by both module "default-rater" and
module "example-rater". The selected modules conflict;
choose a combination that does not collide.
userMessages:
- >-
Duplicate starter row key "Quote::defaultRater" in
slice "fields" — declared by both module
"default-rater" and module "example-rater". The
selected modules conflict; choose a combination that
does not collide.
validationFailure:
summary: Starter content failed validation (no changes applied)
value:
error:
code: config-validation-failed
message: Config validation failed
userMessages:
- Config validation failed
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'409':
description: >-
Conflict. The company already has a non-empty FMV1 configuration and
`replace` was not set. Re-send the request with `replace: true` to
overwrite the existing configuration.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
configAlreadyExists:
summary: >-
Company already configured — set `replace: true` to
overwrite
value:
error:
code: ConfigAlreadyExists
message: >-
This company already has a persisted FMV1 configuration;
seeding would replace it. Re-send this request with
`replace: true` to overwrite the existing configuration.
userMessages:
- >-
This company already has a persisted FMV1
configuration; seeding would replace it. Re-send this
request with `replace: true` to overwrite the existing
configuration.
'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:
ConfigurationSeedRequest:
type: object
description: >-
Request to seed FMV1 configuration from code-defined starter content.
The server materializes the starter content in-memory and runs it
through the import pipeline.
There are two mutually-exclusive ways to choose what gets seeded:
- `starterSheet` — a single named variant (the pre-#3428 contract). The
server
resolves it to a base + exposure-scheme (+ rater) selection AND appends every
default feature module, so the output is a complete, importable out-of-box
config.
- `modules` — an EXPLICIT starter-module selection (checkbox
granularity). The
list is authoritative for every axis and feature: the server unions it with
the always-on base (`core` + `default`) but appends NO default feature
modules.
Supplying **both** `starterSheet` and `modules` is a `400`
(`InvalidModuleSelection`). Supplying neither seeds the product default
(`single-exposure-list`: single exposure-list modeling with the default
rater).
properties:
starterSheet:
type: string
description: >-
A single named starter variant to seed. Mutually exclusive with
`modules`. If both `starterSheet` and `modules` are omitted, the
product default variant (`single-exposure-list`) is used. Discover
the valid names and their descriptions via `GET
/configuration/seed/options` (`options`). An unknown name fails with
a `400` (`UnknownStarterSheet`) listing the available variants.
enum:
- default-rater
- single-exposure-list
- standalone-primary-insured
modules:
type: array
description: >-
An EXPLICIT starter-module selection (checkbox granularity, #3428) —
the module ids to seed. Mutually exclusive with `starterSheet`. The
server unions the list with the always-on base (`core` + `default`)
and appends no default feature modules, so the caller names its own
exposure scheme, rater, and policy-number flavor. Discover the valid
ids (and their axis `group`) via `GET /configuration/seed/options`
(`modules`). An unknown id fails with a `400`
(`UnknownStarterModule`) listing the valid ids; a colliding pick-one
axis selection (e.g. two raters, or two exposure schemes) fails with
a `400` (`InvalidModuleSelection`).
items:
type: string
example:
- standalone-primary-insured
- policy-number-auto
replace:
type: boolean
description: >-
Overwrite an existing configuration (#3428). Seeding a company whose
config is already non-empty is refused with a `409`
(`ConfigAlreadyExists`) UNLESS this is `true`; a never-configured
company seeds without it. This guards config-only customization; the
downstream breaking-change gate still independently protects
companies that hold entity data.
default: false
ConfigurationImportResponse:
type: object
description: Result of importing FMV1 configuration
required:
- success
properties:
success:
type: boolean
description: Whether the import completed successfully
message:
type: string
description: Human-readable status message
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`.
````