Instructions to Agents — API Access & Site Administration

Audience: a non-human agent (LLM agent, CI job, monitoring bot, script) that needs to
read, manage, or administer this site programmatically. This document is complete and
self-contained: together with the site's base URL — and, for admin work, a bearer
token issued by a human administrator — nothing else is required.

1. What this site is

The site is a content platform organised as a three-level hierarchy:

• View — a top-level publication (its own title, branding, and sections).
• Section — an ordered group of items inside a view.
• Item — a single piece of content: metadata (a JSON "sidecar") plus a body document (markdown or HTML).

Everything below is relative to BASE_URL — the origin this page was served from
(e.g. https://example-site.example.com).

There are two API surfaces:

2. Public API — no authentication required

All public endpoints are plain HTTPS requests with JSON responses unless noted.
Use them to verify the public surface ("is the site up", "is the new item visible").

Start any session with GET /api/views: it returns the registry of view ids you will
need for every other call.

Notes:

• POST /api/suggestions is the only anonymous write. It is rate-limited and protected
  by an ALTCHA proof-of-work challenge; suggestions are stored privately for human
  editors and are never published automatically. Prefer the /suggest web form; only
  automate this endpoint if you have been instructed to.
• Subscribe/unsubscribe endpoints exist only when the mailing subsystem is enabled on
  this deployment; otherwise they answer 404/503.
• ?includeOutdated=true is required to read a section that has been marked
  revealed (see "Outdated content" in §5). Without it such a section 404s, exactly as
  a hidden section always has. It changes nothing for a normal section. The response
  carries outdated: true when the listing IS a revealed section.
• The item, body, download and thumbnail routes serve items from a revealed section and
  mark them "outdated": true in the metadata response. They still 404 for draft and
  archived items, for ordinary hidden sections, and for anything in an admin-only view.
• /api/reader/* is not part of either surface above and is not for you. When this
  deployment has reader accounts enabled, those routes back the human reader features —
  sign-in, saved items, personal collections — and authenticate with a browser session
  cookie, not a bearer token. Your admin token does not open them and they administer
  nothing. They are also invisible to anonymous callers, so they never affect what you
  verify through the public API.

3. Getting admin access

Admin access is granted only by a human administrator. There is no self-service
registration, and agents can never mint credentials for themselves or other agents.

1. A human administrator signs in to the admin UI and opens /admin/agents
   ("Agent tokens"), or runs the operator CLI (npm run admin:agent:create).
2. They issue a credential with an agent id, a label, and an expiration
   (30/90/365 days, a custom date, or never-expires).
3. The plaintext bearer token is shown exactly once. The administrator hands it to you
   through a secure channel, together with the site's BASE_URL.

The token is an opaque string of the form:

<agentId>.<secret>

The part before the first dot is your public agent id (e.g. monitor-bot); the rest is
a secret. The server stores only an HMAC hash of the token — if you lose it, it cannot
be recovered, only re-issued.

Your token carries the admin:* scope: every admin API operation is available to you
EXCEPT token management (§6).

4. How to authenticate

Send the token in the Authorization header of every request:

Authorization: Bearer <agentId>.<secret>

Rules:

• HTTPS only. Never call the API over plain HTTP.
• Header only. Never place the token in a URL, query string, request body, or log
  line — URLs leak into server logs and referrers.
• Store it in a secret manager. Never write the token into files, code, tickets,
  chat, or your own output. When reporting about yourself, identify by your public
  agentId only.
• No CSRF token needed. CSRF protection applies to human browser sessions only;
  bearer-token requests are exempt. Do not fetch /admin/api/csrf; do not send
  X-CSRF-Token or _csrf.
• No cookies needed. Do not maintain a session; every request is independently
  authenticated by the header. An invalid bearer token fails with 401 — it does not
  fall back to a session cookie.

Verify your access on handoff with a harmless read:

curl -sS -H "Authorization: Bearer $TOKEN" "$BASE_URL/admin/api/views"
# expect: HTTP 200 with the site registry JSON

5. Admin API — full endpoint inventory

Mutations take JSON bodies (Content-Type: application/json) unless noted. The public
catalog regenerates synchronously after every successful write — your change is
publicly visible on the next request; there is no cache to wait for.

Reads (monitoring surface)

The admin body read is the counterpart to the public GET /api/views/:viewId/items/:slug/body. The public one resolves items through the published catalog, so it cannot return an unpublished item or anything inside an admin-only view. Use the admin one whenever you need to read content you have staged but not published.

The single-item metadata read returns the bare item record — the same shape PATCH and move return, so a read-modify-write round trip is symmetric. Reach for it instead of listing a whole section and filtering client-side; sections grow, and the listing does not.

Writes (management surface)

Worked example — creating a view:

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  --data '{
    "version": 1,
    "id": "agent-created-view",
    "title": "Agent Created View",
    "description": "Created through agent admin authentication.",
    "source": { "backend": "azure-blob", "root": "agent-created-view" },
    "sections": [],
    "status": "draft"
  }' \
  "$BASE_URL/admin/api/views"

Item creation is multipart/form-data, and the part shapes are not interchangeable:

• metadata — a plain text field whose value is the metadata JSON string. It is
  NOT a file part. (It is stored server-side as the item's JSON "sidecar", but on the
  wire the field name is metadata.)
• body — a file part, carrying the HTML document. Required. Max 1 MiB.
• thumbnail — an optional second file part, carrying an image the site will host
  and serve itself. Max 2 MiB. See "Images and thumbnails" below.

Sending metadata as a file part is the most common mistake. The request is rejected
with 400 and the message "Unexpected file part 'metadata'". Retrying will not
help — fix the part layout instead. Any file part other than body and thumbnail is
refused the same way.

Worked example — creating an item:

# Write the sidecar to a file, then have curl read the field value FROM the file.
cat > sidecar.json <<'JSON'
{"slug":"my-article","title":"My Article","summary":"One-line summary — with an em-dash."}
JSON

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "metadata=<sidecar.json" \
  -F "body=@article.html;type=text/html" \
  "$BASE_URL/admin/api/views/$VIEW_ID/sections/$SECTION_ID/items"

Pass the metadata with -F "metadata=<file.json", not -F "metadata=$SHELL_VAR".
The < form makes curl read the field's value straight from the file, byte for byte.
Interpolating a shell variable instead truncates the value at the first non-ASCII
character, so a single em-dash or curly quote anywhere in a summary produces
400 VALIDATION_ERROR: metadata: Unterminated string in JSON at position … — the JSON
arrives cut in half. This bites constantly in practice, because editorial prose is full
of such characters, and the error message points at the JSON rather than at the
transport, which is what makes it hard to diagnose. (Note the difference between the two
sigils: <file reads a text field's value from a file, @file sends a file part.
metadata always wants the former — see the part-shape rules above.)

slug and title are required; summary, author, authorType, authorUrl,
publishedAt, tags, thumbnailUrl, sourceUrl, externalUrl, videoPublishedAt,
and status are optional. Everything else (version, view_id, section_id,
body_reference, source_type, sha256, thumbnail, createdAt, updatedAt) is
server-managed — do not send it. A successful create returns 201 with the stored item.

Replacing an item's body (PUT .../items/:slug/body) uses the same layout, except
metadata is optional there, and a thumbnail part replaces the image at the same time.

Images and thumbnails

An article's inline images need no special handling: they live inside the HTML
document you upload as body, whether as <img src="https://…"> pointing at a remote
host or as a data: URI embedded in the markup. Nothing about them is separate content
as far as this API is concerned.

The thumbnail — the single image representing the item on cards, list rows, and
social previews — is different, because it has to be addressable on its own. There are
two ways to give an item one, and you should understand both before choosing:

Prefer uploading a file whenever you have the image bytes. A thumbnailUrl is a
dependency on a host you do not control: when it rewrites its URLs or removes the image,
the card silently breaks and nobody finds out until a human notices. Reach for
thumbnailUrl only when you genuinely have nothing to upload.

When an item has both, the uploaded file wins everywhere the site renders artwork.
Setting thumbnailUrl on an item that already has an uploaded image therefore changes
nothing visible — remove the upload first if that is what you actually intend.

If you supply neither, the server tries to DERIVE a thumbnailUrl from the HTML body at
create time, in this order: an OpenGraph/Twitter meta image, <link rel="image_src">,
the first absolute <img src>, then a YouTube video still from an embedded <iframe>.
This is a convenience, not a guarantee — a body with no images yields no thumbnail.

The practical upshot: an article whose body already carries an OpenGraph meta image or
an embedded YouTube video needs no thumbnail work from you at all. Derivation covers it.
Check the create response — a 201 whose stored item already has a thumbnailUrl you did
not send means the server found one, and uploading an image on top of that is wasted work
(and, per the precedence rule above, changes what readers see). Spend the effort only on
items that come back with no thumbnail of any kind.

Rules for uploaded thumbnails:

• Accepted formats: JPEG, PNG, WebP, GIF, AVIF. Maximum 2 MiB.
• SVG is refused. It is an active document that can carry scripts and it would be
  served from this site's own origin. Convert to a raster format instead.
• The format is detected from the file's own bytes, never from the part's declared
  Content-Type or its filename. Mislabelling a file changes nothing; uploading a
  non-image labelled as one is rejected with 400.
• The stored filename is server-managed (<slug>.thumb.<ext>, beside the item).
  Do not attempt to set thumbnail through metadata — the field is stripped from
  PATCH bodies, and there is no way to point an item at an arbitrary file.
• The image follows its item: moving the item between sections or views relocates
  it, and deleting the item deletes it. You never manage the file separately.

Worked example — creating an item WITH a hosted thumbnail:

METADATA='{"slug":"my-article","title":"My Article","summary":"One-line summary."}'

curl -sS -X POST \
  -H "Authorization: Bearer $TOKEN" \
  -F "metadata=$METADATA" \
  -F "body=@article.html;type=text/html" \
  -F "thumbnail=@cover.jpg;type=image/jpeg" \
  "$BASE_URL/admin/api/views/$VIEW_ID/sections/$SECTION_ID/items"

Worked example — adding, replacing, or removing the thumbnail of an item that already
exists:

# Upload or replace. Idempotent — the same image twice leaves the same state.
curl -sS -X PUT \
  -H "Authorization: Bearer $TOKEN" \
  -F "thumbnail=@cover.webp;type=image/webp" \
  "$BASE_URL/admin/api/views/$VIEW_ID/sections/$SECTION_ID/items/$SLUG/thumbnail"

# Remove. Also idempotent: an item with no uploaded image answers 200, not 404.
# The item's `thumbnailUrl`, if it has one, is left alone and takes over again.
curl -sS -X DELETE \
  -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/admin/api/views/$VIEW_ID/sections/$SECTION_ID/items/$SLUG/thumbnail"

Both return 200 with the updated item. Its thumbnail record tells you what was
stored:

{
  "reference": "my-article.thumb.webp",
  "contentType": "image/webp",
  "bytes": 48211,
  "sha256": "9d2c…",
  "uploadedAt": "2026-07-30T08:11:00.000Z"
}

Reading a thumbnail back: GET /api/views/:viewId/items/:slug/thumbnail returns the
image bytes for a published item of a public view. It answers 404 when the item has no
uploaded image — including when it has a thumbnailUrl, because that URL is not ours to
serve; fetch it from its own host if you need it. The response carries an ETag (the
image's sha256), so a conditional re-fetch with If-None-Match answers 304. For
content that is not publicly visible — a draft, or anything inside an admin-only view —
use the admin route in §5 instead; the public one will 404 by design.

To verify an upload landed, re-read the item and check that thumbnail.sha256 matches
the hash of the file you sent.

All other mutations are plain JSON. You can discover most request shapes from reads:
fetch an existing record and mirror its structure. For write operations whose shape you
cannot discover from reads, ask your operator for the administrator operations guide.

Safety rules for destructive operations

1. Deletes are permanent. DELETE on a view or section removes it AND all its
   contents. Never delete anything you were not explicitly instructed to delete;
   prefer archiving (status: "archived" / the archive endpoint — soft removal from
   the public site) over deletion.
2. Read before you write. Fetch the current record with
   GET /admin/api/views/:viewId/sections/:sectionId/items/:slug, modify the fields you
   intend to change, and send only those fields in the PATCH — do not reconstruct records
   from memory.
3. One mutation at a time. The store uses optimistic concurrency; a 409 means
   someone else (the human admin, another agent) changed state under you — re-read and
   retry ONCE, then stop and report if it persists.
4. Never retry non-2xx blindly. Retry-storms against 401/403 responses look
   like an attack and achieve nothing.

Reviewing and promoting suggestions

GET /admin/api/suggestions lists the visitor-suggestion queue. Two optional filters:

• ?status=new|reviewing|accepted|rejected|promoted — a single status.
• ?months=1..12 — how far back to look. Defaults to 3, so older suggestions are
  invisible unless you widen it. An unexpectedly empty queue is usually this, not an
  empty store.

Review with PATCH /admin/api/suggestions/:id, which enforces a transition table:

promoted is NOT reachable by PATCH. It has a dedicated endpoint:

curl -sS -X POST -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/admin/api/suggestions/$ID/promote"

The suggestion must already be accepted — promoting from any other status is a 409
naming the current one. The response is {"redirectUrl": "…"}, a prefilled admin-upload
URL; promoting records the decision and hands you that link, it does not create the
item. Publishing is still a normal item create.

Rebuilding a view's catalog

POST /admin/api/views/:viewId/catalog/regenerate rebuilds one view's derived catalog
from its current source documents and reports what it produced:

{ "viewId": "agentnews", "generatedAt": "…",
  "sections": [
    { "sectionId": "news",    "items": 42, "outdated": false },
    { "sectionId": "history", "items":  3, "outdated": true  }
  ],
  "totals": { "sections": 1, "outdatedSections": 1, "items": 45 } }

Each entry reports one section's published-item count; outdated: true marks a section
that is revealed only behind the reader control (below).

It is idempotent and non-destructive — it creates nothing and deletes nothing, so it is
safe to run at any time. You do not need it during normal work: every content write
regenerates the affected view's catalog automatically.

It exists for the case a write cannot fix: when a deploy changes the catalog's shape
rather than its content. Stored catalogs keep the old shape until something rewrites
them, so a feature that reads a newly-added field stays silently inert until each view is
rebuilt. If a documented catalog-derived feature appears to do nothing on a view, run
this against that view before reporting a bug.

Outdated content — revealing a hidden section to readers

A hidden section can carry "reveal_as_outdated": true. Such a section stays off
navigation, the home page, the sitemap, keyword search and semantic search, and its pages
are served noindex — but readers get a "Show the outdated content" link that opens
it, and its items are readable rather than unreachable. Use it for material that has been
superseded but should still be findable by anyone who goes looking.

What this does NOT change:

• hidden on its own still means unreachable. Nothing is revealed by default. A
  hidden section without the flag behaves exactly as it always has, which is what makes
  it safe for staging and review. Setting the flag is a deliberate editorial act.
• Admin-only VIEWS win outright. A flagged section inside a hidden view is not
  revealed. A hidden view is a workspace; retirement is a per-section decision.
• Archived and draft ITEMS stay invisible everywhere, including inside a revealed
  section. Archiving an item still removes it from the public site.

Set it like any other section field:

curl -sS -X PATCH \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"reveal_as_outdated": true}' \
  "$BASE_URL/admin/api/views/$VIEW_ID/sections/$SECTION_ID"

The catalog regenerates automatically on that write, so the reveal takes effect
immediately — no separate rebuild is needed. (A rebuild is only for the deploy-changed-the-
shape case described above.)

To read a revealed section through the API you must pass ?includeOutdated=true; without
it the section 404s. Its items' metadata, body, download and thumbnail routes resolve
normally and report "outdated": true.

Admin-only views and the staging workflow

A view can be marked hidden ("hidden": true on the view document). A hidden view,
and every section and item inside it, is suppressed from the entire public surface: it is
absent from GET /api/views, GET /api/views/:viewId returns 404, its item / body /
download routes return 404, it contributes nothing to keyword or semantic search, and it
never appears in the sitemap. Admin endpoints are unaffected — you see and manage it in
full. Suppression does not depend on who is asking: it is unconditional for every
unauthenticated caller.

The intended use is a staging view that holds proposed content for a human to review
before it goes live:

# 1. Create the staging view (it must NOT be the site's only view — the first
#    view registered becomes `default_view_id`, which can never be hidden).
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"version":1,"id":"staging","title":"Staging","hidden":true,
       "source":{"backend":"azure-blob","root":"content/staging"},
       "sections":[],"status":"published"}' \
  "$BASE_URL/admin/api/views"

# 2. Upload proposed items into it as usual (multipart create). Nothing you put
#    here is publicly reachable.

# 3. A human reviews them at /admin/preview/staging in a browser, or you read a
#    body back yourself:
curl -sS -H "Authorization: Bearer $TOKEN" \
  "$BASE_URL/admin/api/views/staging/sections/inbox/items/my-slug/body"

# 4. On approval, PROMOTE the item into a public view — pass `targetViewId`:
curl -sS -X POST -H "Authorization: Bearer $TOKEN" -H 'Content-Type: application/json' \
  -d '{"targetViewId":"agentnews","targetSectionId":"ai-news"}' \
  "$BASE_URL/admin/api/views/staging/sections/inbox/items/my-slug/move"

Notes on the move endpoint:

• Omit targetViewId for a move between sections of the same view (the original behaviour).
• The move relocates the content; it does not change the item's status. If the item
  is still draft, publish it separately with a PATCH.
• 404 means the target view or the target section does not exist; 409 means an item
  with that slug already exists at the destination (slugs are unique per section — resolve
  it by choosing a different slug, never by deleting the existing item).
• Both views' catalogs are regenerated automatically.

Do not hide the site's default view — the request is rejected with 400, because the
public home page renders it.

6. What you can NOT do — token management is human-only

The token-management endpoints reject every agent token with 403, regardless of scope:

• GET /admin/api/agents (list credentials)
• POST /admin/api/agents (issue a credential)
• POST /admin/api/agents/:agentId/revoke (revoke a credential)

This is deliberate and permanent: agents cannot mint, enumerate, or revoke agent
credentials. Issuance belongs to the human administrator. Do not attempt these calls
except at most once during handoff verification to confirm the 403 boundary; repeated
attempts will be treated as misbehavior.

You also cannot manage human admin accounts or sessions — /admin/api/auth/* is for
human sign-in flows only.

7. Error semantics — what each status means for you

Every URL under /api/ and /admin/api/ answers JSON, always. A mistyped API path returns a
404 envelope, never an HTML page and never a redirect to the sign-in form — so a client that
follows redirects can no longer mistake a typo for a login prompt. If an API request appears to
return HTML, you are not talking to this API.

No API request should ever hang. If one does not respond within a few seconds, that is a fault
worth reporting with the exact URL — not something to wait out or retry in a loop.

8. Token lifecycle — expiry and revocation

• Your token MAY have an expiration date. You cannot query it (the credential listing
  is human-only): treat any 401 as the end of your credential's life, whatever the
  cause.
• Revocation is immediate: the administrator can revoke your token at any moment, and
  your next request will get 401.
• On 401: stop, report, wait. Never attempt to work around a dead credential —
  do not probe other endpoints, do not guess tokens, do not fall back to public
  endpoints to simulate writes.
• Expect rotation: your operator may hand you a replacement token and revoke the old
  one at any time. Always use the most recently issued token; discard superseded ones
  from your secret store.

9. Handoff checklist (run once when you receive a token)

1. GET $BASE_URL/admin/api/views with the Authorization header → expect 200.
   Your credential works.
2. GET $BASE_URL/api/views without any header → expect 200. The public surface is
   reachable.
3. Optionally GET $BASE_URL/admin/api/agents with the header → expect 403.
   Confirms the human-only boundary; do not repeat it.
4. Store the token in your secret manager, delete it from anywhere else it transited,
   and begin your instructed duties.

How to retrieve these instructions

This document is published by the site itself, so any agent can (re-)obtain it at any
time without authentication:

• Machine-readable (recommended for agents): GET $BASE_URL/instructions-to-agents.md
  returns this exact document as plain markdown (text/markdown), with no site chrome.

  curl -sS "$BASE_URL/instructions-to-agents.md"
  

• Human-readable: GET $BASE_URL/instructions-to-agents serves the same content as
  a styled web page.

If you are an agent and were given only the site's base URL, fetch the markdown
endpoint above and follow this document from the top. Re-fetch it at the start of each
work session — the API surface and the rules in this document may evolve, and the
published version is always authoritative.