Bookmark.fm API Documentation

Version 1.0

Table of Contents

• Overview
• Authentication
• Endpoints
• Processing States
• Rate Limits
• Error Responses
• Example Implementations

Overview

The Bookmark.fm API provides programmatic access to create and retrieve bookmarks. All API endpoints require authentication using a bearer token.

Authentication

All API requests must include an Authorization header with a bearer token:

Authorization: Bearer YOUR_API_KEY

Your API key is automatically generated when your account is created. Sign in to view your API key.

Endpoints

{
  "id_token": "YOUR_GOOGLE_ID_TOKEN"
}

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "image": "https://lh3.googleusercontent.com/...",
    "avatar_url": "https://cdn.example.com/avatars/1.jpg",
    "api_key": "uak_062825abcdef1234"
  }
}

{
  "user": {
    "id": 1,
    "name": "John Doe",
    "email": "john@example.com",
    "image": "https://lh3.googleusercontent.com/...",
    "avatar_url": "https://cdn.example.com/avatars/1.jpg",
    "episode_length_preference": "medium",
    "bookmarks_count": 87,
    "created_at": "2025-01-15T10:30:00Z",
    "updated_at": "2025-06-28T09:45:00Z"
  }
}

{
  "bookmarks": [
    {
      "id": 123,
      "url": "https://example.com/article",
      "title": "Example Article",
      "description": "An interesting article about...",
      "category": "tech",
      "processing_state": "completed",
      "processing_progress": 100,
      "processing_completed_segments": 5,
      "processing_total_segments": 5,
      "has_audio": true,
      "audio_url": "https://cdn.example.com/audio/123.mp3",
      "has_artwork": true,
      "artwork_url": "https://cdn.example.com/artwork/123.png",
      "created_at": "2025-06-28T10:30:00Z",
      "updated_at": "2025-06-28T10:35:00Z"
    }
  ],
  "pagination": {
    "current_page": 1,
    "total_pages": 5,
    "total_count": 87,
    "per_page": 20
  }
}

{
  "bookmark": {
    "url": "https://example.com/article-to-bookmark"
  }
}

{
  "bookmark": {
    "id": 124,
    "url": "https://example.com/article",
    "title": null,
    "description": null,
    "category": null,
    "processing_state": "pending",
    "processing_progress": 0,
    "processing_completed_segments": 0,
    "processing_total_segments": 0,
    "has_audio": false,
    "audio_url": null,
    "has_artwork": false,
    "artwork_url": null,
    "created_at": "2025-06-28T11:00:00Z",
    "updated_at": "2025-06-28T11:00:00Z"
  }
}

Processing States

Bookmarks go through several processing states:

• pending Initial state, waiting to be processed
• downloading Downloading and parsing the webpage
• classifying Using AI to classify the content
• generating_transcript Generating podcast transcript
• generating_audio Creating audio using text-to-speech
• completed Processing finished successfully
• failed Processing failed (check error logs)

Rate Limits

API requests are subject to rate limiting. Current limits:

• 100 requests per minute per API key
• 1000 requests per day per API key

Error Responses

{
  "error": "Unauthorized"
}

{
  "errors": ["URL can't be blank"]
}

{
  "error": "Rate limit exceeded"
}

Example Implementations

import requests

API_KEY = "your_api_key_here"
BASE_URL = "https://bookmark.fm/api/v1"

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

# Get account info
response = requests.get(f"{BASE_URL}/account", headers=headers)
account = response.json()

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

# Create bookmark
data = {"bookmark": {"url": "https://example.com/article"}}
response = requests.post(f"{BASE_URL}/bookmarks", json=data, headers=headers)
new_bookmark = response.json()

const API_KEY = 'your_api_key_here';
const BASE_URL = 'https://bookmark.fm/api/v1';

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

// Get account info
fetch(`${BASE_URL}/account`, { headers })
  .then(response => response.json())
  .then(data => console.log(data));

// Get bookmarks
fetch(`${BASE_URL}/bookmarks`, { headers })
  .then(response => response.json())
  .then(data => console.log(data));

// Create bookmark
fetch(`${BASE_URL}/bookmarks`, {
  method: 'POST',
  headers,
  body: JSON.stringify({
    bookmark: { url: 'https://example.com/article' }
  })
})
  .then(response => response.json())
  .then(data => console.log(data));