Documentation

API

Authentication

All API requests must include your API key in the X-Api-Key header. You can create API keys in your settings.

X-Api-Key: your-api-key

Keep your API key secure! Don't share it or expose it in client-side code.

Base URL

All API requests should be made to: https://bookmarkmanager.com/api/v1

Response Format

All responses are returned as JSON. Successful responses typically include the requested data, while error responses include error details.

Success Response Example

{
    "id": "abc123",
    "url": "https://example.com",
    "title": "Example Website",
    "description": "An example website",
    "tags": ["example", "demo"],
    "createdAt": "2023-06-15T12:30:45Z",
    "updatedAt": "2023-06-15T12:30:45Z"
}

Error Response Example

{
    "error": "Invalid request",
    "message": "The URL is required",
    "code": 400
}

Endpoints

List Bookmarks

GET /bookmarks

Returns a list of all your bookmarks.

Response

Status: 200 OK

Returns an array of bookmark objects.

Search Bookmarks (AI)

GET /bookmarks/search?q=your+query
X-Api-Key: your-api-key

Semantic search over your bookmarks. Finds bookmarks by meaning rather than exact keywords and returns the closest matches first.

Query Parameters

q *required - The search query (max 500 characters)
limit optional - Maximum number of results, 1-100 (default 20)

Response

Status: 200 OK, 400 Bad Request, or 429 Too Many Requests

Returns an array of bookmark objects, each with an additional score field (higher means more similar). Bookmarks saved moments ago may not be searchable yet, as embeddings are generated asynchronously.

Get a Bookmark

GET /bookmarks/:id

Returns a single bookmark by ID.

Response

Status: 200 OK or 404 Not Found

Returns a bookmark object or an error if the bookmark doesn't exist.

Create a Bookmark

POST /api/v1/bookmarks
Content-Type: application/json
X-Api-Key: your-api-key

{
    "url": "https://example.com",
    "title": "Example Website",
    "description": "An example website",
    "tags": ["example", "demo"]
}

Creates a new bookmark.

Request Body Fields

url *required - The URL to bookmark
title optional - Title of the bookmark (extracted from the webpage if not provided)
description optional - Description of the bookmark (extracted from the webpage if not provided)
tags optional - Array of tag strings

Response

Status: 201 Created or 400 Bad Request

Returns the created bookmark object or an error.

Update a Bookmark

PUT /api/v1/bookmarks/:id
Content-Type: application/json
X-Api-Key: your-api-key

{
    "url": "https://example.com",
    "title": "Updated Title",
    "description": "Updated description",
    "tags": ["updated", "tags"]
}

Updates an existing bookmark. All fields are required.

Response

Status: 200 OK, 400 Bad Request, or 404 Not Found

Returns the updated bookmark object or an error.

Partially Update a Bookmark

PATCH /api/v1/bookmarks/:id
Content-Type: application/json
X-Api-Key: your-api-key

{
    "title": "Updated Title",
    "tags": ["updated", "tags"]
}

Updates only specific fields of a bookmark. Only include the fields you want to modify.

Response

Status: 200 OK, 400 Bad Request, or 404 Not Found

Returns the updated bookmark object or an error.

Delete a Bookmark

DELETE /bookmarks/:id
X-Api-Key: your-api-key

Permanently deletes a bookmark.

Response

Status: 200 OK or 404 Not Found

Returns the deleted bookmark or an error if the bookmark doesn't exist.