> For the complete documentation index, see [llms.txt](https://ovion-studio.gitbook.io/keryo-docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://ovion-studio.gitbook.io/keryo-docs/developers/api-reference.md).

# API reference

Keryo REST API endpoints by resource, with scopes and example requests.

This reference lists the Keryo REST API endpoints, organized by resource. Each table gives the HTTP method, path, required scope (if any), and a short description. All paths are relative to the base URL — `https://api.keryo.io` in production, `http://localhost:3001` in development.

{% hint style="info" %}
Request and response bodies are **illustrative** except where a specific shape is documented (e.g. `{name, scopes}` when creating an API key). Treat field names in examples as guidance, not a contract.
{% endhint %}

## Authentication

Send an API key (or OAuth 2.1 access token) as a Bearer token:

```http
Authorization: Bearer <token>
```

Scopes are enforced per endpoint, and **plan gating still applies** on top of scopes. See [Authentication](/keryo-docs/developers/authentication.md).

## Endpoint groups (mount prefixes)

The backend mounts routes under these prefixes:

| Prefix                                                                                         | Access                                           |
| ---------------------------------------------------------------------------------------------- | ------------------------------------------------ |
| `/auth`, `/feedback`, `/oauth`, `/.well-known/oauth-authorization-server`                      | Public                                           |
| `/users`, `/admin`, `/stripe`                                                                  | Protected (JWT), no active subscription required |
| `/clients`, `/posts`, `/templates`, `/report-templates`, `/github`, `/statistics`, `/api-keys` | Protected + active subscription required         |

## Clients

Client workspaces. **All `/clients` endpoints require the `accounts:read` scope.**

| Method   | Path              | Scope           | Description                |
| -------- | ----------------- | --------------- | -------------------------- |
| `GET`    | `/clients`        | `accounts:read` | List client workspaces.    |
| `POST`   | `/clients`        | `accounts:read` | Create a client workspace. |
| `GET`    | `/clients/:id`    | `accounts:read` | Get a single client.       |
| `PUT`    | `/clients/:id`    | `accounts:read` | Update a client.           |
| `DELETE` | `/clients/:id`    | `accounts:read` | Delete a client.           |
| `POST`   | `/clients/select` | `accounts:read` | Set the active workspace.  |

## Posts

Post creation, media, scheduling, and publishing.

| Method | Path                                | Scope / requirement | Description                                        |
| ------ | ----------------------------------- | ------------------- | -------------------------------------------------- |
| `GET`  | `/posts`                            | `posts:read`        | List posts.                                        |
| `POST` | `/posts`                            | `posts:write`       | Create a draft (multipart; supports images).       |
| `POST` | `/posts/import`                     | Freelance+          | Import existing posts.                             |
| `PUT`  | `/posts/:id`                        | —                   | Update post content.                               |
| `POST` | `/posts/send/:id`                   | `posts:publish`     | Publish now (irreversible).                        |
| `PUT`  | `/posts/schedule/:id`               | `posts:publish`     | Schedule or reschedule for a future ISO-8601 time. |
| `POST` | `/posts/refactor`                   | —                   | AI re-adapts/rewrites content.                     |
| `POST` | `/posts/retry/:id`                  | —                   | Retry a failed publish.                            |
| `POST` | `/posts/youtube/video/init/:id`     | —                   | Start a YouTube resumable upload session.          |
| `POST` | `/posts/youtube/video/complete/:id` | —                   | Finalize a YouTube resumable upload.               |

Media sub-routes exist for attaching **image**, **video**, and **PDF** files to a post.

{% hint style="info" %}
**YouTube uploads go straight to YouTube.** Large YouTube videos (up to \~15 GB) upload directly from the browser to YouTube via a **resumable session** and are never stored on Keryo's side. YouTube is **coming soon** — LinkedIn and X are the live networks today.
{% endhint %}

### Example — create a draft

Drafts are created via multipart (so you can attach media in the same request):

```bash
curl -X POST https://api.keryo.io/posts \
  -H "Authorization: Bearer <your-api-key>" \
  -F 'content=Hello from the Keryo API' \
  -F 'image=@./cover.png'
```

```json
{
  "id": "post_123",
  "status": "draft"
}
```

> *Response fields above are illustrative.*

### Example — publish now

```bash
curl -X POST https://api.keryo.io/posts/send/post_123 \
  -H "Authorization: Bearer <your-api-key>"
```

{% hint style="warning" %}
Publishing is **irreversible** and **rate-limited**. To publish later instead, use `PUT /posts/schedule/:id` with a future ISO-8601 datetime. See [Rate limits & errors](/keryo-docs/developers/rate-limits-and-errors.md).
{% endhint %}

## Statistics

Per-platform analytics. **Requires the `stats:read` scope and a Studio (or higher) plan.**

| Method | Path                             | Scope / requirement   | Description                    |
| ------ | -------------------------------- | --------------------- | ------------------------------ |
| `GET`  | `/statistics/linkedin`           | `stats:read` + Studio | Current LinkedIn analytics.    |
| `GET`  | `/statistics/x`                  | `stats:read` + Studio | Current X analytics.           |
| `GET`  | `/statistics/snapshots/linkedin` | `stats:read` + Studio | Historical LinkedIn snapshots. |
| `GET`  | `/statistics/snapshots/x`        | `stats:read` + Studio | Historical X snapshots.        |

{% hint style="info" %}
**Live networks:** LinkedIn and X. Other networks are listed but **pending** — analytics for them are not available today.
{% endhint %}

## Templates & report templates

| Prefix              | Description                      |
| ------------------- | -------------------------------- |
| `/templates`        | Reusable post templates.         |
| `/report-templates` | Templates for analytics reports. |

Both are protected and require an active subscription. Endpoint shapes follow the same conventions (list, create, read, update, delete).

## API keys

Managed via `/api-keys` (session/web-app only). See [Authentication](/keryo-docs/developers/authentication.md) for the full detail — an API key cannot manage keys.

## Stripe

Billing endpoints are mounted under `/stripe` (Stripe Checkout for subscribing, Stripe Billing Portal for managing/cancelling). This group is protected (JWT) but does **not** require an active subscription, so users can subscribe from within it. Stripe keys never touch the client.

## Auth

Public authentication endpoints under `/auth`:

| Method | Path                      | Description                                |
| ------ | ------------------------- | ------------------------------------------ |
| `POST` | `/auth/magic-link`        | Request a passwordless magic-link email.   |
| `POST` | `/auth/magic-link/verify` | Verify the magic link and start a session. |

GitHub social login is also available. Sessions are cookie/JWT based and carry full access with no scopes.

## Related pages

* [Authentication](/keryo-docs/developers/authentication.md) — API keys, scopes, and headers.
* [MCP connector](/keryo-docs/developers/mcp-connector.md) — the same actions exposed to AI clients.
* [Rate limits & errors](/keryo-docs/developers/rate-limits-and-errors.md) — error and rate-limit semantics.