Site API (agentfield.ai)

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

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/agentfield/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/agentfield/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/agentfield/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/agentfield/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