Agent Fieldnotes API documentation

Use the public read-only Agent Fieldnotes API, CLI, and browser methods with exact IDs, revision checks, and explicit permissions.

When to use Agent Fieldnotes

Use this public team reference to find the reasoning behind agent workflows, copy full references with their caveats, or build a learning brief suited to someone's role and experience. Start with a concrete question: what should a new developer verify, how should a maintainer bound an agent task, or which decisions should a technical lead keep explicit? Retrieve the complete relevant articles, compare their tradeoffs, and cite their URLs and headings. A useful brief separates source recommendations from behavior you have verified in your own project.

The library supplies reference material, not personalized inference or proof that an example fits your environment. Read related articles before generalizing a single example. Copying an example is not permission to execute it. Original linked sources may have separate access requirements; the coverage inventory states the scope and exclusions rather than claiming every linked video was independently transcribed.

For the library's creator, audience, and source boundaries, see About Agent Fieldnotes. The privacy guide explains local search, URL state, clipboard actions, and hosting requests. Use the contact guide to report a correction, and the version and compatibility policy for breaking changes, deprecation, and sunset rules.

Public read contract

No login, API key, or authorization header is required. Send GET requests without an input body; HEAD is available for headers only. There are no server writes, hosted search queries, account state, remote code execution, hosted inference, or MCP server. The OpenAPI 3.1 description describes these real resources:

HTTP negotiation, delivery headers, and typed gateway errors described here apply to the published canonical origin https://robust-reef-dmr6.here.now, advertised as canonicalOrigin in the capability manifest. A local static preview is for browsing assets and pages; it does not provide that HTTP delivery contract.

Resource Result
/agent.json Capabilities, permissions, limits, and current revision
/api/v1/index.json Categories and all document metadata
/api/v1/search.json Metadata plus full text for local filtering
/api/v1/documents/{id}.json One exact-ID reference with full Markdown
/api/v1/coverage.json Source-unit mappings and explicit exclusions
/downloads/knowledge-base.json Complete structured corpus

JSON uses schemaVersion as the string "1". The revision is a 16-character lowercase hexadecimal value; this guide's corpus revision is 22ce5d34dbcb5a78. Metadata includes id, title, summary, category, categoryId, tags, collection, wordCount, url, markdownUrl, jsonUrl, headings, sources, and sourceUnits. Complete document JSON adds the full body in markdown, not an excerpt. Search records instead add text. The complete JSON export has one outer revision covering its documents.

Discover resources through HTTP links

At the canonical origin, HTTP Link response headers expose api-catalog for /.well-known/api-catalog, service-desc for OpenAPI, service-doc for this API documentation, describedby for capabilities, and index for llms.txt. The API catalog is served as application/linkset+json with the RFC 9727 profile. Follow these advertised links to discover supported resources, then read the manifest and choose exact IDs from the index rather than inventing endpoints. Canonical HTML and Markdown page responses also advertise their actual alternate representation; preserve the target URL and its query parameters when following that link.

Discover, choose an exact ID, and read

The shell examples require curl and jq. They save only local files. This example selects an observed ID rather than inventing a slug:

BASE='https://robust-reef-dmr6.here.now'
curl --fail --silent --show-error "$BASE/agent.json" -o capabilities.json
curl --fail --silent --show-error "$BASE/api/v1/index.json" -o index.json
REVISION="$(jq -er '.revision' capabilities.json)"
jq -e --arg revision "$REVISION" '.schemaVersion == "1" and .revision == $revision' index.json || exit 1
ID="$(jq -er '.documents[0].id' index.json)"
curl --fail --silent --show-error -H 'Accept: application/json' \
  "$BASE/api/v1/documents/$ID.json" -o document.json
jq -e --arg id "$ID" --arg revision "$REVISION" \
  '.schemaVersion == "1" and .id == $id and .revision == $revision' document.json || exit 1
MARKDOWN_URL="$(jq -er '.markdownUrl' document.json)"
curl --fail --silent --show-error -H 'Accept: text/markdown' \
  "$BASE$MARKDOWN_URL" -o reference.md

Before combining the Markdown with other references, compare its frontmatter revision and id with the inspected JSON. The CLI below performs this check automatically. A mismatch means stop, rediscover, and select again—not silently accept stale material.

Preserve the advertised Markdown URL in full, including raw=1 and v. The raw parameter keeps file retrieval out of the host's Markdown preview wrapper; v identifies the expected corpus revision but is not a historical-version selector. For canonical HTML page URLs, request Markdown through Accept instead:

curl --fail --silent --show-error -H 'Accept: text/markdown' 'https://robust-reef-dmr6.here.now/'

At the published canonical origin, page responses vary by Accept and Accept-Encoding. The gateway uses Cache-Control: no-store. Do not reuse a cached HTML response as Markdown, or assume query parameters pin content forever. Compare the body revision across discovery, index, search, document, and exports; X-Corpus-Revision identifies the delivered snapshot. See the version policy.

Follow entrypoints.agentInstructions from agent.json to the public agent instructions. The filename is case-sensitive: /AGENTS.md is the sole Markdown guide file. The HTML guide remains at /agents/; requesting that page with Accept: text/markdown retrieves the same public instructions.

Filter the full-text index locally

The search resource is a file, not a hosted query service. Download it once for the revision you are using, then filter locally. Adding q, category, limit, or offset to an HTTP URL does not perform a server-side search.

curl --fail --silent --show-error "$BASE/api/v1/search.json" -o search.json
jq -e --arg revision "$REVISION" '.revision == $revision' search.json || exit 1
jq --arg term 'verification' '
  [.documents[]
   | select(([.title, .summary, (.tags | join(" ")), .text]
       | join(" ") | ascii_downcase | contains($term)))
   | {id, title, categoryId, jsonUrl, markdownUrl}][0:5]
' search.json

Use categoryId values from the index for role-appropriate subsets. Search matches guide retrieval; they do not replace reading the full article or checking its caveats.

Bounded CLI reads

Download the public CLI, inspect it before running, and use a local Node.js runtime with fetch support. It makes read-only HTTP requests and never executes the reference content. These commands reuse an observed revision and exact ID:

curl --fail --silent --show-error 'https://robust-reef-dmr6.here.now/agent-cli.mjs' -o agent-cli.mjs
node agent-cli.mjs help
node agent-cli.mjs discover --source "$BASE"
node agent-cli.mjs inspect --source "$BASE" --revision "$REVISION"
node agent-cli.mjs list --source "$BASE" --revision "$REVISION" --limit 5 --offset 0
node agent-cli.mjs query --source "$BASE" --revision "$REVISION" --q 'verification' --limit 5 --offset 0
node agent-cli.mjs read --source "$BASE" --revision "$REVISION" --id "$ID" --format markdown
node agent-cli.mjs export --source "$BASE" --revision "$REVISION" --format json > knowledge-base.json

For list and query, limit is 1–100 (default 20), offset is a nonnegative integer, and nextOffset is null when finished. Query accepts at most 500 characters and requires every whitespace-separated term to match. Optional --category takes an exact category ID or label. These bounds limit displayed results, not the size of the downloaded index. Read returns one complete reference; export returns the complete corpus, not a truncated page. The CLI caps each response at 32 MiB and each request at 20 seconds; Ctrl-C cancels. The delivery gateway has a separate 4 MiB uncompressed response bound and shared 20-second request deadline.

CLI JSON successes use {requestId,status,revision,result}; Markdown successes are raw text. CLI errors use {requestId,status,error:{code,message}} and a nonzero exit status. Codes include INVALID_INPUT, HTTP_ERROR, NETWORK_ERROR, RESPONSE_TOO_LARGE, INVALID_RESPONSE, STALE_REVISION, and NOT_FOUND. This local envelope is distinct from HTTP problem details below; the CLI does not expose a new server API.

Browser methods and permissions

On this site's pages, window.WorkshopAgent exposes discover(), inspect(), query(), reset(), and copy(). These are browser methods, not remote endpoints. Inspect returns actual page and search state; discover downloads metadata. Query and reset change local search state and the page URL. Use the current discovered revision when changing state:

const agent = window.WorkshopAgent;
const page = agent.inspect();
const discovery = await agent.discover();
if (!discovery.ok) throw new Error(discovery.error.message);
const expectedRevision = discovery.revision;
const matches = await agent.query({ q: "verification", category: "", expectedRevision });
if (!matches.ok) throw new Error(matches.error.message);
console.log(page.page, matches.results.map(({ id, title }) => ({ id, title })));
// Reset only when you intend to clear the current search:
const reset = await agent.reset({ expectedRevision });
if (!reset.ok) throw new Error(reset.error.message);

A category must be an exact discovery.categories id; the empty string means all categories. Results include ok, status, requestId, revision, and current state. Check ok before using a result. A superseded query is not a successful search. STALE_REVISION requires reloading and rediscovering rather than bypassing the check.

Copy is the one operation that writes outside page state: it writes the local clipboard. Only invoke it for an explicit user-requested copy of an inspected reference. It can require browser permission or a user gesture; a headless call is not guaranteed permission. This separate example uses an observed search result:

const selected = matches.results[0];
if (!selected) throw new Error("No reference selected");
// Only from the user's requested copy action:
const copied = await agent.copy({ id: selected.id, format: "markdown", expectedRevision });
if (!copied.ok || !copied.copied) console.error(copied.error);

Format may be markdown or url. Copy checks the current document's identity and revision. CLIPBOARD_UNAVAILABLE means text was retrieved but not copied: the page selects the exact text for manual copying and the result reports copied:false and fallback:"selection". Never report success from retrieval alone.

Search filtering runs locally; there is no hosted search or inference service. Search state lives in the page URL, so opening, reloading, or sharing a search URL sends that URL, including search terms, to hosting services. The application does not submit clipboard text or prompts, and implements no analytics or request recording. Hosting platforms retain their own ordinary request logs and privacy policies; linked third-party sites have their own policies.

Typed HTTP errors and recovery

For the JSON resources above, failed gateway reads return application/problem+json following RFC 9457. Every problem includes type, title, status, detail, code, requestId, instance, and links with index, llms, and sitemap. The X-Request-ID response header matches requestId. type is about:blank; code is the machine-readable distinction. Check the HTTP status and media type before reading a success schema. Request IDs are diagnostics, not credentials.

HTTP status Code Recovery
404 NOT_FOUND Follow links.index and select a current exact ID.
405 METHOD_NOT_ALLOWED Use GET or HEAD; Allow lists GET, HEAD. There is no write operation.
406 NOT_ACCEPTABLE Request application/json for JSON, or text/markdown for canonical Markdown.
500 CONFIGURATION_ERROR Delivery configuration is unavailable; do not infer an empty library.
502 UPSTREAM_UNAVAILABLE The backing public resource could not be retrieved safely; use a bounded retry.
502 RESPONSE_TOO_LARGE The resource exceeded the gateway bound; prefer individual references when possible.
504 UPSTREAM_UNAVAILABLE The retrieval deadline expired; a bounded retry is safe.

Some backing delivery failures retain their upstream HTTP status with a typed problem; do not invent an application quota or an availability promise. A non-API missing page may instead return a useful Markdown or HTML 404 with recovery links. Network failure before an HTTP response is not an RFC 9457 body. The following reads a deliberately unknown JSON path without suppressing its error body:

curl --silent --show-error -i -H 'Accept: application/json' \
  'https://robust-reef-dmr6.here.now/api/v1/not-a-resource.json'

Keep diagnostics separate from article text. Reads are idempotent, but repeated failures are not permission to invent content, drop revision checks, or execute source examples.