---
title: "Venom Notes API"
description: Read and write the notes in a Venom Notes vault, follow [[wikilinks]] and backlinks, search, fetch the graph, and move a vault in and out as a zip of Obsidian-compatible markdown.
section: cloud
order: 400
audience: [builder, operator, agent]
sources: [services/nodejs-cloud/app/globe/api, services/nodejs-cloud/lib/globe, services/nodejs-cloud/migrations/0116_globe.sql, services/nodejs-cloud/migrations/0119_globe_loop.sql, services/nodejs-cloud/migrations/0129_globe_live.sql, services/nodejs-cloud/lib/globe/live, services/nodejs-cloud/migrations/0131_globe_import_sources.sql, docs/globe.md, docs/adr/0050-globe-live-editing.md]
features: [cloud.globe, cloud.globe-loop, reference.doc-globe]
---

Venom Notes is a vault of markdown notes in Venom Cloud, in the style of Obsidian: folders, `[[wikilinks]]`,
backlinks and a graph of how the notes link. The vault is also the thing assistants read, so it should hold what
people want them to know. This page is the HTTP API behind the Notes app.

The API is at `/globe/api/*` on the same host as the console and uses the console's sign-in: the session cookie, not
an API key. A request without a session gets `401 signed_out` as JSON, never a redirect. The one exception is
`/globe/api/sync`, which `venom globe sync` uses with a bearer key ([Sync a folder](/docs/globe/sync.md#api)). A request that changes
something must come from the console's own origin (the same cross-site check as the console). The API belongs to
the app; it is not a machine API for keys yet.

Errors follow [the common shape](/docs/cloud/api-overview.md#errors): `{ "error": { "message", "type", "code", "param" } }`.

## Access {#access}

- Venom Notes is an add-on. An org that has not bought it gets `403 addon_required` from every route, with an
  `upgrade_url`. A self-hosted install without billing has every add-on.
- Only members of an organisation have vaults. An operator who also belongs to an organisation opens that
  organisation's vaults (the one Clerk had active at sign-in, with the role they hold there). An operator with no
  seat, or a legacy team session, gets `403 no_vault`.
- **Vaults.** `me` is the signed-in member's personal vault. Nobody else can read it, an owner or admin included.
  `org` is the organisation's vault: every member reads it, and changing it needs `org:manage`. A team vault's id
  opens it for the members of its org team (members of the teams above it included) and org admins, and is `404` for
  everyone else
  ([Notes team vaults](/docs/cloud/globe-team-vaults.md)).
- A note id from another member's personal vault, or from another org, is `404`, the same as a missing one.

## Notes {#notes}

A note has a `path`: its folder and its title, without `.md`, like `Projects/Venom/Plan`. The title is the last
part. Paths are unique within a vault, ignoring case. A path is at most 300 characters, has no `..`, no leading
slash, and none of `\ : * ? " < > | # ^ [ ]`. A folder with no notes is kept by a note named `.folder` inside it
(`Projects/.folder`).

The `body` is markdown, at most 200 KB, without frontmatter. `properties` is the frontmatter as a JSON object (at
most 32 KB): `tags`, `aliases` and anything else. A body or properties that look like they hold a secret (an API
key, a token, a private key) are refused with `422 secrets_found`.

| Route | What |
|---|---|
| `GET /globe/api/vaults` | `{ vaults: [{ id, name, scope, canWrite, count }] }` |
| `GET /globe/api/tree?vault=me` | `{ items: [{ id, path, title, folder, updatedAt, status }], order }`, folders are the path prefixes; `order` is the sidebar's manual order |
| `GET /globe/api/notes/{id}` | `{ note, backlinks, unlinked, outgoing }` |
| `POST /globe/api/notes` | `{ vault, path, body?, properties? }` creates a note: `201 { note }`, `409 path_exists` when the path is taken |
| `PATCH /globe/api/notes/{id}` | `{ body?, properties?, path? }` saves: `{ note, renamedLinks? }` |
| `DELETE /globe/api/notes/{id}` | `{ ok: true }` |
| `PATCH /globe/api/folders` | `{ vault, from, to }` renames or moves a folder and every note under it: `{ moved, renamedLinks }` |
| `PUT /globe/api/tree/order` | `{ vault, folder, names }` sets one folder's sidebar order: `{ folder, names }` |
| `GET /globe/api/notes/{id}/versions` | `{ versions: [{ id, at, by, path }] }`, newest first |
| `POST /globe/api/notes/{id}/versions/{vid}/restore` | `{ note }` |

A note is `{ id, vault, path, title, body, properties, status, updatedAt, updatedBy }`. `status` is `live`, `draft`
or `stale`.

Changing `path` renames or moves the note and rewrites the `[[links]]` that point to it, in the notes that have
them, in one transaction. `renamedLinks` says how many links changed. Every save keeps the previous state as a
version (quick saves by the same person merge into one); the last 100 are kept.

### Links and backlinks {#links}

Every save rebuilds the note's links from its body. These count: `[[Note]]`, `[[Note|alias]]`, `[[Note#Heading]]`
and `![[Embed]]`. Links inside code blocks and inline code do not. A link finds its note the way Obsidian's do: by
path when it has a folder, otherwise by title, then by an alias in `properties.aliases`, ignoring case; when
several notes match, the one nearest the linking note wins. A link to a note that does not exist yet stays
unresolved and resolves when that note is created or renamed into place.

- `outgoing`: `[{ toId, toPath, kind }]`, `toId` is `null` while unresolved, `kind` is `link` or `embed`.
- `backlinks`: notes that link here, `[{ id, path, title, excerpt }]`.
- `unlinked`: notes that mention this note's title in the text without linking to it.

`GET /globe/api/resolve?vault=me&link=Some%20Note` answers `{ id }`, or `404` when nothing matches. Add
`from=<note id>` to resolve as that note would.

## Search and graph {#search}

`GET /globe/api/search?vault=me&q=deploy` returns `{ results: [{ id, path, title, snippet }] }`: full-text search
with stemming, the best matches first, at most 30. The `snippet` marks the matched words with `⟦` and `⟧`; it is
plain text, not HTML. Without `vault` it searches every vault you can read, and each result has a `vault`.

`GET /globe/api/graph?vault=me` returns the vault as nodes and edges:

```json
{
  "nodes": [{ "id": "…", "title": "Plan", "path": "Projects/Plan", "folder": "Projects", "tags": ["venom"], "degree": 3, "status": "live" }],
  "edges": [{ "source": "…", "target": "…" }],
  "truncated": false
}
```

An edge is a resolved link from one note to another. `degree` is the number of notes a note is linked with, in
either direction. A vault of more than 20,000 notes is cut at 20,000 and `truncated` is `true`.

## Live editing {#live}

Several people can edit one note at once (ADR 0050). Each note opened live has a [Yjs](https://docs.yjs.dev)
document, a CRDT: every edit is an update that merges with everyone else's in any order, so two people typing in the
same paragraph keep both their edits. The editor binds it through TipTap's Collaboration extension on the XML fragment
named `default`. The server keeps the document in Postgres and never needs the editor's schema. There are no
WebSockets: changes come down as server-sent events and go up as POSTs.

| Route | What |
|---|---|
| `GET /globe/api/notes/{id}/live?session=<tab id>` | The note's live document as `text/event-stream`. Send `Last-Event-ID` (or `?after=<seq>`) to resume |
| `POST /globe/api/notes/{id}/live` | `{ update, clientId? }`: one Yjs update, base64. Answers `{ seq }` once it is stored |

The stream's events (`data:` is JSON):

| Event | Data | When |
|---|---|---|
| `sync` (with `id: <seq>`) | `{ seq, state, canWrite, saved, me }`: the whole document as one Yjs update; `me` is `{ uid, name, color }` for your own cursor | First, on a fresh connect, or when you are too far behind |
| `update` (with `id: <seq>`) | `{ seq, u, by, external? }`: one stored update; `external` when it came from outside an editor | Each change, including your own (applying it again is harmless) |
| `presence` | `{ people, awareness }` (see [Presence](#presence)) | When who is on the note, or a cursor, changes |
| `saved` | `{ seq, at, error }`: the note's markdown has caught up to `seq`, or could not (`error.code` is `secrets_found` or `note_too_large`) | After the markdown is written |
| `gone` | `{ reason: "deleted" \| "forbidden" }` | The note was deleted or your access ended; the stream closes |

- **Resume.** The stream ends after about 4.5 minutes, and `EventSource` reconnects by itself with `Last-Event-ID`.
  The updates after that id are replayed when the log still has them and they are at most 300 updates and 1 MB;
  otherwise you get one `sync` with the whole state, which Yjs merges with what you have. A `: ping` comment comes every
  25 seconds.
- **Saving.** An edit is saved when its POST answers. Never seed a document yourself: start from the `sync`. The
  server writes the note's markdown back through the normal save path 1.5 seconds after edits pause (at the latest 10
  seconds after the first unsaved one), as the last person who edited, so links, search, backlinks and versions follow.
  `GET /globe/api/notes/{id}` returns that markdown.
- **Writes from elsewhere.** A save through `PATCH /globe/api/notes/{id}`, MCP, the Inbox, a restore or an import
  reaches open editors as an `external` update within about a second. It changes only the blocks that changed, and
  inside a block only the text that changed, so a block someone is typing in elsewhere keeps their edits. If the write
  overwrites live edits nobody had saved yet, those are kept as a version first.
- **Who may edit.** The same as saving: anyone in their own vault, `org:manage` in the org vault. Others get
  `canWrite: false` in the `sync`, see every change and presence, and are refused a POST with `403 forbidden`.
- **Limits.** One update is at most 1 MB (`413 update_too_large`); per person and note, 120 updates or 4 MB per 10
  seconds (`429 rate_limited` with `Retry-After`; send the edits again later, they merge); a note's whole edit history at
  most 8 MB (`413 note_too_large`). Something that is not a Yjs update is `400 invalid_update`.

## Presence {#presence}

| Route | What |
|---|---|
| `POST /globe/api/presence` | `{ session, note, state, awareness?, clientId?, vault? }`: a tab's heartbeat. Answers `{ notes }` when `vault` is given, else `{ ok: true }` |
| `GET /globe/api/presence?vault=org` | `{ notes: { "<note id>": [person] } }`: the notes in a vault other people have open now |

- `session` identifies a browser tab (1 to 64 letters, digits, `-`, `_`). `note` is the note it is on, or `null`.
  `state` is `active` (the tab is in front), `idle` (hidden or away) or `left` (it closed the note).
  `awareness` is the tab's cursor as a [y-protocols](https://github.com/yjs/y-protocols) awareness update (base64, at
  most 8 KB); it is passed to the others as is.
- Heartbeat about every 15 seconds, and at once when the state or note changes. A tab not heard from for 45 seconds is
  offline.
- A person is `{ uid, name, color, state, at, self? }`. `state` is `active` (online on the note: drawn as a solid
  circle), `idle` (online, but the tab is hidden or away: a hollow ring) or `recent` (left in the last 30 minutes:
  a hollow ring, "Viewed 3 min ago"). A person's tabs and devices count as one, the liveliest. `color` is fixed by the
  person, the same for every viewer. `self` marks your own other tabs and devices.
- In the stream, `awareness` is `[{ session, clientId, data }]` for the other tabs online on the note.
- A personal note's presence is only its owner's; the vault map leaves you out.

## Import and export {#import-export}

`GET /globe/api/export?vault=me` answers `application/zip`: one `.md` file per note at its path, with the properties
as YAML frontmatter. It opens in Obsidian as it is. The uploads the notes link (images, video, files) go in an
`attachments/` folder, named `<first 8 characters of the id>-<name>`, and the notes' links become relative to it, such as
`![](../attachments/ab12cd34-photo.png)`. A file that would push the zip past 100 MB keeps its address and is left out.
The answer's `x-globe-attachments` header counts them.

`POST /globe/api/import?vault=me` takes a zip of an Obsidian vault, as a multipart form with the field `file` or as a raw
`application/zip` body, and answers `{ created, updated, skipped, unresolvedLinks }`.

- `.md` files are read, and so are files in an `attachments/` folder of a type Notes takes (4 MB each): they are stored as
  uploads of the vault, notes linking `attachments/<file>` are pointed at them, and the answer gains `attachments`, how
  many. A file with the same content already in the vault is reused. `.obsidian/` and other hidden files are skipped.
- A single top-level folder around the vault is dropped.
- A note whose path already exists is updated when its content differs (and the old content is kept as a version);
  an identical one is skipped. A note that is too large, has a name that is not allowed or looks like it holds a secret is skipped.
- Links are resolved across the whole vault, and links that were waiting for these notes resolve too.
- At most 5,000 notes and 50 MB per import. Importing into `org` needs `org:manage`.
- The platform limits a request body to 4.5 MB on Venom Cloud's hosted deployment, so larger vaults need a self-hosted install for now.

## Files {#files}

`POST /globe/api/files?vault=me` uploads a file for a note, as a multipart form with the field `file` (or the raw
bytes with the name in an `x-file-name` header), and answers `201 { id, url, name, mime, size }`. Put `url` in a note
as `![name](url)`.

`GET /globe/api/files/{id}/{name}` (and `HEAD`) serves it to anyone who can read its vault; `?download` asks for an
attachment. Everyone else gets 404.

- At most 4 MB a file in one request, 100 MB in parts, and 1 GB an organisation (`413 file_too_large`, `413 files_quota`).
- Images, video, audio, PDF, text, CSV, Markdown, JSON, zip and office documents; anything else is `415 unsupported_type`.
- Uploading into `org` needs `org:manage`.

### Large files {#large-files}

A file over 4 MB is sent in parts of 3 MB, because a hosted request body is limited to 4.5 MB. The editor does this for
you. To do it yourself:

1. `POST /globe/api/files/uploads?vault=me` with JSON `{ name, mime?, size }` answers `201 { id, partBytes, parts }`. The
   declared size counts against the organisation's quota at once; ten unfinished uploads per member at most
   (`429 too_many_uploads`).
2. `PUT /globe/api/files/uploads/{id}?seq=0` with the raw bytes of part 0, and so on to `parts - 1`. Every part is
   exactly `partBytes` except the last (`400 invalid_part`). Sending a part again replaces it. Answers `{ received }`.
3. `POST /globe/api/files/uploads/{id}` assembles the file in the database and answers `201 { id, url, name, mime,
   size }`, like a single upload. With parts missing it answers `409 incomplete_upload`.

An upload left unfinished for a day is deleted. Only the member who started an upload can add to it.

## Comments {#comments}

`GET /globe/api/notes/{id}/comments` answers `{ threads }`: each with `id`, `kind` (`inline` on text, `page` on the
page), `quote`, `resolvedAt`, `resolvedBy` and `comments` (`id`, `author`, `body`, `createdAt`, `editedAt`, `mine`,
`reactions`).

| Request | Does |
|---|---|
| `POST /globe/api/notes/{id}/comments` `{ kind, quote?, id?, body }` | starts a thread; for `inline`, put `<span data-comment="{id}">…</span>` around the text in the note |
| `POST /globe/api/notes/{id}/comments` `{ threadId, body }` | replies |
| `PATCH /globe/api/comments/{id}` `{ body }` | edits your comment |
| `DELETE /globe/api/comments/{id}` | deletes your comment; a thread's first comment deletes the thread |
| `POST /globe/api/comments/{id}/reactions` `{ emoji }` | adds your reaction, or takes it back |
| `PATCH /globe/api/comments/threads/{id}` `{ resolved }` | resolves or reopens |
| `GET /globe/api/comments/notifications` | `{ notifications, unread }`: mentions and replies for you |
| `POST /globe/api/comments/notifications[?note=]` | marks them read |

A mention is `@[Name](user:<member id>)` in `body`. Anyone who can read the note may comment; a team or service key
only reads.

## Inbox and capture {#inbox}

What Notes learns arrives as suggestions in the Inbox ([How Notes learns](/docs/cloud/globe-learning.md)). The same routes serve
the app and anything you build on it.

| Route | What |
|---|---|
| `GET /globe/api/inbox?vault=me&status=pending` | `{ items, counts: { me, org } }`. `status` is `pending` (the default), `applied`, `rejected`, `undone` or `all` |
| `POST /globe/api/inbox` | `{ vault, suggestions }` files 1 to 50 suggestions as you. They wait for a decision, even in your own vault: `201 { added, ids }` |
| `GET /globe/api/inbox/count` | `{ pending }`, across the vaults you read |
| `POST /globe/api/inbox/{id}/apply` | `{ edits? }` applies it, edited first: `{ item, noteId }` |
| `POST /globe/api/inbox/{id}/reject` | `{ item }` |
| `POST /globe/api/inbox/{id}/undo` | `{ item }`. Refused with `409 changed_since` once the note was edited after |
| `POST /globe/api/inbox/apply-all?vault=org` | `{ applied, failed }`: every pending suggestion but conflicts and rewrites |
| `POST /globe/api/capture` | JSON `{ vault, title?, text, kind? }`, or a multipart form with `file` (`.md`, `.txt`, `.html`, up to 5 MB), `vault` and `title`: `201 { source, duplicate: false }`, or `200` with `duplicate: true` for text the vault already has. `kind` is `capture` (the default) or `memory-paste`, a list of what an AI chat app remembers about you, read like an imported chat |
| `GET /globe/api/sources?vault=me` | `{ sources }`: what came in, newest first, with its status (`queued`, `done`, `failed`, `skipped`) |
| `GET /globe/api/sources/{id}` | `{ source, text }`: the original as captured |
| `GET /globe/api/settings/loop` | `{ settings: { daily_cap_usd, session_summaries, memory }, spent_today_usd, paused, resumes_at, summaries_collected }` |
| `PUT /globe/api/settings/loop` | `{ daily_cap_usd?, session_summaries?, memory? }` (needs `org:manage`) |
| `GET /globe/api/notes/{id}/freshness` | `{ score, stale, days, why, status }` |
| `POST /globe/api/notes/{id}/confirm` | "Confirm still true": the same shape. A stale note is live again |

A suggestion is one of:

```json
{ "kind": "create", "path": "Ops/Release Freeze", "body": "The week before a launch. See [[Deploys]]." }
{ "kind": "append", "noteId": "…", "heading": "Schedule", "text": "Deploys move to Thursdays." }
{ "kind": "link", "fromId": "…", "toId": "…", "reason": "A bad deploy is undone by a rollback." }
{ "kind": "conflict", "noteId": "…", "excerpt": "We deploy on Tuesdays.", "sourceExcerpt": "We deploy on Thursdays.", "explanation": "The days differ." }
{ "kind": "replace", "noteId": "…", "body": "…", "baseVersionId": "…" }
```

Note ids must be live notes of the vault (`404 note_not_found`), paths follow the note rules and may not be in
`Memory/` or `Inbox/`, and anything that looks like a secret is refused (`422 secrets_found`). Deciding on the org
vault's suggestions needs `org:manage` (`403 forbidden`). Another vault's or another org's suggestion is a 404.

## Import from Notion and markdown {#pages-import}

Notes and databases read in the browser from a Notion export or a folder of markdown
([Import from Notion and markdown folders](/docs/globe/import-from-apps.md)).

| Route | What |
|---|---|
| `POST /globe/api/import/pages` | `{ vault, notes?, databases? }`. `notes` is up to 400 of `{ path, body, properties? }`, written in one transaction like the zip import (same path: updated and versioned; others created; links resolved). `databases` is up to 50 of `{ name, folder, schema }`, created after the notes; a folder that already holds a database is not changed. `200 { created, updated, skipped, unresolvedLinks, databases, databaseConflicts }`. The body is at most 8 MB; importing into `org` needs `org:manage` |

## Import from AI chats {#ai-import}

Conversations from a ChatGPT or Claude data export, parsed in the browser and sent in batches
([Import from ChatGPT and Claude](/docs/globe/import-from-ai.md)). The zip itself is never uploaded.

| Route | What |
|---|---|
| `GET /globe/api/import/conversations?vault=me` | `{ vault, can_use_org, model, price, daily_cap_usd, spent_today_usd, sources, limits }`. `model` is the loop's model (the default gear's summary model) and `price` its list price in USD per 1M tokens (`{ input, output }`, null when unknown). `sources` counts the vault's imported sources by kind (`chatgpt`, `claude`, `memory-paste`) and status (`queued`, `done`, `failed`, `skipped`). `limits` is `{ batch, send_bytes, chars }` |
| `POST /globe/api/import/conversations` | `{ vault, conversations, connect_now? }`, 1 to 25 conversations in at most 4 MB. `201` when any was queued, else `200`: `{ results, queued, duplicates, skipped, redacted }` |

Each conversation is:

```json
{
  "vendor": "chatgpt",
  "id": "the vendor's conversation id",
  "title": "Planning the migration",
  "created": "2025-02-03T09:15:00Z",
  "origin": "conversation",
  "messages": [
    { "role": "user", "text": "We're moving to Kubernetes. I own the plan." },
    { "role": "assistant", "text": "Stateless services first is a common order." }
  ]
}
```

`vendor` is `chatgpt` or `claude`. `role` is `user`, `assistant` or `document` (a Claude project's instructions or
files, with `origin: "project"`). `created` is ISO 8601 or epoch seconds, and may be null.

The server renders each conversation as a markdown transcript and stores it as one queued source: `kind` is the
vendor, `ref` the vendor's id, `format` `chat`. Text that looks like a key or token is replaced with
`[secret removed]`, and `redacted` counts the replacements. Each result is `{ id, status, sourceId?, redacted?, message? }`,
where `status` is one of:

| Status | Meaning |
|---|---|
| `queued` | stored; the loop reads it within the daily cap |
| `duplicate` | the vault already has this conversation (same kind and id, or identical text) |
| `empty` | nothing the person wrote |
| `too_large` | over 1,000,000 characters or 20,000 messages |
| `invalid` | not the shape above |

`connect_now: true` starts reading the first three right after the response. The browser sends it with the first
batch only. Importing into `org` needs `org:manage` (`403 forbidden`). The loop reads imported sources and pasted
memory lists with a prompt tuned for chat transcripts, and their suggestions wait in the Inbox even in a personal
vault.

## Audit {#audit}

Every change writes an audit row (`globe.note.created`, `.updated`, `.renamed`, `.deleted`, `.restored`,
`globe.vault.imported`, `globe.vault.exported`, `globe.file.uploaded`, `globe.comment.*`, `globe.source.captured`, `globe.import.batch`, `globe.note.confirmed`, `globe.loop.settings`)
with ids, counts and hashes. It never holds a note's title, path or text, or what was captured.
