API

Getting Started

1. Install and start the API server

This downloads the server from npm and starts it on port 1924:

npx galaxybrain-api

To use a different port:

GB_API_PORT=3000 npx galaxybrain-api

2. Open GalaxyBrain in the browser

The app automatically connects to ws://localhost:1924 and registers itself as an instance.

3. Connect your client

const ws = new WebSocket("ws://localhost:1924");

ws.onopen = () => {
  ws.send(JSON.stringify({
    type: "command",
    requestId: "1",
    cmd: "ORIENTATION"
  }));
};

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);
  console.log(msg);
};

Architecture

The API has three moving pieces:

1. The API server — a local WebSocket server, started with npx galaxybrain-api. An HTTP GET / returns the health check string "GalaxyBrain API Server/{protocolVersion}" (e.g. "GalaxyBrain API Server/1"). The protocol version increments on breaking changes to the WebSocket command/event format.
2. GalaxyBrain browser tabs — each tab connects to the server and registers as an addressable instance.
3. External clients — your scripts, tools, or integrations connect to the same server and send commands.

External clients do not connect directly to the browser tab. Commands are routed through the server to a specific instance, and responses are routed back.

GalaxyBrain instances can be in one of three states:

Always available commands

LIST_INSTANCES, LIST_FOLDERS, OPEN_FOLDER, OPEN_DEMO, CLOSE_PROJECT, REMOVE_RECENT_FOLDER, FILES_WATCH, FILES_UNWATCH, SUBSCRIBE, UNSUBSCRIBE

Require an open project

READ_PAGES, CREATE_PAGES, UPDATE_PAGES, DELETE_PAGES, QUERY, READ_TEMPLATES, CREATE_TEMPLATES, UPDATE_TEMPLATES, DELETE_TEMPLATES, CREATE_FROM_TEMPLATE, PUSH_PAGE_ITEMS, PUSH_TEMPLATE_ITEMS, POP_PAGE_ITEMS, POP_TEMPLATE_ITEMS, READ_WORKSPACE, WRITE_WORKSPACE, MAP, ANCESTORS, ORIENTATION

App URL Parameters

gb_port

API server port to connect to. Default: 1924.

?gb_port=3000

gb_id

Instance ID the browser tab registers with. If omitted, a random 6-character ID is generated.

?gb_id=desk-main

Use a stable gb_id when you want to target a specific browser tab from a script, or run multiple tabs simultaneously. If two tabs use the same gb_id, the older one is evicted.

demo

Startup demo selection. An app convenience — API clients use OPEN_DEMO instead.

Transport

Message Format

All messages are JSON objects with a type field. Five message types on the wire:

• identify — sent by the browser app to register with the server
• command — sent by external clients to the server
• response — sent back for commands and identify
• error — server-level routing or protocol errors
• event — server-pushed subscription events

External clients only use the last four. The identify handshake is documented here because it governs instance registration and affects behavior visible to external clients.

Identify (Browser App → Server)

When a GalaxyBrain browser tab connects, it identifies itself:

{
  "type": "identify",
  "instanceId": "desk-main",
  "protocolVersion": 1,
  "state": "picker",
  "folder": null,
  "demo": null,
  "offline": false,
  "version": "0.5.0"
}

The server responds with:

{ "type": "response", "requestId": "identify", "ok": true, "serverVersion": "0.2.1" }

The serverVersion field contains the API server’s npm package version string.

Command (Client → Server)

{
  "type": "command",
  "requestId": "req-1",
  "instance": "desk-main",
  "cmd": "READ_PAGES",
  ...
}

Response (Server → Client)

{
  "type": "response",
  "requestId": "req-1",
  "cmd": "READ_PAGES",
  ...
}

Every response includes type, requestId, and cmd.

Error (Server → Client)

{
  "type": "error",
  "requestId": "req-1",
  "code": "INSTANCE_REQUIRED",
  "message": "Multiple instances connected. Specify \"instance\" field."
}

Event (Server → Client)

{
  "type": "event",
  "event": "pages_updated",
  "seq": 42,
  "instanceId": "desk-main",
  "timestamp": 1712766240
}

Instance Routing

• One instance connected: instance is optional — auto-routed.
• Multiple instances: instance is required, otherwise INSTANCE_REQUIRED.
• No instances: NO_INSTANCES error.
• Unknown instance: UNKNOWN_INSTANCE error.

Response Patterns

Commands use three distinct response shapes:

1. Singleton

Top-level ok with command-specific fields. Used by: LIST_FOLDERS, OPEN_FOLDER, OPEN_DEMO, CLOSE_PROJECT, QUERY, MAP, ANCESTORS, ORIENTATION, READ_WORKSPACE, WRITE_WORKSPACE, SUBSCRIBE, UNSUBSCRIBE, CREATE_FROM_TEMPLATE.

2. Batch

Top-level results array aligned to input order, each entry succeeds or fails independently. Used by: READ_PAGES, CREATE_PAGES, UPDATE_PAGES, DELETE_PAGES, READ_TEMPLATES, CREATE_TEMPLATES, UPDATE_TEMPLATES, DELETE_TEMPLATES, PUSH_PAGE_ITEMS, PUSH_TEMPLATE_ITEMS, POP_PAGE_ITEMS, POP_TEMPLATE_ITEMS.

3. Parse failure

When the payload is malformed before execution can begin.

Ordering and Delivery

• Commands are processed FIFO per target instance.
• Batch arrays execute in array order — later operations can observe earlier mutations from the same batch.
• For API-triggered mutations, the response is sent first, then any resulting events are flushed.

IDs, Versions & Snapshots

Data Model

Writable Schemas

These shapes are used when creating or updating pages and templates.

Page Body (Create / Full Replace)

null entries in the pages array create default blank pages.

Item Input

Unit Input

Surgical Update

UPDATE_PAGES and UPDATE_TEMPLATES support surgical block-level edits as an alternative to full replacement:

blocks (full replacement) is mutually exclusive with all surgical fields.

Serialized (Read) Schemas

Read operations return these shapes. Fields marked (read-only) are computed and must not be round-tripped back into writes.

Page

{
  "pageId": "AbcDef1234567890GhIj",
  "icon": "📄",
  "title": [ /* serialized units */ ],
  "subtitle": [ /* serialized units */ ],
  "blocks": [ /* serialized blocks */ ],
  "blockOrder": [0, 1, 2],
  "createdAt": 1712766240,
  "updatedAt": 1712766300,
  "templateValues": { "nextNumber": "5" },
  "counts": { "words": 150, "characters": 820, ... }
}

Read-only fields: pageId, blockOrder, createdAt, updatedAt, templateValues, counts.

Block

{
  "blockId": 0,
  "linkOrder": "A.M.tt",
  "lastSelectedTemplateId": null,
  "items": [ /* serialized items */ ],
  "createdAt": 1712766240,
  "updatedAt": 1712766300,
  "counts": {
    "words": 50, "characters": 280,
    "checkboxes": 0, "checkboxesChecked": 0, "checkboxesUnchecked": 0,
    "pageLinks": 2, "listItems": 1
  }
}

Read-only fields: createdAt, updatedAt, counts.

Serialized Items

indentLevel is only present when > 0 (default 0). orderedListStart is only present when style is "ol".

// Text (indentLevel omitted when 0; orderedListStart only for "ol" style)
{ "type": "text", "style": "", "content": [ /* units */ ], "indentLevel": 2 }
{ "type": "text", "style": "ol", "content": [ /* units */ ], "orderedListStart": 3 }

// Var (value is read-only, computed from formula)
{ "type": "var", "id": 0, "name": "Total", "formula": [ /* units */ ], "value": "150" }

// Image
{ "type": "image", "imageId": "a1b2c3...64hex.png" }

// Page Link (title is read-only, resolved at read time)
{ "type": "pageLink", "pageId": "AbcDef1234567890GhIj", "title": "My Page" }

Read-only fields: var value, pageLink title.

Serialized Units

// Text
{ "type": "text", "text": "Hello", "unitStyle": "bold" }

// Web Link
{ "type": "webLink", "text": "Example", "url": "https://example.com" }

// Page Link (title is read-only)
{ "type": "pageLink", "pageId": "AbcDef1234567890GhIj", "title": "My Page" }

// Meta Ref — success
{ "type": "metaRef", "ref": "M.tw", "value": "150" }
// Meta Ref — error
{ "type": "metaRef", "ref": "V.AbcDef1234567890GhIj.0", "value": null, "error": "NOT_FOUND" }

// Template Value — on template page (no resolved value)
{ "type": "templateValue", "valueType": "dateToday" }
// Template Value — on regular page (resolved)
{ "type": "templateValue", "valueType": "dateToday", "value": "2026-04-10" }

Read-only fields: metaRef.value, metaRef.error, pageLink.title, templateValue.value on regular pages.

Meta ref errors: NOT_FOUND, VAR_MISSING_REFERENCE, VAR_CIRCULAR_REFERENCE.

Normalization

The parser applies these normalization steps to written content:

• Adjacent compatible text and web-link units are merged.
• A lone page-link unit inside an unstyled text item is converted into a standalone pageLink item.
• Bullet, checkbox, and ordered-list items keep a lone inline page-link unit as text content.

Link Order

linkOrder controls automatic sorting of page-link items within a block. Format: "{direction}.{sortKey}".

Examples: A.M.tt, D.M.ua, A.V.score.

Meta References

metaRef units reference live computed values. The ref string uses dot-separated segments:

Time formats: a.ut (UNIX), a.d (date), a.dow (day of week), r.s / r.m / r.h / r.d (relative). Relative only valid for CA/UA.

PLCV derivations: cnt, sum, avg, min, max.

Images

Image IDs are content-addressed: {64 lowercase hex sha256}.{ext}. Allowed extensions: png, jpg, jpeg, webp, gif, svg.

Commands that accept new images support a top-level images map with base64 data URIs:

{
  "images": {
    "cover.png": "data:image/png;base64,iVBORw0KGgo..."
  }
}

Commands

{ "type": "command", "requestId": "1", "cmd": "LIST_INSTANCES" }

{
  "ok": true,
  "instances": [{
    "instanceId": "desk-main", "connectedAt": 1712766240,
    "state": "folder", "folder": "Work Notes",
    "offline": false, "version": "0.4.0"
  }]
}

{ "type": "command", "requestId": "1", "cmd": "LIST_FOLDERS" }

{
  "ok": true,
  "recentFolders": [{ "id": 1, "name": "My Project", "permission": "granted" }],
  "demos": ["Simple", "F1", "The Premier League", "The Universe"]
}

{ "type": "command", "requestId": "1", "cmd": "OPEN_FOLDER", "id": 1 }

{ "ok": true, "folder": "My Project", "skippedFiles": [] }

{ "type": "command", "requestId": "1", "cmd": "OPEN_DEMO", "name": "Simple" }

{ "type": "command", "requestId": "1", "cmd": "REMOVE_RECENT_FOLDER", "id": 2 }

{ "ok": true }

File Watching

{ "type": "command", "requestId": "1", "cmd": "FILES_WATCH", "subpath": "inbox", "recursive": true }

{ "ok": true, "subscriptionId": "fwatch_..." }

{ "type": "command", "requestId": "2", "cmd": "FILES_UNWATCH", "subscriptionId": "fwatch_..." }

{ "ok": true }

{
  "type": "command", "requestId": "1",
  "cmd": "READ_PAGES",
  "pageIds": ["AbcDef1234567890GhIj"],
  "icon": true, "title": true, "subtitle": true,
  "blockIds": [0, 4]
}

{ "type": "command", "requestId": "1", "cmd": "READ_PAGES", "tabs": true }

{
  "type": "command", "requestId": "1",
  "cmd": "CREATE_PAGES",
  "returnPages": true,
  "pages": [null, {
    "icon": "📝",
    "title": [{ "type": "text", "text": "New Page" }],
    "subtitle": [],
    "blocks": [{ "blockId": 0, "items": [...] }]
  }]
}

{
  "type": "command", "requestId": "1",
  "cmd": "UPDATE_PAGES",
  "pages": [{
    "pageId": "AbcDef1234567890GhIj",
    "readVersion": 3,
    "updateBlocks": [{ "blockId": 0, "items": [...] }],
    "insertBlocks": [{ "blockId": 4, "items": [...] }],
    "blockOrder": [0, 4]
  }]
}

{ "type": "command", "requestId": "1", "cmd": "DELETE_PAGES", "pageIds": ["AbcDef1234567890GhIj"] }

{
  "type": "command", "requestId": "1",
  "cmd": "QUERY",
  "scope": "pages",
  "search": { "text": "invoice", "sections": ["title", "blocks"] },
  "fields": ["icon", "title", "counts"],
  "sortBy": "updatedAt",
  "sortDirection": "desc",
  "maxResults": 20
}

Templates Commands

Template commands mirror their page counterparts. Key differences: templates can contain templateValue units, regular page IDs return NOT_TEMPLATE_PAGE errors, and the default blank template icon is "📋".

{ "type": "command", "requestId": "1", "cmd": "READ_TEMPLATES", "pageIds": ["TplPage1234567890AbC"] }

{
  "type": "command", "requestId": "1",
  "cmd": "CREATE_TEMPLATES",
  "pages": [{
    "icon": "📋",
    "title": [{ "type": "templateValue", "valueType": "dateToday" }, { "type": "text", "text": " — Daily Note" }],
    "subtitle": [],
    "blocks": [{ "blockId": 0, "items": [{ "type": "text", "style": "#", "content": [{ "type": "text", "text": "Tasks" }] }] }]
  }]
}

{ "type": "command", "requestId": "1", "cmd": "DELETE_TEMPLATES", "pageIds": ["TplPage1234567890AbC"] }

{
  "type": "command", "requestId": "1",
  "cmd": "CREATE_FROM_TEMPLATE",
  "pageId": "AbcDef1234567890GhIj",
  "blockId": 0,
  "templateId": "TplPage1234567890AbC",
  "insertAtTop": false,
  "returnPage": true
}

Items Commands

Add or remove items from individual blocks without replacing the entire page.

{
  "type": "command", "requestId": "1",
  "cmd": "PUSH_PAGE_ITEMS",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "anchor": "bottom", "offset": 0,
    "items": [{ "type": "text", "style": "[ ]", "content": [{ "type": "text", "text": "New task" }] }]
  }]
}

{
  "type": "command", "requestId": "1",
  "cmd": "POP_PAGE_ITEMS",
  "operations": [{
    "pageId": "AbcDef1234567890GhIj",
    "blockId": 0,
    "anchor": "bottom", "offset": 0,
    "count": 2
  }]
}

Workspace Commands

Discovery Commands

Events Commands

{ "type": "command", "requestId": "1", "cmd": "SUBSCRIBE", "categories": ["pages", "project", "workspace", "files"] }

Event System

All events include type, event, seq, instanceId, and timestamp (UNIX seconds). Exception: eviction omits seq, instanceId, and timestamp.

Pages Events

All include source ("user", "api", "system") and requestId when API-triggered.

pages_created

Includes icon, serialized title, and sourceTemplateId (page ID or null).

pages_updated

Every changed region includes before/after diffs. Fields: role ("direct"/"cascade"), scope (changed regions), blockChanges with ops: created, deleted, updated, reordered.

pages_deleted

Includes icon and title at deletion time.

Project Events

project_opened, project_closed, concurrent_access_detected (with detectedBy: "workspace_poll", "api_server", or "both").

Workspace Events

workspace_tab_opened, workspace_tab_closed, workspace_tab_navigated, workspace_tab_resized, workspace_scrolled, workspace_changed (coarse fallback, emitted by WRITE_WORKSPACE).

Files Events

Subscribe with category files. files_changed fires for each change record produced by an active FILES_WATCH subscription.

{ "type": "event", "event": "files_changed",
  "seq": 99, "instanceId": "desk-main", "timestamp": 1712766500,
  "source": "system",
  "subscriptionId": "fwatch_...",
  "subpath": "inbox", "recursive": true,
  "changeType": "appeared",
  "path": ["recipes", "curry.png"],
  "movedFrom": null }

Fields: subscriptionId, subpath, recursive, changeType (appeared, disappeared, modified, moved, unknown, errored), path (array, relative to subpath), movedFrom (array or null).

Eviction Event

Always delivered regardless of subscriptions. Sent when another tab connects with the same gb_id.

Error Reference

Server-Level Errors

Arrive as type: "error" messages.

PROTOCOL_MISMATCH errors include additional fields:

• serverProtocolVersion — the server's protocol version (number)
• clientProtocolVersion — the client's claimed protocol version (number or null)

Command-Level Errors

Arrive inside response messages as { ok: false, error, message }.

General

Parse and validation

Images

Page and template targeting

Workspace

Folder and demo lifecycle

File watching

Recommended Client Flow

1. Connect to ws://localhost:<port>.
2. Send LIST_FOLDERS to see available folders and demos.
3. If you expect multiple app tabs, include instance on every command.
4. Open a project with OPEN_FOLDER or OPEN_DEMO.
5. Get your bearings with ORIENTATION, then drill into specifics with READ_PAGES, QUERY, or MAP.
6. Store page versions and workspace version from responses.
7. SUBSCRIBE to pages, project, and/or workspace for real-time updates.
8. For writes, pass readVersion for optimistic concurrency.
9. If you suspect missed events, issue a fresh read and compare snapshotSeq with your latest event seq.

When to use each read command

When to use each write approach

Protocol Constants