API Contracts: governance for every API change · Evlio

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. Evlio watches every commit against it and stops the surprise before it ships.
Create a contract
See the catalog
Per-audience scope
Field-level control
Block-publish policies
Only in Evlio
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. Evlio 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 · evlio bot
evlio 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 Evlio 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. Evlio 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 Evlio already found.
API Catalog →
Tests prove the promise
Contract tests run on every PR and verify the live API still returns the shape you committed to.
API Testing →
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 →
FAQ
What is an API contract in Evlio?
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 Evlio 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.
From top startups to Fortune 500 companies, trusting Evlio
SOC 2 Type II
·
certified
ISO 27001 / 27701
·
certified
GDPR
·
compliant
Encryption
·
TLS 1.3 / AES-256
SSO / SAML and SCIM
·
available
Full security posture →
RELATED READING
Contracts
Aug 28
·
8
min
How teams maintain API contracts without a manual spec
Read →
Product
Jun 18
·
6
min
Contracts: one API, four audiences
Read →
Governance
Aug 27
·
5
min
API versioning strategies that survive breaking changes
Read →
Ship changes without the apology email
Your first contract takes about five minutes. It watches every commit after that.
Create a contract
See plans