The integration surface

Everything an integrator touches derives from one artefact. That is the whole design of this surface, and the rest of this page is what follows from it.

One contract, and everything downstream of it

The API contract is an OpenAPI 3.1 document. It is not documentation written after the code; it is the artefact the surface is defined by, and the clients, the tools and the tests are generated from it rather than maintained beside it.

That ordering matters more than it looks. A hand-written client drifts from the service it calls, and the drift is discovered by a caller in production rather than by a build. When the contract is the source, a change that would break a caller breaks generation first.

Four things come out of it, and each one exists because the contract does.

	What it is	What it is for
SDKs	Generated clients, typed against the contract	Removing the class of bug where a caller and a service disagree about a payload
CLI	The same operations from a terminal	Onboarding checks, support work, and looking at a tenant’s state without writing a client
Test fixtures	Worked examples, valid against the schemas	Making the contract checkable against itself in CI
MCP endpoints	The operations as typed tools for an AI agent	Letting an agent work through the authenticated surface rather than around it

The last one is the one that shapes the others, and it is covered on its own below.

The event stream

Coverage publishes a domain event on every state change that matters: a policy issued, endorsed, cancelled or lapsed, a claim moved, a receipt settled. Those events go onto Kafka, and the ledger consumes them at its own pace.

The event surface is described by an AsyncAPI 3.1 document, on the same principle the HTTP surface follows. An event that is not in the catalogue is not an event a consumer may depend on, and a producer cannot quietly change a payload shape that the catalogue declares.

Webhooks deliver those events to an endpoint you control. They are signed, so a receiver can verify the sender, and they are retried with backoff until acknowledged, so a receiver that was down does not lose the record of what happened while it was.

Webhooks sit downstream of the catalogue on purpose. Delivering an event that has not been described is how an integration ends up depending on a field nobody agreed to keep.

The agent surface

The platform exposes its operations to an AI agent as typed tools over the Model Context Protocol, and those tools are generated from the same contract the SDKs are.

This is the part of the surface that is designed differently from how most platforms would do it, so it is worth being precise about why.

An agent acting on an insurance platform is doing regulated work. It is issuing cover, moving a claim, releasing a payment. The common pattern is to give an agent a service account with broad rights and let it act on the operator’s behalf, which produces an audit trail that records the service account and loses the actor. That is unacceptable in a market where a regulator can ask who authorised a settlement.

So the agent surface carries no separate authorisation model. An agent holds the scopes of the identity it acts for and nothing more, its calls are subject to the same tenancy boundary as every other caller, and the audit log records the acting identity, the agent, and the tool call that produced the change. An agent cannot reach anything a person with the same credentials could not, and every action it takes is attributable.

The alternative, an agent that talks to a database or an internal service directly, gets a faster demonstration and an unauditable system. See Tenancy and scopes for the model this inherits.

Rate limits

Limits are agreed per tenant rather than published as one number, because the platform carries a ride-hailing app issuing thousands of policies an hour and a broker issuing forty, and one number would be wrong for both.

What is uniform is how a client learns its position. Responses carry the remaining allowance and the reset time, and a client that reads those headers backs off cleanly instead of discovering the limit by being refused. The headers are declared in Conventions along with the rest of the wire behaviour.

Environments

An integration is built against a test tenant, which is a full data plane with its own database, its own event stream and mock insurer systems behind the adapters. It is not a shared sandbox with a reset button, and that is deliberate: a shared sandbox teaches an integrator that state is disposable, which is the opposite of the lesson an insurance integration needs.

The mock insurers matter more than they sound. A real carrier’s API is slow, occasionally down, and sometimes wrong, and an integration that has only ever been tested against a healthy one has not been tested. The mocks reproduce the failure modes the adapters exist to absorb.

Test tenants are provisioned during onboarding, because a tenant carries scopes and a scope catalogue is not something the platform hands out to an unauthenticated caller.

What this surface will not do

It exposes no endpoint that returns the list of tenants, channels or products you do not already hold an identifier for. Enumeration is closed across the control plane, and Channel service sets out why: the platform carries competing distributors and competing carriers at once, and a list endpoint on shared reference data is a directory of who else is here.

It also carries no pricing or rating operation. Pricing is where insurers compete, and the platform issues what a carrier’s rates produce rather than producing them. That line is the same one the standard draws, and it is in Scope and design.