Anytype

Anytype Skill

Binary: anytype (install via https://github.com/anyproto/anytype-cli) API base: http://127.0.0.1:31012 Auth: Authorization: Bearer <ANYTYPE_API_KEY> (key stored in .env as ANYTYPE_API_KEY) API docs: https://developers.anytype.io

Instance config: Space IDs, tag IDs, collection IDs, and sharing links are in SETUP.md (same directory). Read that alongside this file.

Check Status First

anytype auth status     # is an account set up?
anytype space list      # is the service running + spaces joined?

If either fails → follow Setup below. Otherwise skip to API Usage.

Setup (one-time)

# 1. Create a dedicated bot account (generates a key, NOT mnemonic-based)
anytype auth create my-bot

# 2. Install and start as a user service
anytype service install
anytype service start

# 3. Have the space owner send an invite link from Anytype desktop, then join
anytype space join <invite-link>

# 4. Create an API key
anytype auth apikey create my-key

# 5. Store the key
echo "ANYTYPE_API_KEY=<key>" >> ~/.openclaw/workspace/.env

API Usage

Load the API key (reads only ANYTYPE_API_KEY from env or .env):

import os, requests

def load_api_key():
    if "ANYTYPE_API_KEY" in os.environ:
        return os.environ["ANYTYPE_API_KEY"]
    env_path = os.path.expanduser("~/.openclaw/workspace/.env")
    if os.path.exists(env_path):
        for line in open(env_path):
            if line.strip().startswith("ANYTYPE_API_KEY="):
                return line.strip().split("=", 1)[1]
    return ""

API_KEY = load_api_key()
BASE = 'http://127.0.0.1:31012'
HEADERS = {'Authorization': f'Bearer {API_KEY}', 'Content-Type': 'application/json'}

See references/api.md for all endpoints and request shapes.

Common Patterns

List spaces:

GET /v1/spaces

Search objects globally:

POST /v1/search
{"query": "meeting notes", "limit": 10}

List objects in a space:

GET /v1/spaces/{space_id}/objects?limit=50

Create an object:

POST /v1/spaces/{space_id}/objects
{"type_key": "page", "name": "My Page", "body": "Markdown content here"}

Update an object (patch body/properties):

PATCH /v1/spaces/{space_id}/objects/{object_id}
{"markdown": "Updated content"}

⚠️ Create uses body, Update uses markdown — different field names for the same content. Easy to mix up.

⚠️ CRITICAL: PATCH does NOT update the body/content field. Sending body or markdown in a PATCH silently succeeds (HTTP 200) but the content is NOT updated in Anytype. Only metadata fields like name are updated via PATCH.

The only reliable way to update an object's content is: DELETE + recreate.

⚠️ This is destructive. Always save the old content before deleting:

# Step 0: fetch and save existing content before deleting
old = requests.get(f"{BASE}/v1/spaces/{space_id}/objects/{old_id}", headers=headers).json()
old_content = old.get("object", {}).get("snippet", "")  # keep a local copy

# Step 1: delete old object (irreversible via API — confirm before running)
requests.delete(f"{BASE}/v1/spaces/{space_id}/objects/{old_id}", headers=headers)

# Step 2: create new object with full updated content
resp = requests.post(f"{BASE}/v1/spaces/{space_id}/objects",
    json={"name": name, "type_key": "page", "body": new_content},
    headers=headers)
new_id = resp.json()["object"]["id"]

Store the new object ID — callers must update any references (e.g. related_pages) after recreation. Deleted objects may be recoverable from the Anytype bin in the desktop app.

Use scripts/anytype_api.py as a ready-made helper for making API calls.

Key Constraints (learned from testing)

• links property is read-only — system-managed, populated only by the desktop editor. API returns 400 if you try to set it.
• Collections cannot have an icon set on create — causes a 500. Create without icon, add it after.
• body vs markdown — create uses body, update uses markdown.
• PATCH cannot update content — body/markdown fields in PATCH are silently ignored. HTTP 200 is returned but content is unchanged. To update content: DELETE + recreate.
• related_pages custom property (key: related_pages, format: objects) — writable via API for linking objects. Must be created in the space first if it doesn't exist.

Object Type Preference

Default to page for all content. Notes (note type) are the exception — use only when content is informal/scratchpad and doesn't need linking into the knowledge graph.

Everything meaningful (call notes, research, hub pages, product docs, meeting summaries) → type_key: "page".

Knowledge Graph Principles — Apply These Always

Anytype is a linked knowledge base, not a flat file store. Every time you create or update content, ask: how does this connect to what already exists?

1. Link Everything

• Use [[Page Name]] style inline links in the markdown body to reference related objects.
• When creating a new page, search for related existing pages first and link back to them.
• When updating an existing page, add links to any newly created pages that are related.

2. Collections as Cluster Containers

• For any topic cluster, create a Collection (type_key: collection) — not a plain page hub.
• Collections are Anytype's native container type. They appear in the sidebar, support multiple views (grid, list, kanban), and are queryable.
• Use the Lists API to add child objects to a collection.
• Also maintain a hub page inside the collection as the written overview (description + links).

Create + populate a collection:

# 1. Create (no icon on create — causes 500)
col = api('POST', f'/v1/spaces/{SPACE}/objects', {'type_key': 'collection', 'name': 'My Cluster'})
col_id = col['object']['id']

# 2. Add objects
api('POST', f'/v1/spaces/{SPACE}/lists/{col_id}/objects', {'objects': [id1, id2, id3]})

Sidebar note: Sidebar pinning is manual only — no API. Ask the user to pin collections in the Anytype desktop app.

3. Bidirectional Awareness

• Anytype shows backlinks automatically, but you must write forward links in the body.
• After creating content, update the hub page to include a link to the new object.

4. Before Creating a Page

1. Search: POST /v1/spaces/{space_id}/search {"query": "<topic>", "limit": 10}
2. Check if a page already exists — update it rather than duplicate
3. Identify the parent hub page(s) this belongs to
4. Create the page with inline links to related pages in the body
5. Update the hub page(s) to add a link to the new page

5. Hub Page Template

When creating a hub page, use this structure:

## Overview
<2-3 sentence summary>

## Pages
- [Child Page Name](anytype://object?objectId=<id>&spaceId=<space_id>) — one-line description
- [Another Page](anytype://object?objectId=<id>&spaceId=<space_id>) — one-line description

## Key Facts
- Fact 1
- Fact 2

6. Native Object Links (Anytype Graph Feature)

Anytype has two link mechanisms. Use both:

A. System links property (read-only via API)

The built-in links property is auto-populated by the Anytype desktop app when you use @mention or [[]] syntax in the rich text editor. The API cannot set it directly — attempting to do so returns 400.

B. Custom related_pages property (writable via API) ✅

Create a custom objects-type property called related_pages (key: related_pages) in your space. This shows up in each object's sidebar and lets the API express object relationships.

// On create:
{
  "type_key": "page",
  "name": "My Page",
  "body": "...",
  "properties": [
    {"key": "related_pages", "objects": ["<hub_id>", "<sibling_id>"]}
  ]
}

Rule: Hub pages → related_pages set to all children. Child pages → related_pages set back to their hub. This creates visible edges in the graph view.

7. Inline Links Syntax

Use anytype:// deep links — NOT object.any.coop URLs — for links inside the app.

object.any.coop URLs in body text render as plain text and are NOT clickable inside Anytype. The only format that renders as a clickable internal link is:

[Link Text](anytype://object?objectId=<object_id>&spaceId=<space_id>)

Helper function:

def anytype_link(name, obj_id, space_id):
    return f"[→ Open: {name}](anytype://object?objectId={obj_id}&spaceId={space_id})"

⚠️ Do NOT put links inside markdown headings — Anytype strips the link and renders only plain text. Links only work as inline body text.

Use object.any.coop links only when sharing with external users (outside the Anytype app).

8. Tags

Tags require pre-existing tag option IDs in the space — you cannot pass free-text strings directly.

Create a new tag:

POST /v1/spaces/{space_id}/properties/{tag_property_id}/tags
{"name": "my-tag", "color": "blue"}
→ returns tag.id — use that ID in multi_select

Set tags on an object:

PATCH /v1/spaces/{space_id}/objects/{object_id}
{
  "properties": [
    {"key": "tag", "multi_select": ["<tag_id_1>", "<tag_id_2>"]}
  ]
}

See SETUP.md for the tag property ID and all defined tag IDs for this instance.

9. Proactive Organization Checklist

After any write operation, run through:

• Does a hub page exist for this topic? If not, create one.
• Did I link the new/updated page from the hub?
• Did I link related pages from within the new content?
• Are there orphan pages (no incoming links) I should connect?
• Did I set tag (project + content type + domain) on the new page?
• Did I set related_pages pointing to the hub?

Sharing Links

Use the public web link format when sharing externally:

https://object.any.coop/{object_id}?spaceId={space_id}&inviteId={invite_id}#{hash}

The inviteId and #hash are space-level constants. Only object_id changes per object.

See SETUP.md for this instance's spaceId, inviteId, and hash.