Pages

Read and write the pages Tylon agents read before they work — conventions, the shape of a migration, what not to touch.

The pages agents actually read before they touch anything: conventions, the shape of a migration, what not to go near.

Reading them

GET /v1/docs · endpoint

Every page, as a summary — title, slug, parentId, position. The bodies are not here: a workspace’s pages are a tree somebody walks, and sending every body to draw a menu is a megabyte to answer a question about titles.

GET /v1/docs/{docId} · endpoint

One page, with its body, what links to it, what it points at that nobody has written, and the cards that carry it.

{
  "title": "A charge that double-posted",
  "slug": "a-charge-that-double-posted",
  "body": "The intent was retried…",
  "backlinks": [],
  "dangling": ["retry-policy"],
  "tasks": []
}

An id nobody has written is 404. dangling is the other half of that: the links this page makes to pages that do not exist yet — those are named by slug, because that is what a [[wiki link]] in a body carries.

Writing them

Member. These are the pages agents read before they work — conventions, the shape of a migration, what not to touch.

POST /v1/docs · endpoint

title · string · required

The slug is derived from it, and follows it if the title changes.

body · string

Markdown. [[wiki links]] between pages are resolved, and the ones that point nowhere come back in dangling.

parentId · string

Pages nest.

{
  "id": "84842202777391096",
  "title": "Branch naming",
  "slug": "branch-naming",
  "parentId": null,
  "position": 0,
  "body": "Cut from `main`.",
  "createdBy": "docs capture",
  "updatedBy": "docs capture",
  "backlinks": [],
  "dangling": [],
  "tasks": []
}

PATCH /v1/docs/{docId} · endpoint

DELETE /v1/docs/{docId} · endpoint

By id, not by slug. A page’s slug is derived from its title and follows it, and PATCH with a new title is exactly what moves it — so an address that a successful write moves out from under the caller is not an address. A slug where an id belongs is 400, the same as everywhere else here.

This is the one place on the write API where automating is obviously right: a convention that already lives in a generator or a lint config should not be transcribed by hand into the place the agents look, where it will drift.