Skip to main content
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

StatusMeaning
200 OKThe request succeeded and the response body contains the result.
201 CreatedA new resource was successfully created.
400 Bad RequestThe request was malformed or failed validation. Check the message field.
401 UnauthorizedNo valid credentials were provided. Check your Authorization header.
403 ForbiddenYour credentials are valid but do not have permission for this action.
404 Not FoundThe requested resource does not exist or is not accessible to you.
409 ConflictThe request conflicts with existing data (for example, a duplicate resource).
429 Too Many RequestsYou 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.

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.