Work with AI agents

Guardrails for AI agents that write APIs

An agent renames a response field as readily as a variable, without asking which clients read it. Catch the incompatible change in its local checks, and again in the required CI check.

Put the checks in the agent's loop Install API Genie

A linter that says noapigenie lint exits with status 1 and names each issue's line and rule, as JSON on request, so an agent fixes what it broke instead of guessing.
A diff that rates the changeapigenie diff rates each change by what it does to a client, as a status, a changelog or JSON. Run as a required check against the base branch, it stops a breaking change even when the agent skipped its local checks.
Edits that review cleanThe formatter gives the same file every time, and --fix keeps your comments, so an agent's change is a small diff a person can read.

A rename rejected, then done safely

The agent renames customerName to customer_name in a response. apigenie diff against the base branch's file rates the response change breaking and exits with 1. The agent keeps the old field, marks it deprecated, adds the new one, and the recheck passes, as JSON it can read. A required CI check runs the same command on the pull request, so merging depends on it, not on the agent's local run.

$ apigenie diff main.yaml api.yaml
api.yaml
  10  7  breaking  Modified operation GET /orders/{orderId}
  10  7  breaking  Modified response code 200
$ echo $?
1
$ # keep customerName, deprecated; add customer_name
$ apigenie diff main.yaml api.yaml \
    --report status --formatter json
{
  "formatVersion": 1,
  "status": "non-breaking"
}
$ echo $?
0

What it covers

One table of exit statusesShared by the four binaries, and frozen by the 1.0 compatibility promise for apigenie, the generator and the server.
JSON on requestlint, diff, format, test, the catalog and the server's contract report, each with a formatVersion that changes only when a field is removed or changes meaning.
A configuration with a schemaapigenie.yaml is checked against its JSON Schema before any command reads it.
Docs an agent can readGuides, reference pages and linter rules as Markdown, listed in llms.txt and collected in llms-full.txt.
MCP servers from the contractapigenie-generator server mcp writes a tool per operation (experimental).
Generated code, checkedA validating proxy checks what an agent's server returns against the contract.

The tools that do it

Step by step

Work with AI agents: Put the linter, the diff and the formatter in a coding agent's loop, so that what it changes in a contract is checked the way a person's change is.

The same answer for the agent, the reviewer and CI

lint, diff and format give the agent JSON, the reviewer text and CI an exit status, with the same rules behind each.