skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
developers.anytype.io49 installs

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-api
view source ↗

Is 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/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

IntentCall
find objectsPOST …/{space_id}/search (or POST /v2/search across spaces — rows then carry space_id). Search with filters; don't enumerate GET …/objects
read one objectGET …/objects/{id} — start with ?outline=true
change property valuesPATCH op set_properties — add/remove for list values, set for scalars
complete a task objectset_properties ("set":{"done":true} or the status option) — a property, not a block edit
change a word/phraseop replace_text {find, replace} — id optional; never retype the block
toggle a checkbox blockop update_block {"match":"Draft timeline","set":{"checked":true}} — merge; text untouched. match or id, never both
add contentop insert_blocks with a markdown payload — write markdown, the server parses it
restructureops move_block / replace_subtree / delete_block (delete_block takes match too)
one table cellop set_cell — never rewrite the table
show/hide a view column, edit a viewop 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 viewops insert_view (copy_from duplicates one) · move_view (position:"first" = default tab) · delete_view
create an objectPOST …/objects — shortcut {type, name, properties, markdown} covers most cases
delete an object you createdDELETE …/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 collectionPATCH ops add_items / remove_items on the collection object
read a query / collectionGET …/queries/{id}/objects · …/collections/{id}/objects (?view=, ?fields=)
new type / propertyPOST …/types · POST …/properties; select options ride the property, or ?create_missing_options=true mints them from values
upload a filePOST …/files (multipart or {"url":…}) → the id file blocks and chat attachments need
download a file or iconGET …/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.
chatGET/POST …/chats/{id}/messages, POST …/read — see Chats
put an object in the sidebarPOST …/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 objectPOST …/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, 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 object_id="…">); ≤8000 UTF-16 units; 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; 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}/discussion mints one (201, created: true) or returns the existing id (200). Use that id as the chat id on every route above; reply_to makes 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 as text. Discussions are not in GET …/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.
  • 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, 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; document is the full format, what POST /v2/validate checks. 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).

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>