Skip to Content
LYNKORIADocs

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-id header. Include it when you report a problem.

Authentication

CallerCredentialHeader
Your backendService keyAuthorization: Bearer lynk_live_…
User’s deviceMessaging 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.

SectionCredential
CallsService key, scope calls:write
Sessions and usersService key, messaging:write or users:write
MessagingService key (messaging:write) or messaging token
PresenceMessaging token
AttachmentsMessaging token
Push notificationsService key (messaging:write) or messaging token
RecordingsService key, scope calls:write
Console (admin) APIConsole 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

OperationKeyOn repeat
Create callproductCallIdReturns the active call
Create conversationproductConversationIdReturns the existing conversation
Send messageclientMessageIdReturns the original message

Pagination

  • Conversations: pass the opaque nextCursor back as cursor.
  • Messages: before_seq pages backwards through history; after_seq returns change events forwards for catching up. Both accept limit.

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.

On this page