Skip to content
Docs menu

Venom Notes API

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.

View .md

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). 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: { "error": { "message", "type", "code", "param" } }.

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).
  • A note id from another member's personal vault, or from another org, is 404, the same as a missing one.

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.

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.

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:

{
  "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

Several people can edit one note at once (ADR 0050). Each note opened live has a Yjs 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) 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

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 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

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

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

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

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

What Notes learns arrives as suggestions in the Inbox (How Notes learns). 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:

{ "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

Notes and databases read in the browser from a Notion export or a folder of markdown (Import from Notion and markdown folders).

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

Conversations from a ChatGPT or Claude data export, parsed in the browser and sent in batches (Import from ChatGPT and Claude). 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:

{
  "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

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.