Skip to content
Docs menu

Build on Venom Notes

Read, write and search notes and databases from code or an agent. Write meeting notes, file suggestions for a person to review, query databases and follow org vault changes over REST or MCP.

View .md

Venom Notes holds your organisation's markdown notes and databases in vaults: each member's personal vault, the org vault and team vaults. Every Notes tool is an MCP tool on the workspace server and a REST route under /api/v1, and both run the same code as the Notes app, so the app's access rules, audit log and secret check apply.

What you can build

  • Meeting notes from a recorder. Write a note after each call (POST /api/v1/notes, mode create), then add action items to it later with anchored edits (PATCH /api/v1/notes/{id}).
  • A review queue instead of direct writes. File new notes, appended text or links as suggestions in a vault's Inbox (POST /api/v1/notes/suggestions); a person applies or rejects each one in the app.
  • Answers grounded in your notes. Fetch the notes that answer a question as numbered citations (POST /api/v1/notes/ask) and let your own model write the answer.
  • A tracker kept in a database. Create a database with its columns (POST /api/v1/databases), add rows from a script (POST /api/v1/databases/{database}/rows) and read them back filtered (GET /api/v1/databases/{database}/rows).
  • Sync into another tool. Poll what changed in notes and issues with GET /api/v1/changes (the workspace_change_list tool), or receive the globe.note.* org webhooks below.

At a glance

Generated from the code on every docs build.

MCP endpoint https://cloud.usevenom.dev/workspace/mcp/globe, server name venom-globe
Connect claude mcp add --transport http venom-globe https://cloud.usevenom.dev/workspace/mcp/globe
MCP tools 92 (37 read, 55 write)
OAuth scopes globe:read globe:write
REST twin 94 routes under https://cloud.usevenom.dev/api/v1
Webhook events globe.note.created, globe.note.updated, globe.note.deleted, globe.team_note.created, globe.team_note.updated, globe.team_note.deleted

Authentication and scopes

What a caller sees depends on whether it acts for a member:

  • A personal API key acts for its member. It reads their personal vault, the org vault and the team vaults they belong to, and writes where their role may write. Every member writes their personal vault and their team vaults; writing the org vault needs the org:manage permission (owners and admins).
  • A team key has no member. It reads the org vault only, has no personal vault (vault: "me" is refused) and cannot write notes there, but it can file suggestions in the org vault's Inbox. If an admin bound it to a service agent, the agent's scope applies too: an agent scoped to other apps is refused every Notes tool, and a read-only agent cannot write or suggest.
  • An OAuth app acts for the member who connected it, with their rights. It needs globe:read to use Notes at all and globe:write to write, edit or suggest.

Notes is included in the Team plan and up. An organisation without it gets a tool error that says so and links to the billing page; over REST that is 403 forbidden with the same words. A self-hosted install without billing has Notes.

A note in another member's personal vault, or in a team vault you are not in, answers as if it did not exist.

Worked example

Write a meeting note in your personal vault, then add an action item under its heading:

curl -X POST "$VENOM_CLOUD/api/v1/notes" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: standup-2026-11-09' \
  -d '{"vault": "me", "path": "Meetings/2026-11-09 Standup", "mode": "create",
       "body": "---\ntags: [standup]\n---\n## Notes\n\nShipped the importer.\n\n## Action items\n"}'

curl -X PATCH "$VENOM_CLOUD/api/v1/notes/<note-id>" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"edits": [{"op": "insert_after", "anchor": "## Action items\n", "text": "- [ ] Ana: review the importer PR\n"}]}'

The same edit over MCP, from any client connected to /workspace/mcp/globe:

{ "jsonrpc": "2.0", "id": 1, "method": "tools/call",
  "params": { "name": "globe_note_edit",
              "arguments": { "id": "<note-id>",
                             "edits": [{ "op": "insert_after", "anchor": "## Action items\n", "text": "- [ ] Ana: review the importer PR\n" }] } } }

Each anchor must match the note's current text exactly once, and the edits apply all or none. A read answers the note's version as its ETag; send it back as If-Match and a write that would overwrite someone else's change answers 412. A retry with the same Idempotency-Key within 24 hours replays the first answer.

If the credential cannot write the vault, file the same change as a suggestion instead:

curl -X POST "$VENOM_CLOUD/api/v1/notes/suggestions" \
  -H "Authorization: Bearer $VENOM_API_KEY" -H 'Content-Type: application/json' \
  -d '{"vault": "org", "suggestions": [{"kind": "append", "noteId": "<note-id>", "heading": "Action items", "text": "- [ ] Ana: review the importer PR"}]}'

Suggestions go to the Inbox of your personal vault or the org vault; team vaults have no Inbox yet.

Limits

  • A note body is at most 200 KB and a request at most 1 MiB.
  • A write that contains a credential (an API key, a token, a private key) is refused and nothing is stored.
  • Every write is recorded in the organisation's audit log under the credential, with ids and content hashes, never the text. A note's history names the agent: "Claude Code (via MCP, for ana@example.com)".
  • Rate limits are those of the workspace server: see Errors, limits and pagination.

The MCP endpoint of Notes alone

POST /globe/mcp still serves the same Notes tools as its own server, with its own limit of 120 requests a minute per credential. OAuth tokens issued for it work there only. New integrations should use /workspace/mcp/globe, which shares one credential and one rate window with the other products. Setup for both is in Use Notes from any agent.

The Notes app's own HTTP API, /globe/api/*, uses the console's sign-in and is not for keys, with one exception: /globe/api/sync, which venom globe sync calls with a bearer key (Sync a folder).

Events

6 org webhook events, generated from lib/webhooks/events.ts. Subscribe an endpoint to them in Settings, Webhooks (see Webhooks and events).

Event When
globe.note.created A note was created in the org vault of Venom Notes (never a personal vault's): its id, path and who wrote it. Never the note's text.
globe.note.updated A note in the org vault changed (its text, path or properties). Edits within a minute, live typing included, arrive as one event.
globe.note.deleted A note in the org vault was moved to the trash or deleted.
globe.team_note.created A note was created in a team vault of Venom Notes: its id, path, the ids of the teams whose vault holds it and who wrote it. Never the note's text, and never a personal vault's note.
globe.team_note.updated A note in a team vault changed (its text, path or properties): id, path, team ids and who. Edits within a minute arrive as one event.
globe.team_note.deleted A note in a team vault was moved to the trash or deleted: its id, path and team ids.

Only notes in the org vault send events; personal and team vault notes never do. Edits to one note within a minute, live typing included, arrive as one globe.note.updated. For everything else, including personal notes your key can read, poll GET /api/v1/changes with the cursor from the previous answer.

REST routes

The REST twin: 94 routes under https://cloud.usevenom.dev/api/v1, each calling the MCP tool named in its row with the same arguments (see the REST twin).

/vaults

Method Path Summary MCP tool
GET /api/v1/vaults List the vaults you can read globe_vault_list

/notes

Method Path Summary MCP tool
GET /api/v1/notes List notes in a vault or folder, newest change first globe_note_list
POST /api/v1/notes Create a note, or append to or replace one globe_note_write
GET /api/v1/notes/search Search notes globe_note_search
POST /api/v1/notes/suggestions Put suggested notes in a vault's inbox for a person to review globe_suggestion_create
POST /api/v1/notes/ask Ask a question and get an answer from the notes globe_note_ask
GET /api/v1/notes/{id} Read a note by id (or by vault and path with id omitted: GET /notes/-) globe_note_get
PATCH /api/v1/notes/{id} Change part of a note with anchored edits, all or nothing globe_note_edit
PATCH /api/v1/notes/{id}/properties Set or remove a note's properties (frontmatter) by name globe_note_property_update
POST /api/v1/notes/{id}/trash Move a note to the trash globe_note_delete
GET /api/v1/notes/{id}/versions List a note's saved versions globe_version_list
POST /api/v1/notes/{id}/versions/{version}/restore Restore an earlier version of a note globe_version_restore
GET /api/v1/notes/{id}/freshness How fresh a note is globe_note_freshness
POST /api/v1/notes/{id}/confirm Confirm a note is still right globe_note_confirm
GET /api/v1/notes/{id}/publish A note's publish state globe_note_publish_get
POST /api/v1/notes/{id}/publish Publish a note to a public link globe_note_publish
POST /api/v1/notes/{id}/unpublish Unpublish a note globe_note_unpublish
GET /api/v1/notes/{id}/shares Who a note is shared with globe_share_list
POST /api/v1/notes/{id}/shares Share a note with a member or a group globe_share_create
PATCH /api/v1/notes/{id}/shares Restrict an org note to the people invited, or open it globe_share_update
POST /api/v1/notes/{id}/shares/remove Remove someone's access to a note globe_share_delete
POST /api/v1/notes/move Move notes or folders into another vault globe_note_move
POST /api/v1/notes/move/preview What moving notes into another vault would do globe_note_move_preview
POST /api/v1/notes/move/undo Undo a move between vaults globe_note_move_undo
GET /api/v1/notes/{id}/related Notes related to a note, with the reason for each globe_note_related
GET /api/v1/notes/{id}/comments A note's comment threads globe_comment_list
POST /api/v1/notes/{id}/comments Comment on a note, or reply to a thread globe_comment_create
GET /api/v1/notes/{id}/synced Copies of a synced block globe_synced_list
POST /api/v1/notes/{id}/synced/unsync Turn a synced block's copies into plain text globe_synced_unsync

/databases

Method Path Summary MCP tool
GET /api/v1/databases List databases in a vault globe_database_list
POST /api/v1/databases Create a database, inline in a note or as a page, with properties, rows and a view globe_database_create
POST /api/v1/databases/import Import CSV or a markdown table as a database, or into one globe_database_import
GET /api/v1/databases/{database} Read a database: properties, views, row count, version globe_database_get
PATCH /api/v1/databases/{database} Change a database's title and schema: add, rename, retype, delete properties and options globe_database_update
POST /api/v1/databases/{database}/trash Move a database to the trash globe_database_delete
GET /api/v1/databases/{database}/rows List rows with filter, sort and paging (filter and sort as JSON in the query string) globe_row_list
POST /api/v1/databases/{database}/rows Add up to 100 rows globe_row_create
PATCH /api/v1/databases/{database}/rows Change up to 100 rows at once (updates) globe_row_update
PATCH /api/v1/databases/{database}/rows/{row} Change a row's values, title or page body globe_row_update
POST /api/v1/databases/{database}/rows/{row}/trash Delete a row (to the trash) globe_row_delete
POST /api/v1/databases/{database}/rows/trash Delete several rows, or all: true to clear the table globe_row_delete
POST /api/v1/databases/validate Check a ```base block or .base file and get its warnings globe_database_validate
POST /api/v1/databases/{database}/views Add a table, board, list, gallery, calendar, timeline or chart view globe_view_create
PATCH /api/v1/databases/{database}/views/{view} Change a view globe_view_update
GET /api/v1/databases/{database}/export Export a database as a .base file globe_database_export
GET /api/v1/databases/{database}/automations Recent runs of a database's automations globe_automation_list
GET /api/v1/databases/{database}/templates A database's row templates globe_template_list
POST /api/v1/databases/{database}/templates Add a row template globe_template_create
PATCH /api/v1/databases/{database}/templates/{template} Change a row template globe_template_update
POST /api/v1/databases/{database}/templates/{template}/delete Delete a row template globe_template_delete
POST /api/v1/databases/{database}/rows/{row}/apply Fill a row from a template globe_row_apply
POST /api/v1/databases/{database}/rows/{row}/press Press a row's button globe_row_press

/trash

Method Path Summary MCP tool
GET /api/v1/trash List trashed notes globe_trash_list
POST /api/v1/trash/{id}/restore Restore a trashed note globe_note_restore
POST /api/v1/trash/{id}/purge Delete a trashed note for good globe_trash_purge

/shared

Method Path Summary MCP tool
GET /api/v1/shared Notes shared with you globe_shared_list

/links

Method Path Summary MCP tool
GET /api/v1/links/resolve Resolve a [[wikilink]] to a note globe_link_resolve

/graph

Method Path Summary MCP tool
GET /api/v1/graph The link graph of a vault globe_graph_get

/folders

Method Path Summary MCP tool
POST /api/v1/folders/move Rename or move a folder with its notes globe_folder_move

/favorites

Method Path Summary MCP tool
GET /api/v1/favorites Your favourite notes globe_favorite_list
POST /api/v1/favorites Replace your favourite notes globe_favorite_set

/dashboards

Method Path Summary MCP tool
GET /api/v1/dashboards Pages that hold live insights (Experiments and Tasks) globe_dashboard_list

/import

Method Path Summary MCP tool
GET /api/v1/import/jobs Move in from Notion imports globe_import_job_list
GET /api/v1/import/jobs/{id} One Move in from Notion import globe_import_job_get
PATCH /api/v1/import/jobs/{id} Pause, resume or cancel a Notion import globe_import_job_update

/team-vaults

Method Path Summary MCP tool
GET /api/v1/team-vaults Team vaults you open globe_team_list
POST /api/v1/team-vaults Start a team vault on an org team, or on a new one globe_team_create
PATCH /api/v1/team-vaults/{team} Rename a team vault globe_team_update
POST /api/v1/team-vaults/{team}/delete Close an empty team vault (the team stays) globe_team_delete
GET /api/v1/team-vaults/{team}/members Who opens a team vault (parent teams included) globe_team_member_list
POST /api/v1/team-vaults/{team}/members Add someone to a team vault, or change their role globe_team_member_add
POST /api/v1/team-vaults/{team}/members/remove Take someone out of a team vault, or leave it globe_team_member_remove

/comments

Method Path Summary MCP tool
PATCH /api/v1/comments/{comment} Edit your comment globe_comment_update
POST /api/v1/comments/{comment}/delete Delete a comment or its thread globe_comment_delete
POST /api/v1/comments/{comment}/reactions Toggle your emoji reaction on a comment globe_comment_react

/comment-threads

Method Path Summary MCP tool
PATCH /api/v1/comment-threads/{thread} Resolve or reopen a comment thread globe_comment_resolve

/notifications

Method Path Summary MCP tool
GET /api/v1/notifications Your comment notifications globe_notification_list
POST /api/v1/notifications/read Mark comment notifications read globe_notification_read

/suggestions

Method Path Summary MCP tool
GET /api/v1/suggestions A vault's Inbox globe_suggestion_list
POST /api/v1/suggestions/{id}/apply Apply an Inbox suggestion globe_suggestion_apply
POST /api/v1/suggestions/{id}/reject Reject an Inbox suggestion globe_suggestion_reject
POST /api/v1/suggestions/{id}/undo Undo a decided suggestion globe_suggestion_undo
POST /api/v1/suggestions/apply-all Apply every pending suggestion of a vault globe_suggestion_apply_all

/sources

Method Path Summary MCP tool
GET /api/v1/sources A vault's sources globe_source_list
POST /api/v1/sources Capture text as a source for the loop globe_source_create
GET /api/v1/sources/{id} Read a source globe_source_get

/files

Method Path Summary MCP tool
GET /api/v1/files A Notes file, or a note's pictures: names, types, sizes and short-lived download URLs (no image blocks over REST) globe_file_get
POST /api/v1/files Store a file in a vault: an upload_id (after the PUT), a public url, or small base64; optionally add it to a note globe_file_upload
POST /api/v1/files/uploads Prepare a one-time upload URL for a file's raw bytes (PUT them with curl -T) globe_file_prepare

/settings

Method Path Summary MCP tool
GET /api/v1/settings the Notes loop settings globe_setting_get
PATCH /api/v1/settings Change the Notes loop settings globe_setting_update

/imports

Method Path Summary MCP tool
GET /api/v1/imports Chat-history import status of a vault globe_import_list
POST /api/v1/imports/conversations Queue chat conversations as sources globe_conversation_import
POST /api/v1/imports/pages Write a batch of notes and databases read from an export globe_page_import

MCP tools

92 tools: 37 read, 55 write. Generated from the code; "write (destructive)" is the tool's destructiveHint. A tool with a REST route is the same call over HTTP.

Tool Title Access Scope REST route
globe_automation_list A database's automation runs read globe:read GET /api/v1/databases/{database}/automations
globe_comment_create Comment on a note write globe:write POST /api/v1/notes/{id}/comments
globe_comment_delete Delete a comment write (destructive) globe:write POST /api/v1/comments/{comment}/delete
globe_comment_list List a note's comment threads read globe:read GET /api/v1/notes/{id}/comments
globe_comment_react React to a comment write globe:write POST /api/v1/comments/{comment}/reactions
globe_comment_resolve Resolve or reopen a thread write globe:write PATCH /api/v1/comment-threads/{thread}
globe_comment_update Edit a comment write globe:write PATCH /api/v1/comments/{comment}
globe_conversation_import Import chat conversations write globe:write POST /api/v1/imports/conversations
globe_dashboard_list List dashboard pages read globe:read GET /api/v1/dashboards
globe_database_create Create a Notes database write globe:write POST /api/v1/databases
globe_database_delete Delete a Notes database write (destructive) globe:write POST /api/v1/databases/{database}/trash
globe_database_export Export a database as a .base file read globe:read GET /api/v1/databases/{database}/export
globe_database_get Read a Notes database read globe:read GET /api/v1/databases/{database}
globe_database_import Import a table into a Notes database write globe:write POST /api/v1/databases/import
globe_database_list List Notes databases read globe:read GET /api/v1/databases
globe_database_update Change a Notes database write (destructive) globe:write PATCH /api/v1/databases/{database}
globe_database_validate Check a ```base block read globe:read POST /api/v1/databases/validate
globe_favorite_list List favourite notes read globe:read GET /api/v1/favorites
globe_favorite_set Set favourite notes write globe:write POST /api/v1/favorites
globe_file_get See a file or a note's pictures read globe:read GET /api/v1/files
globe_file_prepare Prepare a file upload write globe:write POST /api/v1/files/uploads
globe_file_upload Upload a file write globe:write POST /api/v1/files
globe_folder_move Rename or move a folder write globe:write POST /api/v1/folders/move
globe_graph_get The link graph of a vault read globe:read GET /api/v1/graph
globe_import_job_get Read a Notion import read globe:read GET /api/v1/import/jobs/{id}
globe_import_job_list List Notion imports read globe:read GET /api/v1/import/jobs
globe_import_job_update Pause, resume or cancel a Notion import write globe:write PATCH /api/v1/import/jobs/{id}
globe_import_list Import status read globe:read GET /api/v1/imports
globe_link_resolve Resolve a [[wikilink]] read globe:read GET /api/v1/links/resolve
globe_note_ask Ask Notes read globe:read POST /api/v1/notes/ask
globe_note_confirm Confirm a note is still right write globe:write POST /api/v1/notes/{id}/confirm
globe_note_delete Move a note to the trash write (destructive) globe:write POST /api/v1/notes/{id}/trash
globe_note_edit Edit part of a note write globe:write PATCH /api/v1/notes/{id}
globe_note_freshness How fresh a note is read globe:read GET /api/v1/notes/{id}/freshness
globe_note_get Read a note read globe:read GET /api/v1/notes/{id}
globe_note_list List notes read globe:read GET /api/v1/notes
globe_note_move Move notes into another vault write globe:write POST /api/v1/notes/move
globe_note_move_preview Preview a move into another vault read globe:read POST /api/v1/notes/move/preview
globe_note_move_undo Undo a move between vaults write globe:write POST /api/v1/notes/move/undo
globe_note_property_update Set a note's properties write globe:write PATCH /api/v1/notes/{id}/properties
globe_note_publish Publish a note to a public link write globe:write POST /api/v1/notes/{id}/publish
globe_note_publish_get Read a note's publish state read globe:read GET /api/v1/notes/{id}/publish
globe_note_related Notes related to a note read globe:read GET /api/v1/notes/{id}/related
globe_note_restore Restore a note from the trash write globe:write POST /api/v1/trash/{id}/restore
globe_note_search Search notes read globe:read GET /api/v1/notes/search
globe_note_unpublish Unpublish a note write globe:write POST /api/v1/notes/{id}/unpublish
globe_note_write Write a note write (destructive) globe:write POST /api/v1/notes
globe_notification_list Comment notifications read globe:read GET /api/v1/notifications
globe_notification_read Mark notifications read write globe:write POST /api/v1/notifications/read
globe_page_import Import pages and databases write globe:write POST /api/v1/imports/pages
globe_row_apply Fill a row from a template write globe:write POST /api/v1/databases/{database}/rows/{row}/apply
globe_row_create Add rows to a Notes database write globe:write POST /api/v1/databases/{database}/rows
globe_row_delete Delete a row of a Notes database write (destructive) globe:write POST /api/v1/databases/{database}/rows/{row}/trash (+1)
globe_row_list List rows of a Notes database read globe:read GET /api/v1/databases/{database}/rows
globe_row_press Press a row's button write globe:write POST /api/v1/databases/{database}/rows/{row}/press
globe_row_update Change a row of a Notes database write globe:write PATCH /api/v1/databases/{database}/rows (+1)
globe_setting_get Read the Notes loop settings read globe:read GET /api/v1/settings
globe_setting_update Change the Notes loop settings write globe:write PATCH /api/v1/settings
globe_share_create Share a note with someone write globe:write POST /api/v1/notes/{id}/shares
globe_share_delete Remove someone's access to a note write (destructive) globe:write POST /api/v1/notes/{id}/shares/remove
globe_share_list Who a note is shared with read globe:read GET /api/v1/notes/{id}/shares
globe_share_update Restrict or open an org note write globe:write PATCH /api/v1/notes/{id}/shares
globe_shared_list Notes shared with me read globe:read GET /api/v1/shared
globe_source_create Capture text as a source write globe:write POST /api/v1/sources
globe_source_get Read a source read globe:read GET /api/v1/sources/{id}
globe_source_list List sources read globe:read GET /api/v1/sources
globe_suggestion_apply Apply a suggestion write globe:write POST /api/v1/suggestions/{id}/apply
globe_suggestion_apply_all Apply every pending suggestion write globe:write POST /api/v1/suggestions/apply-all
globe_suggestion_create Suggest changes to notes write globe:write POST /api/v1/notes/suggestions
globe_suggestion_list List the Inbox read globe:read GET /api/v1/suggestions
globe_suggestion_reject Reject a suggestion write globe:write POST /api/v1/suggestions/{id}/reject
globe_suggestion_undo Undo a suggestion write globe:write POST /api/v1/suggestions/{id}/undo
globe_synced_list Copies of a synced block read globe:read GET /api/v1/notes/{id}/synced
globe_synced_unsync Unsync a block write globe:write POST /api/v1/notes/{id}/synced/unsync
globe_team_create Start a team vault write globe:write POST /api/v1/team-vaults
globe_team_delete Close an empty team vault write (destructive) globe:write POST /api/v1/team-vaults/{team}/delete
globe_team_list List team vaults read globe:read GET /api/v1/team-vaults
globe_team_member_add Add someone to a team vault write globe:write POST /api/v1/team-vaults/{team}/members
globe_team_member_list List a team vault's people read globe:read GET /api/v1/team-vaults/{team}/members
globe_team_member_remove Take someone out of a team vault write (destructive) globe:write POST /api/v1/team-vaults/{team}/members/remove
globe_team_update Rename a team vault write globe:write PATCH /api/v1/team-vaults/{team}
globe_template_create Add a row template write globe:write POST /api/v1/databases/{database}/templates
globe_template_delete Delete a row template write (destructive) globe:write POST /api/v1/databases/{database}/templates/{template}/delete
globe_template_list A database's row templates read globe:read GET /api/v1/databases/{database}/templates
globe_template_update Change a row template write globe:write PATCH /api/v1/databases/{database}/templates/{template}
globe_trash_list List the trash read globe:read GET /api/v1/trash
globe_trash_purge Delete a trashed note for good write (destructive) globe:write POST /api/v1/trash/{id}/purge
globe_vault_list List Notes vaults read globe:read GET /api/v1/vaults
globe_version_list List a note's versions read globe:read GET /api/v1/notes/{id}/versions
globe_version_restore Restore a note's earlier version write globe:write POST /api/v1/notes/{id}/versions/{version}/restore
globe_view_create Add a view to a Notes database write globe:write POST /api/v1/databases/{database}/views
globe_view_update Change a view of a Notes database write globe:write PATCH /api/v1/databases/{database}/views/{view}