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: 204 No Content or 404 Not Found

Returns no content on success or an error if the bookmark doesn't exist.

Integration Examples

Zapier Integration

You can use Zapier to automate bookmark creation. For example, you could create a Zap that:

  • Creates a bookmark when you star a GitHub repository
  • Saves links from your liked tweets
  • Bookmarks articles you save in Pocket or Instapaper

Use the "Webhooks by Zapier" action with the POST endpoint to create bookmarks.

Make Integration

Make.com (formerly Integromat) can be used similarly to Zapier. Use the HTTP module to make requests to the API.

cURL Example

curl -X POST "https://bookmarkmanager.com/api/v1/bookmarks" \
-H "Content-Type: application/json" \
-H "X-Api-Key: your-api-key" \
-d '{"url": "https://example.com", "tags": ["example"]}'