Contracts · 8 min
How teams maintain API contracts without a manual specRead →API Contracts
Breaking changes should be a decision
A contract says which endpoints an audience sees, which fields they get, and what happens when that promise changes. Elva watches every commit against it and stops the surprise before it ships.
Per-audience scopeField-level controlBlock-publish policiesOnly in Elva
payouts-partnercontract v1.42 breaking
audience partnerendpoints 12consumers 4policy block
commit a91f2c · 6 filesno contract impact
POST /payouts addedadditive · in scope
GET /payouts/{id} · field "fee" now nullablewarn · partners notified
DELETE /builds/{id} · "buildLog" removedbreaking · 2 consumers
GET /billing/plans · scope tightenedbreaking · 1 partner build
docs and SDK regeneratedpending approval
publish blocked · 4 stakeholders notified · approval requiredReview
4AUDIENCE TYPES
EveryCOMMIT CHECKED FOR DRIFT
5DEPLOY TARGETS PER CONTRACT
0SILENT BREAKING CHANGES
01Define the audience
One API, four very different promises
An internal service can absorb a schema change on Tuesday. A partner cannot. Elva starts from who the consumer is, then applies the governance that audience deserves, instead of one policy for everyone.
01Internal service
Another team or microservice. Lighter governance, faster iteration, full field access.02Partner integration
An external company consuming your API. Strict versioning, approval required before publish.03Public API
Open to any developer. Needs rate limits, a sandbox, and a changelog anyone can read.04AI agent / MCP
Agents consuming via MCP tools. Needs rich descriptions, typed schemas, and tool stability above all.02Field-level control
Decide field by field what leaves the building
Include an endpoint but hide its internal fields. Redact PII for partners while your own services keep it. The gateway enforces exactly this, so a contract is not documentation, it is behavior.
GET /payments/{id}9 of 14 fields exposed to partner
Quick actions:Required onlyExclude PIIExclude internal
ONFIELDTYPEDESCRIPTIONPARTNER SEES
idStringPayment identifiervisible
amountNumberCharged amount in minor unitsvisible
currencyStringISO 4217 currency codevisible
statusEnumsucceeded, pending, failedvisible
customer_emailPIIStringBilling contact for this paymentredacted
risk_scoreinternalNumberInternal fraud heuristichidden
ledger_refinternalStringInternal accounting referencehidden
enforced at the gateway on every call, not just written in the docsinternal services still receive all 14 fields
03Policies
Block, warn, or notify. You pick per contract
Internal contracts warn and move on. Partner and agent contracts block the publish until a human approves. The rule lives with the contract, so nobody has to remember which API is delicate.
Contracts4 active
payments-internalinternal · 38 endpoints · 6 consumers
warnpayouts-partnerpartner · 12 endpoints · 4 consumers
blockorders-publicpublic · 24 endpoints · sandbox on
blockacme-payments-agentAI agent · 23 tools · 4 agents
blockgithub · PR #482 · elva bot
elva bot commented on this pull request
✕ 2 breaking changes affect 1 contract
payouts-partner v1.4 audience: partner
DELETE /builds/{id} response field "buildLog" removed
GET /billing/plans auth scope tightened
◷ publish blocked by policy: block-publish
affected consumers: 2 services, 1 partner build, 1 MCP client
approve in Elva or bump to v2 to proceed
04Publish
Approve once, ship five artifacts
A contract is the single definition behind your spec, docs, SDK, Postman collection, and MCP server. Approve the change once and every artifact regenerates in sync, with a changelog your consumers can read.
Contract approvedpayouts-partner v1.5 · signed off by platform
API
OpenAPI 3.1 specversioned, diffable
DOC
Docs sitepublished, per audience
MCP
MCP serverscoped tools, hosted
SDK
Client SDKsTS, Python, Go
PM
Postman collectionshareable with partners
A changelog consumers can subscribe toEvery approved change becomes a public entry with the version, the affected endpoints, and a migration note. Partners stop emailing to ask what moved.
Audit trail on every decisionWho proposed the change, who approved it, which policy applied, and when each artifact picked it up. Exportable, and the answer to most compliance questions.
The piece nobody else has
Contracts are what turn a catalog into governance
Other tools document APIs or proxy them. Elva connects the catalog, the tests, and the gateway to one promise per audience, and enforces it.
The catalog is the inputYou cannot promise what you have not mapped. Contracts pick from the endpoints, fields, and consumers Elva already found.API Catalog →
Tests prove the promiseContract tests run on every PR and verify the live API still returns the shape you committed to.API Testing →
The gateway enforces itScopes, field redaction, and rate limits at runtime come straight from the contract. Documentation cannot deny a call, a gateway can.MCP Management →
FAQ
What is an API contract in Elva?
A named, versioned view of your API for one consumer: which endpoints they see, which fields exist for them, how they authenticate, and what happens when something they depend on changes. Contracts are machine-checked on every commit.
How does Elva detect breaking changes?
Every commit regenerates the spec from code and diffs it against each contract touching the affected endpoints. Changes are classified as breaking, compatible, or cosmetic, and each contract carries its own policy: block publish, warn, or notify.
Which audiences can a contract target?
Internal, partner, public, and AI agent. Each audience gets its own visibility and guarantees over the same underlying endpoints, and MCP tools are generated from the agent contract.
Ship changes without the apology email
Your first contract takes about five minutes. It watches every commit after that.