REST API reference
Endpoints, authentication, idempotency and pagination for the Lynkoria HTTP API.
The SDKs wrap every endpoint below. Use the API directly only for languages without an SDK. The machine-readable contract is the OpenAPI specification, generated from the route definitions.
- Base URL:
https://api.lynkoria.com(staging and self-hosted deployments have their own). - Version: everything is under
/v1. Within v1 only additive changes are made. - Format: JSON request and response bodies; timestamps are ISO 8601 UTC.
- Request IDs: every response carries an
x-request-idheader. Include it when you report a problem.
Authentication
| Caller | Credential | Header |
|---|---|---|
| Your backend | Service key | Authorization: Bearer lynk_live_… |
| User’s device | Messaging token (10 minutes) | Authorization: Bearer <token> |
The project and environment always come from the credential, never from the request body.
Endpoints
The full reference (every operation, parameter, body field, response and error, with the credential and scope it needs) is generated from the OpenAPI specification: HTTP API reference.
| Section | Credential |
|---|---|
| Calls | Service key, scope calls:write |
| Sessions and users | Service key, messaging:write or users:write |
| Messaging | Service key (messaging:write) or messaging token |
| Presence | Messaging token |
| Attachments | Messaging token |
| Push notifications | Service key (messaging:write) or messaging token |
| Recordings | Service key, scope calls:write |
| Console (admin) API | Console session and console role |
Realtime messaging, typing and presence subscriptions use the socket; see events.
Example
curl https://api.lynkoria.com/v1/sessions/messaging-token \
-H "Authorization: Bearer $LYNKORIA_SERVICE_KEY" \
-H "Content-Type: application/json" \
-d '{"userId":"alice","deviceId":"web-1"}'
# {"token":"eyJ…","expiresAt":"2026-11-12T08:40:00.000Z"}Idempotency
| Operation | Key | On repeat |
|---|---|---|
| Create call | productCallId | Returns the active call |
| Create conversation | productConversationId | Returns the existing conversation |
| Send message | clientMessageId | Returns the original message |
Pagination
- Conversations: pass the opaque
nextCursorback ascursor. - Messages:
before_seqpages backwards through history;after_seqreturns change events forwards for catching up. Both acceptlimit.
Errors
Errors use one shape with a stable code; see errors.
{ "error": { "code": "feature_disabled", "message": "…", "requestId": "…" } }Console API
The console uses separate /v1/admin/* endpoints authenticated by a console session (password sign-in; accounts come from the operator CLI) and, where configured, Cloudflare Access. Service keys and messaging tokens are rejected there. Each operation lists the console roles it accepts; see the console API reference and admin access.
Rate limits
Limits per credential and per environment are listed in limits. A limited request gets 429 with code rate_limited (request rate) or quota_exceeded (an environment quota such as concurrent rooms); retry with backoff. A 503 with Retry-After: 1 means a dependency is briefly unavailable.