Anytype API

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"} }
] }

• set_properties: a key appears in at most one of set/unset/add/remove. add/remove are per-entry list edits (select/multiSelect/objects/files) — appending one tag never rewrites the array. remove never creates the option it names. set: {"k": []} = present-but-empty; unset removes presence.
• update_block is THE block-field op (merge; explicit null clears a field) — checkbox, color, language, retype, or full text rewrite.
• match addresses the block by its TEXT on update_block and delete_block — the id alternative: give one or the other, never both (and never neither). The text must appear in exactly ONE block or the op refuses: zero → read the outline, several → the error lists candidate ids to retry with. Repeats inside the one matched block are fine — match names a block, not an occurrence. It reads the document as the ops before it in the batch left it.
• replace_text: id is optional — omitted, find locates the block and must appear in exactly ONE block (zero or several matching blocks refuse; the ambiguity error lists candidate ids to retry with). Within the matched block find must match exactly once ("found 2 matches — provide more context"); replace_all: true is the escape, within that one block only. Preferred over update_block for word-level edits. replace_subtree {id, blocks} swaps a block plus descendants.
• insert_blocks: blocks (flat array) or markdown — mutually exclusive, same targeting. Target with one of after/before/inside (+position: first|last inside that container); omit all three and position picks an end of the DOCUMENT — last (or absent) appends, first inserts at the start, both on an empty object too. Payload indent: 0 = the anchor's level (after/before) or the container's child level (inside). move_block targets the same way, so {"op":"move_block","id":"b9","position":"first"} moves a block to the top of the document.
• Author new content without ids — an id names an EXISTING block, so insert_blocks takes none anywhere in its payload (rows and columns included); the server mints them and returns them in created_blocks, keyed by the payload path that produced each — ops[0].blocks[0], ops[0].blocks[0].rows[1], ops[0].blocks[0].columns[0]. The same holds wherever you leave an id out of an existing-content payload (a new row in update_block set.rows, a block inside a set_cell array), so you never have to re-read to learn an id you just created.
• update_view edits ONE dataview view — never resend the views array. block/view are optional when the object has one dataview and it one view (types, queries, collections usually do). set merges view fields (name, type, groupBy, sorts, filters — arrays replace whole; filter takes the compact string; null clears a field); columns merges per property key: {"hidden": false} shows a column, null removes it, a new key appends one. Works on Blocks-restricted objects — view config is not a block edit.
• insert_view/move_view/delete_view complete the family (same addressing, same channels; insert_view's name is its own required field — not in set). insert_view needs only name — bare default: every listed property visible, newest first; copy_from duplicates a view (then set/columns override); the minted id returns in created_views, keyed ops[i]. move_view REQUIRES one of after/before/position ("first" = default tab). delete_view refuses the last view — insert the replacement first (one atomic batch swaps a bad default view).
• Response: new etag, created_blocks (payload position → real id; nested row/column/cell slots included), created_views (same, for minted view ids), created (options minted under ?create_missing_options=true), diff_stats {blocks_added, blocks_removed, blocks_changed, blocks_moved, properties_changed}, warnings (advisory, e.g. an unguarded date filter).
• There is no whole-document replace — never read a document, regenerate it and write it back. Replace a section with replace_subtree; start over by batching delete_blocks with the new insert_blocks.

Query

POST …/search body: {query?, type?, filter?|filters?, sorts?, fields?}. Pagination is the query params — a body limit is rejected. Search is a read: no Idempotency-Key, dry_run ignored.

{ "query": "report", "type": "task",
  "filter": "done = false AND (due_date < currentWeek() OR due_date IS EMPTY)",
  "sorts": [ { "property": "due_date", "direction": "asc" } ],
  "fields": ["name", "due_date", "status"] }

• Prefer the compact filter string (≤4096 chars): status IN ("In progress", "Blocked") · name CONTAINS "report" · last_modified_date > daysAgo(7) · tags HAS ALL ("urgent", "q3") AND assignee IS NOT EMPTY. Dates are RFC 3339 or preset functions (today(), currentWeek(), daysAgo(n)). Parse errors are offset-addressed with did-you-mean.
• The structured filters array: leaf = {"property","condition","value"}, group = {"operator":"and|or","filters":[…]} (non-empty). Date values there are unix seconds, not RFC 3339 (the string form converts for you). filter and filters together → 400 ambiguous_input.
• type is also a filter pseudo-key for multi-type: type IN ("task", "bug"). File rows appear only when a file type is named in the type channel (type = "image", type IN (… "file")) — size > 5 alone matches nothing; compose type = "image" AND size > 5. mimeType and size work in fields/filters/sorts.
• An unguarded due_date < … also matches objects with no date — the response warns; add AND due_date IS NOT EMPTY unless intended.
• Full-text total is a lower bound while has_more is true — walk pages, don't plan on the number.
• Sorts: any property key, {"property", "direction": "asc|desc"}; default is last_modified_date desc.

Chats

• GET …/chats/{id}/messages returns {messages, state, message_count, has_more, next_before?, next_after?}. state carries unread_messages, unread_mentions, last_state_id — so "anything new?" is a ?limit=1 read. Cursors only (?after= walks forward; otherwise newest-first via next_before); ?offset= is rejected.
• Message text is inline markup both ways (mentions as <mention objectId="…">); ≤8000 chars; attachments = up to 32 object ids from POST …/files. ?reactions=full adds who reacted.
• Mark read: POST …/chats/{id}/read with {"up_to": <order>, "last_state_id": <id>} — both from the same GET, else nothing marks.
• PATCH …/messages/{id} {"text"} edits text only (attachments kept); editing/deleting another member's message → 403. DELETE permanently removes orphaned attachments — the response warns with their ids.
• No etag/If-Match on chats; order ids are the concurrency vocabulary.

Conventions on every call

• Errors are {status, code, message, issues:[{path, message, hint}]} — built to be repaired in ONE retry: fix the named path per the hint, resend once. Never loop blindly; 403s and validation failures do not improve with repetition.
• warnings on success responses are advisory — no retry needed.
• Idempotency-Key (all mutations incl. DELETE): mint a fresh random key per logical mutation; reuse the SAME key only to retry the identical request — a replay answers Idempotency-Replayed: true. The same key with a different body/path/query → 409 idempotency_conflict.
• ?dry_run=true on any mutation: full validation, identical verdicts, nothing committed (response echoes dry_run: true).
• ?create_missing_options=true on any write that sets a select value: consent to MINT option names the property does not hold yet. Default off, and off refuses — an unmatched name is usually a typo or a stale label, and a minted option joins the property's vocabulary for the whole space with no delete surface. created on the response lists what a consented write actually minted.
• If-Match (objects only): send an etag back verbatim when a concurrent overwrite would matter; mismatch → 409 etag_mismatch carrying the current etag. Omit it by default — sync also moves the etag, so habitual If-Match 409s on noise.
• POST /v2/validate pre-flights an AnyBlock document: 200 with {issues, warnings} even for an invalid one.

Look it up at runtime — don't guess

• GET /v2/schemas — index. GET /v2/schemas/{kind} — strict JSON Schema
  • worked example per request kind (object, shortcut, type, template, property, query, collection, file, search, space, filters, chat, chatMessage, chatMessageEdit, chatReaction, chatRead). The filters kind also serves the filter-string grammar (EBNF + examples). GET /v2/schemas/ops/{op} — per-op schema + example.
• Live vocabulary: GET …/types and GET …/types/{key} (the type document, incl. its property keys); GET …/properties; GET …/properties/{key}/options?prefix= (check before writing select values); GET …/members and …/members/me (participant ids for assignee/creator; /me is your own).
• Full reference: GET /v2/docs/openapi.json (or .yaml).

Mistakes that actually happen

• RFC 3339 dates in the structured filters array (unix seconds there — or use the filter string, which converts).
• Rewriting a whole multiSelect array to add one entry — use set_properties.add.
• Option ids, or wrong-case option names, as values — names are the identity; check …/options first.
• Reusing one Idempotency-Key across different requests → 409. Keys are per logical mutation, not per session.
• replace_text/edit text is markup SOURCE: *, [, ~~ in a replacement become real formatting — escape with \.
• Deleting a parent block without recursive: true, or moving a block into its own subtree — rejected with the reason; read the error.
• Filtering on file metadata without naming a file type — zero rows.

Not in v2 (yet)

• Object DELETE is own-output-only — DELETE …/objects/{id} archives only objects THIS key created (recorded at creation, immutably). Objects created before that shipped, in the app, by import or by other members are permanently 403 for every key — there is no "delete arbitrary objects" capability. ?dry_run=true is the cheap deletability probe; types/properties still use their own DELETE routes.
• No file content extraction ("read this PDF") in the API. Download its bytes with GET …/files/{file_id}/content and process them in the client.
• No chat SSE stream under /v2 and no per-chat message full-text search (both v1 for now); poll GET messages?limit=1 instead.
• GET …/types/{key}/schema is a 501 stub — compose from GET …/types/{key} + …/properties/{key}/options.
• No option rename/recolor/delete under /v2 (v1 tags admin, Phase 8).