anyproto/anytype-api/agent-skill

Anytype API v2 — HTTP guide for agents

Local REST API at http://127.0.0.1:31009 (the Anytype app must be running). Every call sends Authorization: Bearer <key>; keys are created in the app (Settings → API keys) — the API mints none. Bodies are compact JSON, and every name this API owns is snake_case — params, fields and op names alike. (Inside an object's blocks and properties you are reading the AnyBlock format's content; property and type keys there are served as slugs by default, as display names under ?keys=name — see the properties bullet below.) Every list takes ?offset=&limit= (default 25, max 1000) and returns {data, total, offset, limit, has_more}.

First call: `GET /v2/auth/whoami`. A key may be scoped to particular spaces and to read-only. grant.scoped: false means the whole account; otherwise grant.spaces lists what you may touch and grant.permission whether you may write. Ask this instead of discovering limits through 403s (space_not_granted / write_not_granted — the message names the grant).

The data model in six ideas

• Spaces contain everything; nearly every route is

/v2/spaces/{space_id}/…. GET /v2/spaces lists them.

• An object = properties (typed key-values) + blocks (document

content). type is served as a type key (page, task) — never an id; on input a type NAME ("Meeting note") resolves too.

• Properties are addressed by key — a snake_case slug minted once at

creation and frozen, so it survives renames (due_date, icon_emoji, manual_property). GET …/properties spells them that way, and served documents spell them that way by default; ?keys=name on a read serves the display-name vocabulary instead ("Due date") — pick slugs for anything long-lived, names for showing a user their own words. Input is forgiving everywhere and accepts BOTH: dueDate, DueDate, due-date, the display name Due date and even Дата выполнения all resolve to the one property they name; an input matching two properties is a 400 listing both, and an unknown one never silently creates anything. (One exception: the compact filter STRING validates before folding — spell a multi-word name with underscores there, Due_date.) Select/multi_select values are option names ("In progress", case-sensitive) — never option ids. A name the property does not already hold is refused — check it against GET …/properties/{key}/options, or resend with `?create_missing_options=true` to create it (a PATCH caps that at 64). Unknown property keys are rejected with a did-you-mean.

• Blocks are a FLAT array in pre-order with an integer indent

(absent = 0) — no children key. Inline formatting is markdown inside text. Use block ids exactly as a read served them.

• Title and description are not blocks — they live in properties

(name, description). A fresh object has zero blocks.

• A query is a live query over a type (its type key is still set, the

name it carries internally); a collection is a hand-curated list (edited via add_items/remove_items). Chats store messages outside blocks, paged by order-id cursors.

Which operation

Read cheaply

• GET …/objects/{id}?outline=true → every block's {indent, id, type}

plus its text truncated to 80 runes — structure + addressable ids at a fraction of the tokens. Follow up with ?block={id} for one subtree, or PATCH directly: editing needs no prior full read once you know the ids (but copy exact text from a full read — outline text may be cut).

• When the request already quotes the text to change, skip the read

entirely: replace_text {find, replace} locates the block itself, and update_block/delete_block take match for the same job (one match, or a refusal listing the candidates).

• ?include=properties or ?include=blocks reads half the object.

?format=md is a read-only markdown rendering.

• Echo block ids back exactly as a read served them; if one is rejected as

unknown, re-read and use the fresh ids. ?ids=full is the backup/export shape — the read to archive or clone from, not needed for editing.

• List/search rows are minimal {id, name, type}; add columns with

fields= (property keys) instead of GETting each object.

• Every object read returns an etag (envelope + ETag header).

Edit: PATCH ops

PATCH …/objects/{id} body {"ops":[…]} — one atomic batch (≤512 ops, ≤256 blocks per op): any invalid op rejects the whole PATCH with ops[i]-addressed issues. Fourteen ops:

{ "ops": [
  { "op": "set_properties", "set": {"status": ["Done"]}, "unset": ["oldKey"],
    "add": {"tags": ["urgent"]}, "remove": {"assignee": ["bafy…"]} },
  { "op": "update_block",  "match": "Draft timeline", "set": {"checked": true} },
  { "op": "replace_text",  "find": "Q3 report", "replace": "Q4 report" },
  { "op": "insert_blocks", "after": "b3", "markdown": "## Notes\n- first\n- second" },
  { "op": "move_block",    "id": "b9", "inside": "b2", "position": "last" },
  { "op": "delete_block",  "id": "b4", "recursive": true },
  { "op": "set_cell",      "table_id": "t1", "row": "r2", "col": "c1", "value": "done" },
  { "op": "update_view",   "columns": {"status": {"hidden": false}} },
  { "op": "insert_view",   "name": "Board", "copy_from": "viewAll1",
    "set": {"type": "kanban", "groupBy": "status"} }
] }