Last updated: March 7, 2026

Public API Reference

Programmatic access to your OmniCanvas notes, folders, tags, and web clipping. Available on the Power plan.

Authentication

All API requests require an API key passed as a Bearer token. Create and manage keys in Settings → API Access inside the app.

Header
Authorization: Bearer pk_live_your_key_here

Keys use the pk_live_ prefix. Keep your keys secret — they grant full access to your account.

Base URL

https://app.omnicanvasnotes.com/api/v1

Rate Limits

All endpoints are rate limited to 100 requests per minute per user. Rate limit info is returned in response headers:

  • X-RateLimit-Remaining — requests left in the current window
  • X-RateLimit-Reset — Unix timestamp when the window resets

Response Format

All responses use a consistent JSON envelope:

{
  "data": { ... },
  "error": null,
  "meta": {
    "timestamp": "2026-03-07T12:00:00.000Z"
  }
}

On error, data is null and error contains { code, message }.

Notes

GET/notes

List your notes. Supports filtering and pagination.

Query params:

  • limit (1–100, default 50)
  • offset (default 0)
  • tag — filter by tag
  • folderId — filter by folder
  • search — search titles
GET/notes/:id

Get a single note with full content.

Pass ?includeCanvas=true to include canvas data. Encrypted notes return canvasData: null.

POST/notes

Create a new note.

Body
{
  "title": "My Note",
  "tags": ["research", "ai"],
  "folderIds": ["folder-id"],
  "isPinned": false,
  "canvasData": { ... }
}

All fields are optional.

PATCH/notes/:id

Update a note. Only provided fields are changed.

Tags and folderIds replace existing values entirely. Encrypted notes cannot have their canvas data updated via API.

DELETE/notes/:id

Delete a note. Soft delete by default (moves to trash).

Pass ?permanent=true to permanently delete including version history.

Folders

GET/folders

List all folders with note counts.

GET/folders/:id

Get a folder and its note list.

POST/folders

Create a folder.

Body
{
  "name": "Research",
  "parentId": "optional-parent-folder-id"
}
PATCH/folders/:id

Update a folder name or parent.

DELETE/folders/:id

Delete a folder (soft delete).

Search

GET/search?q=query

Full-text search across note titles and OCR text. Returns matching excerpts.

Minimum 2 characters. Encrypted notes are excluded. Supports limit and offset pagination.

Tags

GET/tags

List all tags with usage counts, sorted by frequency.

GET/tags/:tag/notes

List notes with a specific tag. Supports pagination.

Export

GET/notes/:id/export?format=json

Export a note as a downloadable .excalidraw JSON file.

Encrypted notes return HTTP 403.

Version History

All plans include automatic version history. Continuous snapshots are kept for 72 hours, then consolidated into daily snapshots. Free keeps 3 dailies per note, Pro keeps 30, Power keeps 365. Paid plans can also create up to 10 manual checkpoints per note.

GET/notes/:id/versions

List version snapshots for a note.

GET/notes/:id/versions/:versionId

Get a specific version with full canvas data.

POST/notes/:id/versions

Create a manual checkpoint (paid plans, max 10 per note).

POST/notes/:id/versions/:versionId/restore

Restore a note to a previous version. Current state is auto-snapshotted first.

DELETE/notes/:id/versions/:versionId

Delete a manual checkpoint. Only manual checkpoints can be deleted.

Web Clipping

POST/clip

Clip a web page or YouTube video. YouTube URLs are auto-detected.

Body
{
  "url": "https://example.com/article",
  "mode": "text",
  "includeTranscript": false
}

Fields:

  • url (required) — URL to clip
  • mode — "visual" (screenshot + text) or "text" (default)
  • includeTranscript — for YouTube, fetch transcript (quota-limited)

Returns type: "youtube", "visual", or "webpage" depending on the URL and mode.

GET/youtube/quota

Check your monthly YouTube transcript quota.

POST/youtube/transcript

Fetch a YouTube transcript by video ID.

Body
{ "videoId": "dQw4w9WgXcQ" }

Returns HTTP 429 if monthly quota is exceeded.

API Key Management

These endpoints use JWT auth (your login session), not API key auth. They're used by the app to manage your keys.

POST/keys

Create a new API key. Returns the full key once — store it securely.

GET/keys

List your API keys (prefix only, not the full key).

DELETE/keys/:id

Revoke an API key. Cannot be undone.

Error Codes

CodeHTTPMeaning
UNAUTHORIZED401Missing or invalid API key
FORBIDDEN403Not on Power plan, or encrypted note
NOT_FOUND404Resource not found or not owned by you
VALIDATION_ERROR400Invalid request body or parameters
RATE_LIMITED429Rate limit or quota exceeded

Quick Example

curl
curl https://app.omnicanvasnotes.com/api/v1/notes?limit=5 \
  -H "Authorization: Bearer pk_live_your_key_here"
Response
{
  "data": [
    {
      "id": "abc123",
      "title": "Meeting Notes",
      "isPinned": false,
      "isEncrypted": false,
      "tags": ["work"],
      "folderIds": ["folder-1"],
      "lastModified": "2026-03-07T12:00:00.000Z"
    }
  ],
  "error": null,
  "meta": {
    "timestamp": "2026-03-07T12:00:00.000Z",
    "limit": 5,
    "offset": 0,
    "total": 42
  }
}