API Reference

The Counslr SOS API provides REST endpoints for platform management, session lifecycle, and SOS operations, and a WebSocket API for real-time location exchange during emergencies.

Interactive API Reference

The full API specification is available via the interactive Swagger UI, which lets you explore endpoints, view request/response schemas, and try out API calls.

Authentication

The API uses three authentication methods:

API Key (X-API-Key header)

Server-to-server endpoints require a secret API key:

X-API-Key: sk_live_<kid8>_<secret32>

Keys follow the Stripe model. The key prefix identifies the platform; the full key is verified against a bcrypt hash. Secret keys (sk_) can access all endpoints. Publishable keys (pk_) are restricted to client-side operations.

JWT Bearer Token (Authorization header)

SDK client endpoints require a JWT bearer token:

Authorization: Bearer <jwt-token>

Tokens are HS256-signed and scoped to a platform, containing claims for platform_id, session_id, role (patient or counselor), and exp.

Admin Key (X-Admin-Key header)

Administrative endpoints (platform registration, usage metering) require the admin key:

X-Admin-Key: <admin-key>

Error Responses

All errors follow a consistent format:

{
  "error": {
    "code": "session_not_found",
    "message": "No active session found with the given ID"
  }
}

See the Swagger UI for the complete list of error codes and HTTP status codes.

Rate Limiting

All REST endpoints are rate limited per platform. When the limit is exceeded, the API returns HTTP 429 with an optional Retry-After header. Both the Patient and Counselor SDKs automatically retry rate-limited requests with exponential backoff.