--- title: "API Contracts — governance for every API change · Elva" description: "Define what each audience sees per endpoint and field. Elva checks every commit for drift, warns or blocks breaking changes, and notifies affected consumers." canonical: "https://getelva.ai/contracts" lastModified: "2026-09-01T23:11:23.016Z" --- 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. [Create a contract](https://app.getelva.ai/signup) [See the catalog](https://getelva.ai/catalog.md) Per-audience scope Field-level control Block-publish policies Only in Elva payouts-partner contract v1.4 2 breaking audience partner endpoints 12 consumers 4 policy block commit a91f2c · 6 files no contract impact POST /payouts added additive · in scope GET /payouts/{id} · field "fee" now nullable warn · partners notified DELETE /builds/{id} · "buildLog" removed breaking · 2 consumers GET /billing/plans · scope tightened breaking · 1 partner build docs and SDK regenerated pending approval publish blocked · 4 stakeholders notified · approval required Review 4 AUDIENCE TYPES Every COMMIT CHECKED FOR DRIFT 5 DEPLOY TARGETS PER CONTRACT 0 SILENT BREAKING CHANGES 01 Define 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. 01 Internal service Another team or microservice. Lighter governance, faster iteration, full field access. Internal visibility · Warn on breaking · Spec + Docs 02 Partner integration An external company consuming your API. Strict versioning, approval required before publish. Partner visibility · Block-publish · Postman + SDK + Docs 03 Public API Open to any developer. Needs rate limits, a sandbox, and a changelog anyone can read. Public visibility · Block-publish · Full publishing 04 AI agent / MCP Agents consuming via MCP tools. Needs rich descriptions, typed schemas, and tool stability above all. Public visibility · Block-publish · MCP Server + Spec 02 Field-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 only Exclude PII Exclude internal ON FIELD TYPE DESCRIPTION PARTNER SEES id String Payment identifier visible amount Number Charged amount in minor units visible currency String ISO 4217 currency code visible status Enum succeeded, pending, failed visible customer\_email PII String Billing contact for this payment redacted risk\_score internal Number Internal fraud heuristic hidden ledger\_ref internal String Internal accounting reference hidden enforced at the gateway on every call, not just written in the docs internal services still receive all 14 fields 03 Policies ## 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. Contracts 4 active payments-internal internal · 38 endpoints · 6 consumers warn payouts-partner partner · 12 endpoints · 4 consumers block orders-public public · 24 endpoints · sandbox on block acme-payments-agent AI agent · 23 tools · 4 agents block github · 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 04 Publish ## 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 approved payouts-partner v1.5 · signed off by platform API OpenAPI 3.1 spec versioned, diffable DOC Docs site published, per audience MCP MCP server scoped tools, hosted SDK Client SDKs TS, Python, Go PM Postman collection shareable with partners A changelog consumers can subscribe to Every 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 decision Who 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 input You cannot promise what you have not mapped. Contracts pick from the endpoints, fields, and consumers Elva already found. API Catalog → ](https://getelva.ai/catalog.md)[ Tests prove the promise Contract tests run on every PR and verify the live API still returns the shape you committed to. API Testing → ](https://getelva.ai/testing.md)[ The gateway enforces it Scopes, field redaction, and rate limits at runtime come straight from the contract. Documentation cannot deny a call, a gateway can. MCP Management → ](https://getelva.ai/mcp.md) ## 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. RELATED READING [ Contracts Aug 28 · 8 min How teams maintain API contracts without a manual spec Read → ](https://getelva.ai/blog/automatic-api-contracts-without-manual-specs.md)[ Product Jun 18 · 6 min Contracts: one API, four audiences Read → ](https://getelva.ai/blog/contracts-one-api-four-audiences.md)[ Governance Aug 27 · 5 min API versioning strategies that survive breaking changes Read → ](https://getelva.ai/blog/api-versioning-breaking-changes.md) ## Ship changes without the apology email Your first contract takes about five minutes. It watches every commit after that. [Create a contract](https://app.getelva.ai/signup) [See plans](https://getelva.ai/pricing.md)