API Reference

Programmatic access to your Annote notes and annotations.

Quick Start

1. Generate an API Token

  1. Sign in to Annote
  2. Go to Settings → API Tokens
  3. Click “Generate New Token”
  4. Copy your token (you won’t see it again!)

2. Make Your First Request

curl https://api.annote.ai/v1/notes \
  -H "Authorization: Bearer YOUR_TOKEN"

Authentication

Include your token in the Authorization header:

Authorization: Bearer YOUR_TOKEN

JWT Authentication

For user-facing applications, use OAuth2 with JWT tokens.

Endpoints

List Notes

GET /api/v1/notes

Query Parameters:

Example:

curl "https://api.annote.ai/v1/notes?limit=10&tag=philosophy" \
  -H "Authorization: Bearer YOUR_TOKEN"

Response:

{
  "notes": [
    {
      "id": "note_abc123",
      "content": "This is my note",
      "highlight": "Selected text from page",
      "url": "https://example.com/article",
      "tags": ["philosophy", "ethics"],
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T10:30:00Z"
    }
  ],
  "total": 156,
  "limit": 10,
  "offset": 0
}

Search Notes

GET /api/v1/notes/search

Query Parameters:

Example:

curl "https://api.annote.ai/v1/notes/search?q=habit+formation" \
  -H "Authorization: Bearer YOUR_TOKEN"

GET /api/v1/notes/{id}/related

Find notes semantically similar to a given note.

Example:

curl "https://api.annote.ai/v1/notes/note_abc123/related" \
  -H "Authorization: Bearer YOUR_TOKEN"

Create or Update Note

POST /api/v1/notes

Body:

{
  "content": "My note content",
  "highlight": "Selected text",
  "url": "https://example.com/page",
  "tags": ["tag1", "tag2"],
  "collection_id": "collection_xyz"
}

Example:

curl -X POST "https://api.annote.ai/v1/notes" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "content": "Interesting insight about habits",
    "url": "https://example.com/article",
    "tags": ["habits"]
  }'

Delete Note

DELETE /api/v1/notes/{id}

Example:

curl -X DELETE "https://api.annote.ai/v1/notes/note_abc123" \
  -H "Authorization: Bearer YOUR_TOKEN"

PostgREST Query Interface

For advanced queries, use the PostgREST interface:

POST /api/v1/query

Supports the full PostgREST query syntax for complex filtering, ordering, and aggregation.

Code Examples

Python

import requests

API_TOKEN = "your_token_here"
BASE_URL = "https://api.annote.ai/v1"

headers = {
    "Authorization": f"Bearer {API_TOKEN}",
    "Content-Type": "application/json"
}

# Get notes
response = requests.get(f"{BASE_URL}/notes", headers=headers)
notes = response.json()["notes"]

# Search
response = requests.get(
    f"{BASE_URL}/notes/search",
    headers=headers,
    params={"q": "machine learning"}
)
results = response.json()

# Create note
new_note = {
    "content": "Key insight",
    "url": "https://example.com",
    "tags": ["ai"]
}
response = requests.post(
    f"{BASE_URL}/notes",
    headers=headers,
    json=new_note
)

JavaScript

const API_TOKEN = 'your_token_here';
const BASE_URL = 'https://api.annote.ai/v1';

const headers = {
  'Authorization': `Bearer ${API_TOKEN}`,
  'Content-Type': 'application/json'
};

// Get notes
const response = await fetch(`${BASE_URL}/notes`, { headers });
const data = await response.json();

// Create note
const newNote = {
  content: 'My note',
  url: 'https://example.com',
  tags: ['tag1']
};

await fetch(`${BASE_URL}/notes`, {
  method: 'POST',
  headers,
  body: JSON.stringify(newNote)
});

MCP Server Integration

Use Annote with Claude Desktop via Model Context Protocol:

{
  "mcpServers": {
    "annote": {
      "command": "npx",
      "args": ["-y", "@annote/mcp-server"],
      "env": {
        "ANNOTE_API_TOKEN": "your_token_here"
      }
    }
  }
}

See the MCP documentation for details.

Rate Limits

Rate limit headers included in every response:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1642345600

Error Handling

Error Response Format:

{
  "error": {
    "code": "invalid_request",
    "message": "Missing required field: content"
  }
}

Common Error Codes:

Export & Import

Export All Notes

Coming Soon - Full export to JSON or Markdown.

For now, use the API to fetch all notes with pagination:

curl "https://api.annote.ai/v1/notes?limit=200&offset=0"

Import Notes

Coming Soon - Bulk import from JSON or Markdown.

For now, use the create endpoint in a loop.

Webhooks

Coming Soon - Get notified when notes are created or updated.

Support