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.

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.