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 for how to create API keys with specific roles.
Authorizations
User-principal OAuth 2.0 Bearer authentication. Send a user-scoped Auth0 access token (audience = the app API audience) as Authorization: Bearer <jwt>. 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.
Path Parameters
Company identifier
Body
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.
The ordered list of typed changes to apply (1..N).
1Add 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.
- Option 1
- Option 2
- Option 3
- Option 4
- Option 5
- Option 6
- Option 7
- Option 8
- Option 9
- Option 10
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.
1OPTIONAL. 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.
Response
Patch committed successfully
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.
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.
One human-readable summary per change, in request order — applied changes on a commit, would-be changes on a dry run.
Present and true only when the request set dryRun: true: the changes
were validated but NOT written.