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.
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_requiredfrom every route, with anupgrade_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.
meis the signed-in member's personal vault. Nobody else can read it, an owner or admin included.orgis the organisation's vault: every member reads it, and changing it needsorg: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 is404for 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.
Links and backlinks
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 }],toIdisnullwhile unresolved,kindislinkorembed.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
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
EventSourcereconnects by itself withLast-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 onesyncwith the whole state, which Yjs merges with what you have. A: pingcomment 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 anexternalupdate 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:managein the org vault. Others getcanWrite: falsein thesync, see every change and presence, and are refused a POST with403 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_limitedwithRetry-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 is400 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 |
sessionidentifies a browser tab (1 to 64 letters, digits,-,_).noteis the note it is on, ornull.stateisactive(the tab is in front),idle(hidden or away) orleft(it closed the note).awarenessis 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? }.stateisactive(online on the note: drawn as a solid circle),idle(online, but the tab is hidden or away: a hollow ring) orrecent(left in the last 30 minutes: a hollow ring, "Viewed 3 min ago"). A person's tabs and devices count as one, the liveliest.coloris fixed by the person, the same for every viewer.selfmarks your own other tabs and devices. - In the stream,
awarenessis[{ 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
. 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 }.
.mdfiles are read, and so are files in anattachments/folder of a type Notes takes (4 MB each): they are stored as uploads of the vault, notes linkingattachments/<file>are pointed at them, and the answer gainsattachments, 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
orgneedsorg: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 .
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
orgneedsorg: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:
POST /globe/api/files/uploads?vault=mewith JSON{ name, mime?, size }answers201 { 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).PUT /globe/api/files/uploads/{id}?seq=0with the raw bytes of part 0, and so on toparts - 1. Every part is exactlypartBytesexcept the last (400 invalid_part). Sending a part again replaces it. Answers{ received }.POST /globe/api/files/uploads/{id}assembles the file in the database and answers201 { id, url, name, mime, size }, like a single upload. With parts missing it answers409 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.