> ## Documentation Index
> Fetch the complete documentation index at: https://okl-ink.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Overview

> Authentication, base URLs, error formats, and scopes for the okl.ink v1 REST API.

# REST API v1 Overview

The okl.ink REST API allows developers to automate page generation, link management, theme configuration, and analytics retrieval.

***

## Base URL

| Environment           | Base URL                       |
| :-------------------- | :----------------------------- |
| **Production**        | `https://okl.ink/api/v1`       |
| **Local Development** | `http://localhost:3000/api/v1` |

***

## Authentication

All v1 API requests must include a Bearer token in the `Authorization` header or an `X-API-Key` header:

```http theme={null}
Authorization: Bearer <your-api-token>
```

```bash theme={null}
curl https://okl.ink/api/v1/pages \
  -H "Authorization: Bearer YOUR_API_TOKEN"
```

***

## Token Scopes

API tokens enforce granular permissions:

| Scope           | Description                                         |
| :-------------- | :-------------------------------------------------- |
| `pages:read`    | Read page metadata, themes, and links               |
| `pages:write`   | Create, update, publish, or change themes for pages |
| `links:write`   | Add, update, or remove links from pages             |
| `tokens:manage` | List or revoke API tokens                           |

***

## Standard Error Response

When an error occurs, the API returns standard HTTP status codes and a JSON error object:

```json theme={null}
{
  "error": "That slug is already taken."
}
```

### HTTP Status Codes

| Code               | Meaning                                            |
| :----------------- | :------------------------------------------------- |
| `200 OK`           | Request succeeded                                  |
| `201 Created`      | Resource created successfully                      |
| `400 Bad Request`  | Validation failure or malformed payload            |
| `401 Unauthorized` | Missing, invalid, revoked, or expired token        |
| `403 Forbidden`    | Token lacks the required scope for this operation  |
| `404 Not Found`    | Resource does not exist or belongs to another user |
| `409 Conflict`     | Slug collision or unique constraint violation      |
| `500 Server Error` | Unexpected server exception                        |