Site API (agentfield.ai)

The public read-only API on agentfield.ai for searching and reading AgentField documentation, plus its error model, versioning and deprecation policy, and rate limits.

The public API served by agentfield.ai itself — search the documentation, list every page, and read a page as markdown, without scraping HTML.

This is not the AgentField control plane REST API. That one runs in your deployment and executes agents. This one runs on this website and only serves documentation. Machine-readable description: /openapi.json.

If you are an autonomous agent, start with /agents.md — it covers when to reach for AgentField and how to call this API.

Endpoints

No authentication is required. Everything except POST /api/v1/shares is read-only.

Method	Endpoint	`operationId`	Purpose
GET	`/api/v1/search?q={query}&limit={1-20}`	`searchDocumentation`	BM25 search across every documentation page
GET	`/api/v1/topics?category={category}`	`listDocumentationTopics`	Every page with title, description, category, keywords
GET	`/api/v1/page?path=/docs/{slug}`	`getDocumentationPage`	One page as markdown, plus metadata
POST	`/api/v1/shares`	`createRunShare`	Publish a run bundle to a permalink (used by `af share --public`)

curl -s "https://agentfield.ai/api/v1/search?q=shared+memory+between+agents&limit=3"
curl -s "https://agentfield.ai/api/v1/page?path=/docs/build/building-blocks/agents"

The older unversioned paths — /api/agent/search, /api/agent/topics, /api/agent/page — still work and return their original response shape. They are aliases, they are not scheduled for removal, and each advertises its versioned successor with a Link: rel="successor-version" header. New integrations should use /api/v1/.

Markdown instead of JSON

Every documentation page also serves markdown from its ordinary URL through content negotiation:

curl -H "Accept: text/markdown" https://agentfield.ai/docs/learn/quickstart

Responses carry Vary: Accept. A client that accepts neither text/html nor text/markdown gets a 406.

Errors

Every non-2xx response is an RFC 9457 problem document served as application/problem+json.

{
  "type": "https://agentfield.ai/docs/reference/site-api#errors",
  "title": "Missing required parameter",
  "status": 400,
  "detail": "The required query parameter \"q\" is missing or empty.",
  "instance": "/api/v1/search",
  "code": "missing_parameter",
  "resolution": "Retry with a non-empty q, for example /api/v1/search?q=shared+memory+between+agents.",
  "documentation_url": "https://agentfield.ai/docs/reference/site-api#errors"
}

Branch on code, never on detail. code is part of the contract; detail is prose and may be reworded. resolution tells you what to do next, and some responses add an available_endpoints object listing what to try instead.

`code`	Status	Meaning
`invalid_request`	400	The request was understood but a value is wrong
`missing_parameter`	400	A required query parameter is absent or empty
`not_found`	404	No such endpoint, or no documentation page at that path
`method_not_allowed`	405	The endpoint exists but not for this method
`not_acceptable`	406	The client accepts no representation this site produces
`payload_too_large`	413	The request body exceeds the endpoint's limit
`rate_limited`	429	The client exceeded its request budget
`internal_error`	500	Unexpected server-side failure
`upstream_unavailable`	502	A generated artifact could not be loaded
`service_unavailable`	503	A dependency is not configured on this deployment

New codes may be added over time. Treat an unrecognised code as a generic failure of its HTTP status class rather than erroring out.

Rate limits

Reads are limited to 120 requests per 60-second window per client address. Every response publishes the current budget, so you can pace yourself instead of retrying blindly:

Header	Meaning
`RateLimit-Limit`	Requests allowed in the window
`RateLimit-Remaining`	Requests left in the current window
`RateLimit-Reset`	Seconds until the window resets
`RateLimit-Policy`	The policy in force, as `<limit>;w=<window-seconds>`
`Retry-After`	On a `429` only — seconds to wait before retrying

A 429 returns a rate_limited problem document alongside Retry-After.

Versioning and deprecation

The supported surface is versioned in the URL path: /api/v1/.... Every response also carries an X-API-Version header so a caller can assert what it reached.

What ships where

Breaking changes get a new path prefix (/api/v2/...). An existing version keeps its response shape for as long as it is served — fields are never removed or retyped in place.
Additive changes — new endpoints, new optional response fields, new code values — ship inside the current version without a version bump. Ignore fields you do not recognise.

How a retirement is signalled

When a version is scheduled for removal, its responses begin carrying all three of the following at least 180 days before the sunset date:

Header	Spec	Meaning
`Deprecation`	RFC 9745	The date the version became deprecated
`Sunset`	RFC 8594	The date after which it stops responding
`Link; rel="successor-version"`	RFC 5829	Where to go instead

No Sunset header is emitted today, on any endpoint, because nothing is scheduled for removal — RFC 8594 treats Sunset as a committed date, so it is not sent speculatively. The unversioned /api/agent/* aliases send only Link; rel="successor-version", which points at the versioned endpoint without implying a removal date.

The same policy is published in machine-readable form under x-api-lifecycle in /openapi.json.

Discovery

Surface	What it is
`/openapi.json`	OpenAPI 3.1 description of every operation above
`/agents.md`	When to use AgentField, and how to call it
`/pricing.md`	What it costs, in machine-readable form — $0, no paid tier
`/llms.txt`	Concise site and API index
`/llms-full.txt`	The complete documentation corpus as plain text
`/docs-ai.json`	Documentation manifest
`/.well-known/ai-catalog.json`	Agentic Resource Discovery catalog for this domain
`/.well-known/ai-plugin.json`	Plugin discovery manifest