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.

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.

Authentication

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

Authorization: Bearer <token>

Scopes are enforced per endpoint, and plan gating still applies on top of scopes. See Authentication.

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.

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.

Example — create a draft

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

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'

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

Response fields above are illustrative.

Example — publish now

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

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.

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.

Live networks: LinkedIn and X. Other networks are listed but pending — analytics for them are not available today.

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 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 — API keys, scopes, and headers.

• MCP connector — the same actions exposed to AI clients.

• Rate limits & errors — error and rate-limit semantics.