anytype-api
Call Anytype's local HTTP API v2 directly — search, read, create and edit objects, queries, collections and chats over REST. Use when writing scripts, SDK code or curl against the API. For interactive note/task work prefer the `anytype` CLI and its skill (cmd/anytype/SKILL.md); this guide is the raw-HTTP layer beneath it.
How do I install this agent skill?
npx skills add https://developers.anytype.io --skill anytype-apiIs this agent skill safe to install?
No partner audit is available yet. Read the source before installing.
What does this agent skill do?
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/spaceslists them. - An object =
properties(typed key-values) +blocks(document content).typeis 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 …/propertiesspells them that way, and served documents spell them that way by default;?keys=nameon 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 nameDue dateand 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 compactfilterSTRING 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 againstGET …/properties/{key}/options, or resend with?create_missing_options=trueto 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) — nochildrenkey. Inline formatting is markdown insidetext. 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 viaadd_items/remove_items). Chats store messages outside blocks, paged by order-id cursors.
Which operation
| Intent | Call |
|---|---|
| find objects | POST …/{space_id}/search (or POST /v2/search across spaces — rows then carry space_id). Search with filters; don't enumerate GET …/objects |
| read one object | GET …/objects/{id} — start with ?outline=true |
| change property values | PATCH op set_properties — add/remove for list values, set for scalars |
| complete a task object | set_properties ("set":{"done":true} or the status option) — a property, not a block edit |
| change a word/phrase | op replace_text {find, replace} — id optional; never retype the block |
| toggle a checkbox block | op update_block {"match":"Draft timeline","set":{"checked":true}} — merge; text untouched. match or id, never both |
| add content | op insert_blocks with a markdown payload — write markdown, the server parses it |
| restructure | ops move_block / replace_subtree / delete_block (delete_block takes match too) |
| one table cell | op set_cell — never rewrite the table |
| show/hide a view column, edit a view | op update_view — works on queries, collections and a type's default view (PATCH the type OBJECT id from GET …/types/{key}) |
| add / reorder / remove a view | ops insert_view (copy_from duplicates one) · move_view (position:"first" = default tab) · delete_view |
| create an object | POST …/objects — shortcut {type, name, properties, markdown} covers most cases |
| delete an object you created | DELETE …/objects/{id} — archives (Bin, reversible in the app). Only works on objects THIS key created after provenance shipped; anything else → 403 not_created_by_this_key, permanently — don't retry, archive in the app instead. Ownership is matched on the app name EXACTLY (byte-for-byte — re-pair under the identical name to keep delete rights). User content only: system objects 403. Probe first with ?dry_run=true |
| curate a collection | PATCH ops add_items / remove_items on the collection object |
| read a query / collection | GET …/queries/{id}/objects · …/collections/{id}/objects (?view=, ?fields=) |
| new type / property | POST …/types · POST …/properties; select options ride the property, or ?create_missing_options=true mints them from values |
| upload a file | POST …/files (multipart or {"url":…}) → the id file blocks and chat attachments need |
| download a file or icon | GET …/files/{file_id}/content; use a file id or a space/member's icon_image. Optional ?width= selects an image size. Supports ranges, conditional reads, and HEAD. |
| chat | GET/POST …/chats/{id}/messages, POST …/read — see Chats |
| put an object in the sidebar | POST …/widgets {target, scope} — scope:"personal" is this account's own sidebar (any writer); scope:"space" is the shared one (owner/admin; not offered in one-to-one spaces). GET …/widgets lists both; PATCH/DELETE …/widgets/{id-or-target} change or remove one. Not is_favorite |
| comment on an object | POST …/objects/{id}/discussion → {id}, then the chat routes with that id — see Chats |
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, andupdate_block/delete_blocktakematchfor the same job (one match, or a refusal listing the candidates). ?include=propertiesor?include=blocksreads half the object.?format=mdis 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=fullis 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 withfields=(property keys) instead of GETting each object. - Every object read returns an
etag(envelope +ETagheader).
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 ofset/unset/add/remove.add/removeare per-entry list edits (select/multiSelect/objects/files) — appending one tag never rewrites the array.removenever creates the option it names.set: {"k": []}= present-but-empty;unsetremoves presence.update_blockis THE block-field op (merge; explicitnullclears a field) — checkbox, color, language, retype, or full text rewrite.matchaddresses the block by its TEXT onupdate_blockanddelete_block— theidalternative: 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 —matchnames a block, not an occurrence. It reads the document as the ops before it in the batch left it.replace_text:idis optional — omitted,findlocates 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 blockfindmust match exactly once ("found 2 matches — provide more context");replace_all: trueis the escape, within that one block only. Preferred overupdate_blockfor word-level edits.replace_subtree {id, blocks}swaps a block plus descendants.insert_blocks:blocks(flat array) ormarkdown— mutually exclusive, same targeting. Target with one ofafter/before/inside(+position: first|lastinside that container); omit all three andpositionpicks an end of the DOCUMENT —last(or absent) appends,firstinserts at the start, both on an empty object too. Payloadindent: 0= the anchor's level (after/before) or the container's child level (inside).move_blocktargets 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
idnames an EXISTING block, soinsert_blockstakes none anywhere in its payload (rows and columns included); the server mints them and returns them increated_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 inupdate_block set.rows, a block inside aset_cellarray), so you never have to re-read to learn an id you just created. update_viewedits ONE dataview view — never resend the views array.block/vieware optional when the object has one dataview and it one view (types, queries, collections usually do).setmerges view fields (name,type,groupBy,sorts,filters— arrays replace whole;filtertakes the compact string; null clears a field);columnsmerges per property key:{"hidden": false}shows a column,nullremoves it, a new key appends one. Works on Blocks-restricted objects — view config is not a block edit.insert_view/move_view/delete_viewcomplete the family (same addressing, same channels; insert_view's name is its own required field — not inset). insert_view needs onlyname— bare default: every listed property visible, newest first;copy_fromduplicates a view (thenset/columnsoverride); the minted id returns increated_views, keyedops[i]. move_view REQUIRES one ofafter/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 batchingdelete_blocks with the newinsert_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
filterstring (≤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
filtersarray: 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).filterandfilterstogether → 400ambiguous_input. typeis 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 > 5alone matches nothing; composetype = "image" AND size > 5.mimeTypeandsizework in fields/filters/sorts.- An unguarded
due_date < …also matches objects with no date — the response warns; addAND due_date IS NOT EMPTYunless intended. - Full-text
totalis a lower bound whilehas_moreis true — walk pages, don't plan on the number. - Sorts: any property key,
{"property", "direction": "asc|desc"}; default islast_modified_date desc.
Chats
GET …/chats/{id}/messagesreturns{messages, state, message_count, has_more, next_before?, next_after?}.statecarriesunread_messages,unread_mentions,last_state_id— so "anything new?" is a?limit=1read. Cursors only (?after=walks forward; otherwise newest-first vianext_before);?offset=is rejected.- Message
textis inline markup both ways (mentions as<mention object_id="…">); ≤8000 UTF-16 units;attachments= up to 32 object ids fromPOST …/files.?reactions=fulladds who reacted. - Mark read:
POST …/chats/{id}/readwith{"up_to": <order>, "last_state_id": <id>}— both from the same GET, else nothing marks. PATCH …/messages/{id}{"text"}edits text only (attachments kept; in a discussion the text replaces the message's blocks, with a warning naming dropped quotes/links); 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.
- An object's discussion (its comment thread) is a chat. An object read
carries
discussion: "<id>"when one exists;POST …/objects/{id}/discussionmints one (201,created: true) or returns the existing id (200). Use that id as the chat id on every route above;reply_tomakes a threaded reply. Same message body; a discussion stores the text as one paragraph block per line (blank lines dropped, a---line is a divider) and reads it back astext. Discussions are not inGET …/chats.
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. warningson 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 answersIdempotency-Replayed: true. The same key with a different body/path/query → 409idempotency_conflict.?dry_run=trueon any mutation: full validation, identical verdicts, nothing committed (response echoesdry_run: true).?create_missing_options=trueon 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.createdon 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 → 409etag_mismatchcarrying the current etag. Omit it by default — sync also moves the etag, so habitual If-Match 409s on noise.POST /v2/validatepre-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,type_document,template,document,property,query,collection,file,search,space,filters,chat,chatMessage,chatMessageEdit,chatReaction,chatRead). The three document kinds are narrowed to what their endpoint accepts;documentis the full format, whatPOST /v2/validatechecks. Thefilterskind also serves the filter-string grammar (EBNF + examples).GET /v2/schemas/ops/{op}— per-op schema + example.
- worked example per request kind (
- Live vocabulary:
GET …/typesandGET …/types/{key}(the type document, incl. its property keys);GET …/properties;GET …/properties/{key}/options?prefix=(check before writing select values);GET …/membersand…/members/me(participant ids forassignee/creator;/meis your own). - Full reference:
GET /v2/docs/openapi.json(or.yaml).
Mistakes that actually happen
- RFC 3339 dates in the structured
filtersarray (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
…/optionsfirst. - Reusing one
Idempotency-Keyacross different requests → 409. Keys are per logical mutation, not per session. replace_text/edittext 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=trueis 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}/contentand 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=1instead. GET …/types/{key}/schemais a 501 stub — compose fromGET …/types/{key}+…/properties/{key}/options.- No option rename/recolor/delete under /v2 (v1 tags admin, Phase 8).
How can the creator link this skill?
Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.
<a href="https://skillzs.dev/skills/developers.anytype.io/anytype-api">View anytype-api on skillZs</a>