Bkmark REST API Reference — Overview and Conventions

The Bkmark API is a REST API that lets you manage bookmarks, tags, and groups programmatically. All requests go to a single base URL, accept JSON bodies, and return consistent JSON responses. This page covers the core conventions you need before making your first call.

Base URL

Every API endpoint is rooted at:

https://api.bkmark.it/api/v1

For local development against a self-hosted instance, replace this with http://localhost:3000/api/v1.

Authentication

All API requests require an Authorization header. Bkmark supports two methods:

OAuth2 Bearer Token — the recommended choice for third-party integrations. You obtain a token by completing the OAuth2 Authorization Code flow on behalf of a user.
API Key — the right choice for personal scripts and automation. You generate a key in Settings → Security → API Keys and use it directly.

Both methods use the same header format:

Authorization: Bearer <token-or-key>

Session cookies used by the Bkmark web app are not valid for API requests. See the Authentication and API Keys pages for full details.

Request Format

Send request bodies as JSON and include the appropriate Content-Type header:

Content-Type: application/json

Query parameters (for filtering, pagination, etc.) are passed in the URL as standard key-value pairs.

Responses

Successful responses return HTTP 200 OK or 201 Created. Endpoints that return a list of resources wrap them in an envelope:

{
  "data": [...],
  "nextCursor": "cursor_abc123"
}

Pagination

List endpoints use cursor-based pagination. To retrieve the next page of results, pass the nextCursor value from the previous response as the cursor query parameter:

GET /api/v1/bookmarks?cursor=cursor_abc123

When nextCursor is null, you have reached the last page and there are no more results.

Error Format

All error responses share a consistent JSON structure:

{
  "error": "error_code",
  "message": "A human-readable description of what went wrong.",
  "statusCode": 400
}

Use error for programmatic error handling and message for displaying context to users or logging.

HTTP Status Codes

Status	Meaning
`200 OK`	The request succeeded and the response body contains the result.
`201 Created`	A new resource was successfully created.
`400 Bad Request`	The request was malformed or failed validation. Check the `message` field.
`401 Unauthorized`	No valid credentials were provided. Check your `Authorization` header.
`403 Forbidden`	Your credentials are valid but do not have permission for this action.
`404 Not Found`	The requested resource does not exist or is not accessible to you.
`409 Conflict`	The request conflicts with existing data (for example, a duplicate resource).
`429 Too Many Requests`	You have exceeded the rate limit for this endpoint.

Sample Request and Response

The following example retrieves your first page of bookmarks using a Bearer token:

curl https://api.bkmark.it/api/v1/bookmarks \
  -H "Authorization: Bearer YOUR_TOKEN_OR_KEY" \
  -H "Accept: application/json"

{
  "data": [
    {
      "id": "01J2K8M4N5P6Q7R8S9T0U1V2W3",
      "url": "https://example.com/article",
      "title": "An Example Article",
      "tags": ["reading", "tech"],
      "createdAt": "2024-11-01T09:00:00.000Z"
    }
  ],
  "nextCursor": "01J2K8M4N5P6Q7R8S9T0U1V2W4"
}

To fetch the next page, append ?cursor=01J2K8M4N5P6Q7R8S9T0U1V2W4 to the URL.

Quick Links

Authentication

Learn how to obtain and use OAuth2 Bearer tokens and API keys to authorize requests.

API Keys

Create, list, update, and revoke API keys for personal automation workflows.

Rate Limits

Understand per-endpoint rate limits and how to handle 429 responses gracefully.

OAuth2 Authorization

Walk through the full OAuth2 Authorization Code flow with PKCE step by step.

​Base URL

​Authentication

​Request Format

​Responses

​Pagination

​Error Format

​HTTP Status Codes

​Sample Request and Response

​Quick Links

Authentication

API Keys

Rate Limits

OAuth2 Authorization

Base URL

Authentication

Request Format

Responses

Pagination

Error Format

HTTP Status Codes

Sample Request and Response

Quick Links