Live Demo
Reference Implementation api-agent.yaml v0.4
Live Demo

The API Field Guide, live

Point your AI coding agent at a real API and watch it negotiate the quirks using the field guide. There is no sign-up and nothing to install. The API is the demo, and your agent is the client.

# start your agent here: the directory for everything hosted at this domain
https://api-agent.tristandenyer.com/.well-known/api-agent.yaml

What this is

A live, stateless reference implementation of the api-agent.yaml spec. Each scenario is a real API endpoint with deliberate, real-world quirks that the OpenAPI spec alone does not explain, such as a read-after-write delay, a strict filter grammar, and a human-approval gate.

The point is to feel the difference the field guide makes. Give your agent a task with the field guide and it reasons its way to a clean result. Give it the same task without the guide and watch it stumble into the traps a human integrator hits on day one. Every scenario below gives you both prompts, so you can run the comparison yourself.

How to run it

Paste a prompt below into a coding agent. The guided prompts start it at the discovery entry point, from which it fetches the field guide, follows it to the API, and works the task. You watch it happen, and any human-in-the-loop steps come back to you.

It runs live in any agent with outbound HTTP, such as Claude Code, Cursor, or a custom agent, so you see the calls execute against the API in real time.

Agent in a locked-down sandbox? Some agents sandbox their network and tools, so you may see host_not_allowed, or find that the fetch tool is read-only and cannot POST /register. That is still a successful run. The hard part is reasoning about an unfamiliar API from its field guide, and a good agent does that whether or not it can reach the host. It hands you a correct, ready-to-run script with every quirk encoded: the read-after-write wait, the strict filter, and the case-sensitive tag. Running that script yourself takes about ten seconds.
  • To let the agent execute live instead, allow egress to api-agent.tristandenyer.com and give it a tool that can POST, such as a shell or curl, then re-run.
Either way, the API is open to everyone. The limits are on the caller's side, and clearing them is itself part of getting an API working.

Everything here is a public sandbox. There is no real data and there are no accounts, so it is safe to call freely.

Scenarios

Records API: autonomous CRUD

Live

A create, read, update, and delete API your agent can drive from start to finish on its own. The traps: authentication is self-serve, a new record is not readable for about two seconds, the list filter uses a strict grammar, and tags are case-sensitive.

Guided prompt: hand your agent the field guide 
Task against the API at https://api-agent.tristandenyer.com/records/v2 .
First fetch https://api-agent.tristandenyer.com/.well-known/api-agent.yaml and
follow it to this API's field guide, then obey it. Steps:
register for a key, create a record named "field-test" tagged
"active", retrieve that record, then list records tagged "active".
Control prompt: no field guide, so watch it stumble 
Using the API at https://api-agent.tristandenyer.com/records/v2 (OpenAPI at
/records/v2/openapi.yaml), register for a key, create a record
named "field-test" tagged "active", retrieve it, and list records
tagged "active". Do not read any api-agent.yaml.
What should happen
  • Self-serve auth: the guide says POST /register returns a Bearer key with no human involved. The control agent often assumes it needs a human-provided key.
  • Read-after-write lag: a GET right after create returns 404 for about two seconds. The guide flags this as model.consistency, so the agent waits and verifies. Without it, agents misread the 404 as a failed write and create the record a second time.
  • Filter grammar: the filter is exactly tag:active, and anything else returns a vague 400. The guide documents it as a parameterGotcha.
  • Case-sensitive tags: tag:Active and tag:active are different tags. The guide calls this out as a keyInsight; without it, the query returns a silent empty result.

Orders API: human in the loop

Live

A payment-style flow: preflight → place → confirm. Confirming a large order trips an approval gate, so your agent pauses and hands the decision back to you. You open the approval page in a browser, read the code, and pass it back.

Guided prompt: hand your agent the field guide 
Task against the API at https://api-agent.tristandenyer.com/orders/v1 . First fetch
https://api-agent.tristandenyer.com/.well-known/api-agent.yaml and follow it to this
API's field guide, then obey it. Place an order for 3 units of
"demo-widget" at 4900 cents each, then confirm it. It exceeds the
approval gate, so when the API asks for human approval, stop and
give me the approval URL, and I will hand you back the code.
Control prompt: no field guide, so watch it stumble 
Using the API at https://api-agent.tristandenyer.com/orders/v1 (OpenAPI at
/orders/v1/openapi.yaml), place an order for 3 units of "demo-widget"
at 4900 cents each and confirm it. Do not read any api-agent.yaml.
What should happen
  • Proposal, not a charge: /place only proposes an order. The guide's keyInsights say you must /confirm to charge it, so control agents often stop at place.
  • Five-second token: the preflightToken from /preflight expires in five seconds, so call /place immediately. The guide documents this as a parameterGotcha.
  • The human gate: the $147 order clears the $100 threshold, so /confirm returns 403 with an approveUrl. The guide's humanGates tell a compliant agent to pause and route that URL to you before confirming. You open it, read the six-character code, and hand it back, and then /confirm with approvalCode charges the order.
  • Currency trap: uppercase USD is silently coerced to usd, so the guide tells you to use lowercase.

Sunset and successor: the self-healing loop

Live

Point your agent at a retired API version. It hits 410 Gone, reads the field guide's successor pointer, and hops to the live version to finish the task.

Guided prompt: start on the dead version 
Using the API at https://api-agent.tristandenyer.com/records/v1 , register for a key and
create a record named "field-test" tagged "active". If a version is
retired, follow its field guide (or the Link header on the response)
to the successor and complete the task there.
What should happen
  • 410 Gone: every /records/v1 call returns 410. The response carries a Link: …; rel="agent-contract" header and a successor pointer.
  • Read the field guide: /records/v1/api-agent.yaml has lifecycle.status: sunset and a successor.agentContract pointing at v2.
  • Hop and finish: the agent adopts v2 (the same key works), reads v2's field guide, and completes the create-and-retrieve there. That is the self-healing loop, and no human edited anything.

Built skeptical

An api-agent.yaml is advisory, API-authored, and untrusted by default. Because we are asking you to feed our file to your agent, it is worth saying plainly: a compliant agent treats the file as data to reason over, never as instructions to execute. Ours contains only descriptive guidance and no commands. See the spec's Security Considerations.