Every developer knows they should maintain an OpenAPI spec. Most don't keep it perfectly up to date. Some treat it as documentation debt — something to fix eventually. In a human-first API economy, that's an annoying but survivable choice. Human developers can read source code, try endpoints, read blog posts, file support tickets when things don't match.
Agents can't do any of that.
When an agent evaluates your API, the OpenAPI spec is often the primary source of truth. It tells the agent what endpoints exist, what they accept, what they return, what they cost, and what authentication they require. If the spec is wrong or incomplete, the agent's model of your API is wrong. It will either fail to integrate or integrate incorrectly — and because it's a machine, it won't know to go looking for the discrepancy.
We watch agent behaviour in our nginx logs closely. One pattern that stands out: agents hitting /openapi.json before they hit any data endpoint. Not as an afterthought — as the first thing they do.
# Typical agent discovery sequence — Mar 29 54.196.217.153 - "GET /openapi.json HTTP/1.1" 301 # reads spec first 54.196.217.153 - "GET /llms.txt HTTP/1.1" 200 # then the manifest 54.196.217.153 - "HEAD /oracle/price/btc/usd" 200 # then probes endpoints 54.196.217.153 - "GET /oracle/price/btc/usd" 402 # then attempts payment
The spec comes first. The agent uses it to build its understanding of what's available, then validates against the live endpoints. If the spec and reality don't match, the agent's behaviour becomes unpredictable.
We've also seen the cost of a bad spec directly. A Scaleway agent hit /dlc/attestations?hours=48 — a URL that doesn't exist. It returned a 404. The agent moved on. Looking at the logs, it's clear the agent had read an earlier version of our spec that documented the wrong URL format. We had updated the spec but the agent had cached the old version. One missed update, one lost integration opportunity.
Every endpoint, exactly as it exists in production. Not aspirational. Not documentation of endpoints you plan to build. The actual endpoints, with the actual parameters, returning the actual response schemas. An agent that calls an endpoint based on your spec and gets a different response than documented will fail silently.
If your API uses L402 or x402, document it. Agents need to know which endpoints require payment, how much, and in which currency. The x402 spec defines extensions for this. Use them. An agent that can't determine payment terms from the spec will either skip the endpoint or attempt to call it without payment setup.
Document every field in every response. Including optional fields. Including error responses. An agent building a data pipeline from your response schema needs to know what it might receive, not just what it will typically receive. Missing fields in the schema create undefined behaviour downstream.
Version your spec. When you make breaking changes, update the version. An agent that integrated against v1.2 needs to know when you ship v1.3. If you don't version, you're silently breaking integrations every time you change something.
We protect our spec with a Git pre-commit hook that blocks commits to any of our backend service files unless openapi.json is also staged. It sounds aggressive. It's been invaluable.
#!/bin/sh # Block commits to API files unless openapi.json is staged STAGED=$(git diff --cached --name-only) API_CHANGED=$(echo "$STAGED" | grep -E "server\.py|x402_proxy\.py|main\.go") SPEC_STAGED=$(echo "$STAGED" | grep "openapi.json") if [ -n "$API_CHANGED" ] && [ -z "$SPEC_STAGED" ]; then echo "Error: API files changed but openapi.json not staged." echo "Update the spec or use --no-verify to bypass." exit 1 fi
The bypass is there for legitimate cases where you're making changes that don't affect the API contract. But the default is: if the API changes, the spec changes. This is the discipline that keeps machine-readable documentation accurate.
In the human API economy, documentation is a convenience. Developers read it, understand it, and then rely on their own understanding when the docs fall behind. They can file a ticket. They can ping you on Slack. They can inspect the response and figure out what's actually happening.
In the agentic economy, the spec is the contract. Agents sign it — implicitly, by building their integration model from it — before they spend a single satoshi. If the contract is wrong, the integration is wrong. And unlike a human developer, an agent won't complain. It will just stop working, silently, and you'll see it in the logs as a 402 that never converts.
Treat your OpenAPI spec like production code. Version it. Test it. Keep it accurate. It's not documentation. It's the interface through which machines decide whether to trust you with their money.
OpenAPI v1.5.0 — 140 paths, all documented with payment terms, response schemas, and methodology references. Updated with every release.
Mycelia Signal is a sovereign cryptographic oracle — 63 signed endpoints across crypto, stablecoin pegs, volatility indices, FX, economic indicators, and commodities. Payable by AI agents via Lightning (L402) or USDC on Base (x402). myceliasignal.com