> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bkmark.it/llms.txt
> Use this file to discover all available pages before exploring further.

# Bkmark REST API Reference — Overview and Conventions

> A complete reference for the Bkmark REST API — base URL, authentication, request format, error codes, pagination, and quick links to deeper guides.

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:

```bash theme={null}
Authorization: Bearer <token-or-key>
```

Session cookies used by the Bkmark web app are **not** valid for API requests. See the [Authentication](/api/authentication) and [API Keys](/api/api-keys) pages for full details.

## Request Format

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

```bash theme={null}
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:

```json theme={null}
{
  "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:

```json theme={null}
{
  "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:

```bash theme={null}
curl https://api.bkmark.it/api/v1/bookmarks \
  -H "Authorization: Bearer YOUR_TOKEN_OR_KEY" \
  -H "Accept: application/json"
```

```json theme={null}
{
  "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

<CardGroup cols={2}>
  <Card title="Authentication" icon="key" href="/api/authentication">
    Learn how to obtain and use OAuth2 Bearer tokens and API keys to authorize requests.
  </Card>

  <Card title="API Keys" icon="terminal" href="/api/api-keys">
    Create, list, update, and revoke API keys for personal automation workflows.
  </Card>

  <Card title="Rate Limits" icon="gauge" href="/api/rate-limits">
    Understand per-endpoint rate limits and how to handle 429 responses gracefully.
  </Card>

  <Card title="OAuth2 Authorization" icon="lock" href="/api/oauth/authorization">
    Walk through the full OAuth2 Authorization Code flow with PKCE step by step.
  </Card>
</CardGroup>