# Agent Fieldnotes API documentation

## 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](https://robust-reef-dmr6.here.now/api/v1/coverage.json) 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](https://robust-reef-dmr6.here.now/about/). The [privacy guide](https://robust-reef-dmr6.here.now/privacy/) explains local search, URL state, clipboard actions, and hosting requests. Use the [contact guide](https://robust-reef-dmr6.here.now/contact/) to report a correction, and the [version and compatibility policy](https://robust-reef-dmr6.here.now/versioning/) 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](https://robust-reef-dmr6.here.now/openapi.json) 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](https://robust-reef-dmr6.here.now/agent.json) | Capabilities, permissions, limits, and current revision |
| [/api/v1/index.json](https://robust-reef-dmr6.here.now/api/v1/index.json) | Categories and all document metadata |
| [/api/v1/search.json](https://robust-reef-dmr6.here.now/api/v1/search.json) | Metadata plus full text for local filtering |
| [/api/v1/documents/{id}.json](https://robust-reef-dmr6.here.now/api/v1/index.json) | One exact-ID reference with full Markdown |
| [/api/v1/coverage.json](https://robust-reef-dmr6.here.now/api/v1/coverage.json) | Source-unit mappings and explicit exclusions |
| [/downloads/knowledge-base.json](https://robust-reef-dmr6.here.now/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](https://robust-reef-dmr6.here.now/.well-known/api-catalog), **service-desc** for [OpenAPI](https://robust-reef-dmr6.here.now/openapi.json), **service-doc** for [this API documentation](https://robust-reef-dmr6.here.now/developers/), **describedby** for [capabilities](https://robust-reef-dmr6.here.now/agent.json), and **index** for [llms.txt](https://robust-reef-dmr6.here.now/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:

```sh
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:

```sh
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](https://robust-reef-dmr6.here.now/versioning/).

Follow entrypoints.agentInstructions from [agent.json](https://robust-reef-dmr6.here.now/agent.json) to the public [agent instructions](https://robust-reef-dmr6.here.now/AGENTS.md?raw=1). The filename is case-sensitive: **/AGENTS.md** is the sole Markdown guide file. The HTML guide remains at [/agents/](https://robust-reef-dmr6.here.now/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.

```sh
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:

```sh
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:

```js
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:

```js
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:

```sh
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.
