Reference

HTTP API

The any server listens on 127.0.0.1:7001 and exposes one JSON API under /v1/. Every endpoint below maps onto one SDK call (the two exceptions — /search and /backlinks — are marked), reads always go through /query, and every write returns the same result shape.

Conventions

• Base path /v1/. Media type application/json; charset=utf-8 for every request with a body and every response, except the two raw file routes.
• Status codes: 200 reads, 201 creates, 204 side-effect-only endpoints. Errors always use the envelope in Errors.
• Ids in paths are URL-safe strings; segments are URL-encoded (a bundle id like general-chat/v1 becomes general-chat%2Fv1).
• Body limit 1 MB on every route except file attach.
• Strict bodies: endpoints whose OpenAPI schema carries additionalProperties: false answer 400 request.unknown_field for any unknown top-level key. GET /v1/openapi.json is the authoritative list.
• Unauthorized server: until an account is booted, every route except /v1/health, /v1/shutdown, /v1/openapi.json and /v1/auth answers 401 auth.required.

Write result

Every dataset write — /modify, /delete-records, and the chat and editor handlers — returns api.ModifyResult:

{ "versionId": "<change VersionId>", "changeId": "<changeId>",
  "recordIds": ["<id>"], "rejections": [] }

recordIds mirrors the input order (recordIds[0] is the server-derived id on a create); rejections appears only when a handler dropped an op. Writes never return the record body — read it back through /query or live through /query/subscribe (see Reading data).

Meta

curl http://127.0.0.1:7001/v1/health        # any status

Auth

Errors: 400 auth.bad_mnemonic, 400 request.invalid_field (mnemonic + accountId together, or index without mnemonic), 404 auth.account_not_found, 409 auth.account_in_use, 409 auth.mnemonic_mismatch, 409 auth.already_authorized, 400 auth.passkey_required.

curl -X POST http://127.0.0.1:7001/v1/auth -d '{}'      # any auth login

Account and identities

IdentityInfo = {identity, name?, description?, iconCid?, spaceIds}. Details: Identities.

Spaces

SpaceInfo fields worth knowing: spaceIndexObjectId, createdAt, spaceType (any.space | any.onetoone), author, ownRole (owner\|admin\|writer\|reader\|guest\|none), settings, push, derived, status.

curl -X POST http://127.0.0.1:7001/v1/spaces -d '{"name":"Notes"}'
curl -X PATCH http://127.0.0.1:7001/v1/spaces/$SP -d '{"name":"Project Phoenix"}'   # any space update $SP --name "Project Phoenix"

One-to-one and direct-add invites

Pending rows are discovered through GET /v1/spaces?status=one_to_one_pending / ?status=invite_pending. See One-to-one.

Bundles

curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/bundles \
  -d '{"id":"general-chat/v1","name":"General","rootTypes":["chat"],"derived":true}'

Full semantics in Bundles.

Objects

curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/objects \
  -d '{"types":["page"],"initialProperties":{"any":{"name":"Dune"}}}'
curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/objects/query \
  -d '{"filter":{"any.types":"page"},"sort":["-modifiedAt"],"limit":20}'

Every objects row carries derived author, createdAt, spaceId, modifiedAt (instants as {"$date": …}). See Objects and System fields.

Editor (blocks and markdown)

Reads: POST /v1/spaces/:spaceId/query with {"objectId", "dataset": "editor_blocks", "sort": ["nav.pos"]}. See Editor and Markdown import/export.

Data plane

Snapshot body (closed field set — unknown keys 400 request.unknown_field):

{ "objectId": "obj", "dataset": "chat_messages",
  "filter": {"unread": true}, "sort": ["-_ver.id"],
  "limit": 50, "offset": 0, "includeTotal": true }

Filter faults: 400 filter.unknown_operator, 400 filter.invalid. A serialized-nil objectId is 400 object.id_required. Grammar in Reading data; pipelines in Aggregation.

curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/modify -d '{
  "objectId":"'$OBJ'","dataset":"notes",
  "records":[{"id":"","upsert":true,"ops":[{"type":"$set","path":"","value":{"title":"x"}}]}]}'

Version history

A version is a changeId. Errors: 404 history.version_not_found, 404 history.truncated (reserved). chat_messages opts out of history. See Version history.

Types and properties

curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/types -d '{"name":"Book","xKey":"book"}'
curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/types/$T/properties \
  -d '{"name":"Rating","kind":"number","xKey":"rating"}'

Values are keyed by propId, never xKey. See Types and properties and Runtime datasets.

Chat

Reads: POST /v1/spaces/:spaceId/query with dataset: "chat_messages", sort: ["-_ver.id"], a limit. See Chat.

Files

curl -X POST -T photo.jpg -H 'Content-Type: image/jpeg' \
  "http://127.0.0.1:7001/v1/spaces/$SP/objects/$OBJ/files?name=photo.jpg"   # any file attach $SP $OBJ photo.jpg

See Files.

Members, invites, ACL

Permissions: none, reader, guest, writer, admin, owner. Member statuses: unknown, joining, active, removed, declined, removing, canceled. Guests writing get 403 space.read_only. See Collaboration.

Sync status and debug

See Sync status and Debugging.

Events and processes

curl -X POST http://127.0.0.1:7001/v1/events \
  -d '{"type":"ui.open_object","scope":"device","data":{"spaceId":"'$SP'","objectId":"'$OBJ'"}}'

See Event bus and Processes.

Devices and push

See Devices and Push.

Note. POSTs are not idempotent — each one produces a new DAG change. The single exception is /upsert, where the caller-supplied record id is the idempotency key. Pagination is offset-based on every list.