HTTP API

The any server listens on 127.0.0.1:7001 and exposes one JSON API under /v1/. Endpoints map onto one SDK call each — the consumer-side features built next to the SDK (search, links and backlinks, the event bus, processes, the local store) are marked — reads always go through /query, and every dataset 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 raw routes: file attach and content carry file bytes, local-store export returns application/gzip and import takes that file as its body, and every …/subscribe answers text/event-stream.
• 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 favorites/v1 becomes favorites%2Fv1).
• Body limit 1 MB on every route except file attach and local-store import, whose raw bodies stream past it.
• 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.
• Tech space: GET /v1/account returns its id as techSpaceId. It is a valid :spaceId for bundles, for types, collections and records on bundle roots, and for the space read, sync-status, debug and sync routes; every other space-scoped route there answers 405 space.unsupported.

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, index without mnemonic, replace without a credential, accountId on a managed server), 403 control.forbidden, 403 auth.not_managed, 404 auth.account_not_found, 409 auth.account_in_use, 409 auth.account_mismatch, 409 auth.mnemonic_mismatch, 409 auth.already_authorized, 409 auth.network_mismatch, 400 auth.passkey_required, 409 sdk.crdt_version_newer, 500 auth.device_key_corrupt, 500 auth.network_pin_corrupt. Details and the decision table: Accounts.

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":"notes/v1","name":"Notes","xKey":"notes","hidden":true,"parts":[{"key":"body","datasets":[{"module":"editor","shared":true}]}]}'

Full semantics in Bundles.

Catalog

wiki is the usecase that gives a space its tree — a collection pages are filed under (Objects).

Objects

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

Every objects row carries derived author, createdAt, spaceId, modifiedAt, modifiedBy (instants as {"$date": …}; modifiedBy is the identity that signed the change modifiedAt names). See Objects and System fields.

Links and backlinks

Reads over the link index the search indexer maintains — not SDK methods. All answer 409 index.disabled when the index is off and reflect a write after the indexer's debounce.

Link = {source: {spaceId, objectId, dataset, recordId, typeId?}, kind, target: {uri, kind, spaceId, objectId?, dataset?, recordId?, propId?, identity?, fileId?}}; kind is mention, link, card, embed or relation. A change publishes a device-scope links.updated event naming the moved targets. See Links.

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,
  "projection": {"text": 1, "creator": 1} }

projection (dotted paths → 1 include / -1 exclude; id always ships, _ver narrows to match) shapes snapshot rows and every record in changes frames. includeDeleted: true (snapshot …/query only) returns record tombstones next to live rows. 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, collections 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"}'
curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/collections -d '{"name":"Reading list","xKey":"reading_list"}'
curl -X POST http://127.0.0.1:7001/v1/spaces/$SP/properties/$OBJ/collections/$C

Values are keyed by propId, never xKey. See Types and properties, Collections 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; an ACL operation the caller's role does not allow is 403 acl.forbidden, one naming an unknown request record 404 acl.record_not_found. 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.

Local store

Device-local, non-CRDT collections that never sync — query, modifiers, indexes and aggregation for scratch sets, ingest staging and per-device caches. Not an SDK dataset: no type, no _ver, no subscribe, not search-indexed, and a space-scoped collection outlives its space. Every route answers 409 local.disabled when local.enabled is false.

coll is {scope: "account" | "space", spaceId?, name}, name matching ^[a-z0-9][a-z0-9_-]{0,63}$ (400 local.bad_name). An op on a local storage collection never ensured is 404 local.collection_not_found; a space-scoped write (ensure, insert, upsert, update, indexes, a pipeline's sink target) answers 404 space.not_found / 409 space.deleted for its space, while reads, delete, drop, list, export and import never check the space.

Export and import local collections

Export is a manual copy of selected local collections, including their scope, space ID, names, indexes and documents. It does not export the account's CRDT data or file bytes. The file is a gzip-compressed anyenc value stream, with a manifest followed by each collection's documents; use .anyenc.gz as its extension. An empty selection or missing named collection returns 404 local.collection_not_found before the file response starts.

With the account-scoped scratch collection the CLI example creates, export it and import the same file back; DEST pointed at another authorized server copies it there:

SOURCE=http://127.0.0.1:7001
DEST=http://127.0.0.1:7001
curl --fail --get "$SOURCE/v1/local/export" \
  --data-urlencode 'scope=account' --data-urlencode 'names=scratch' \
  --output scratch.anyenc.gz &&
curl --fail -X POST "$DEST/v1/local/import" \
  -H 'Content-Type: application/gzip' --data-binary @scratch.anyenc.gz

The import response lists the resulting collections. For space-scoped traces, export with scope=space, spaceId=<sourceSpaceId> and names=trace_runs,trace_records,trace_blobs; the destination does not need that space to read the imported records.

Import overlays existing collections: matching IDs are replaced, new IDs are inserted, and documents absent from the file remain. Indexes are ensured; a same-name index with a different definition is 400 local.bad_index. Re-importing an unchanged file leaves the same stored data. Import commits in chunks of 256 documents, so a failure can leave earlier collections and chunks committed. Invalid gzip, format/version, document sections or storage names return 400 local.bad_export; details.imported is the number of fully completed collections, not a rollback guarantee.

Note. Synced writes are not idempotent — each POST produces a new DAG change. The exceptions are /upsert, where the caller-supplied record id is the idempotency key, and the adopt-or-install routes (…/bundles, /v1/catalog/:usecaseId/setup), where a second call adopts. Pagination is offset-based on every list.