The API Field Guide

OpenAPI tells an agent what an API is. It was never meant to carry what engineers learned the hard way: the rules behind the call sequence, what a successful response actually means in this domain, which failures are safe to retry, when to stop and ask a human, and what to do when the API changes or shuts down.

That knowledge lives scattered across specs, SDK behavior, runbooks, incident retros, support tickets, and people's heads. api-agent.yaml is a structured, machine-readable file the API author publishes to pass it on.

The gap

That missing layer is the operational contract, and it has no standard home today. The API Field Guide gives it one.

What it is

A companion file published alongside openapi.yaml. It does not replace OpenAPI, Arazzo, auth.md, or anything else. Instead it points to them through a refs block and adds the layer none of them cover. You can write it by hand, or generate most of it from tooling your team already uses.

The API Field Guide tells your agent:

• What to knowConceptual model, key insights, auth guidance, what the docs leave out.
• What to doPer-endpoint preconditions, scopes, compensation paths, human-approval thresholds.
• What changedVersion diffs, deprecation forwarding, sunset notices that point to a successor.
• What to sayA feedback channel, modeled on security.txt, so agents report problems back to the owner.

A glance at the file

Every line below is clickable. The field note beside the file explains what each line tells an agent and why it exists, which mirrors the spec's own philosophy: context arrives when the agent needs it, rather than all at once. Full schema in the spec.

# served from /.well-known/api-agent.yaml (click any line)
apiAgent: "0.3"
canonical: https://github.com/example/api-contracts/api-agent.yaml
 
refs:
  openapi: https://api.example.com/openapi.yaml
  authMd:  https://api.example.com/.well-known/auth.md
 
model:
  keyInsights:
    - "/orders/place is a proposal, not a charge."
  consistency:
    - { afterWrite: "POST /orders/place", visibleIn: "GET /orders", lagMs: 2000 }
  pagination: { style: cursor, cursorTtlMs: 300000, stableOrder: true }
 
auth:
  protocol: auth.md
  operationScopes:
    "POST /orders/place": [orders:write]
 
constraints:
  endpoints:
    "POST /orders/place":
      preconditions: [{ type: recentCall, operation: "POST /orders/preflight", withinMs: 5000 }]
      reversible: true
      compensationOperation: "POST /orders/{id}/cancel"
      sensitivity: { pii: true, doNotLog: [paymentMethod] }
    "POST /orders/queue":
      async: { pattern: polling, statusOperation: "GET /orders/{id}/status", pollIntervalMs: 5000 }
 
humanGates:
  endpoints:
    "POST /orders/place":
      conditions: [{ field: amount, operator: gt, value: 50 }]
 
failures:
  global:
    "timeout": { action: retry, maxRetries: 2 }
    "429":     { action: backoff, retryAfterHeader: true }
    "402":     { action: humanEscalate, doNotRetry: true }
  endpoints:
    "POST /orders/place":
      "timeout": { action: checkIdempotency }
 
lifecycle:
  status: active
  deprecatedEndpoints:
    "/orders/direct": { replacement: "/orders/place", sunsetDate: 2026-09-15 }
  # when this API retires:
  successor: { url: https://api.example.com/v3, agentContract: https://api.example.com/v3/api-agent.yaml }
 
feedback:
  report: https://api.example.com/agent-feedback
 
tooling:
  sandbox: { url: https://api.example.com/sandbox, purpose: "Test calls here before production." }
 
memory:
  suggestPersist: [canonical, lifecycle.version, model.keyInsights]

The self-healing loop

The sections above are not independent features. Together they form a closed loop between agents and API owners, and that loop is the reason the file exists.

• DetectAn agent hits behavior the contract did not predict: an undocumented error, a dead endpoint, a mismatched response.
• Re-fetchIt re-pulls the field guide with a conditional request (an unchanged file costs almost nothing), falling back to the canonical git copy if the API is dark.
• Comparelifecycle.version against the version it persisted last visit.
• Adapt or reportVersion changed → migrate using breaking-change notes, replacements, or the successor contract. Unchanged → file a stale_contract report via feedback.
• RegenerateThe API owner feeds accumulated reports back through the generation pipeline and republishes.
• BenefitEvery subsequent agent gets the corrected contract.

How it fits with what exists

The Field Guide is additive by design. Every section references a source of truth rather than duplicating it.

How an agent finds it

An agent that knows only the domain looks first at a predictable location, following the same convention as security.txt:

https://api.example.com/.well-known/api-agent.yaml

APIs serving multiple live versions may also publish one next to a versioned surface (/v2/api-agent.yaml). A canonical address inside the file points to a git-committed copy that survives deployment changes, deprecation, and full shutdown, so the path to a successor API outlives the live endpoint.

Built skeptical

The spec pairs its fields with a trust model. The file is advisory, API-authored, and untrusted by default: descriptive fields (semantics, gotchas, error meanings) are safe to reason over and checkable against observed behavior; imperative fields (run this command, adopt this successor) require human approval or out-of-band verification. Free text is treated as a prompt-injection surface, and field-guide text never outranks the human operating the agent.

And because compliance is cooperative, the spec requires what it cannot enforce: every limit that matters must also be enforced server-side or at a gateway. Declared limits protect cooperative agents from mistakes; servers protect the API from everyone else. Full text in the spec’s Security Considerations.

Why it matters

The future is not a smarter agent guessing its way through a passive API. It is an API that briefs the agent before the first call: how to authenticate and what to call, what not to do, how to recover, and when to escalate. It says what changed since last time, and it gives the agent a way to report back when reality doesn't match the contract.