Orga AI API Overview
The Orga AI REST API provides direct access to the same real-time infrastructure that powers our SDKs.
You can securely create and manage real-time voice & video sessions, configure connectivity, and issue short-lived credentials to your clients.
While most developers use our SDKs for higher-level integration, this section documents the raw HTTP endpoints that underpin them.
The SDKs internally call these endpoints — understanding them can help when debugging, customizing integrations, or writing language-specific clients.
Base URL
All API endpoints live under the following base URL:
https://api.orga-ai.com/v1All endpoints use HTTPS and communicate using standard JSON request and response bodies.
Call Flow Summary
Before a client can start a real-time session, it must obtain temporary credentials and network configuration from Orga.
The process typically involves three API calls — two from your server, one from your client.
| Step | Endpoint | Description | Auth Header | Called From |
|---|---|---|---|---|
| 1 | POST /v1/realtime/client-secrets | Exchanges your long-lived API key for a short-lived ephemeral token (JWT). | Authorization: Bearer {API_KEY} | Server |
| 2 | GET /v1/realtime/ice-config | Retrieves STUN/TURN ICE server configuration to enable WebRTC connectivity. | Authorization: Bearer {EPHEMERAL_TOKEN} | Server |
| 3 | POST /v1/realtime/calls | Establishes a new real-time session between your client and Orga AI by sending an SDP offer. Returns an answer that completes the WebRTC handshake. | Authorization: Bearer {EPHEMERAL_TOKEN} | Client |
The SDKs abstract all three of these calls through a single initialization flow.
Authentication Overview
Orga distinguishes between two types of credentials:
| Type | Scope | Used For | Lifetime | Who Stores It |
|---|---|---|---|---|
| API Key | Permanent | Authenticates your server with Orga | Long-lived | Secret (Server-only) |
| Ephemeral Token (JWT) | Temporary | Authenticates clients via WebRTC | Short-lived (≈1 min) | Transient (Client) |
- The Server exchanges the API key for an ephemeral token using the
/client-secretsendpoint. - The Client uses that ephemeral token to establish a WebRTC session via
/calls.
Never embed your API key in client-side code or mobile apps. Always call the Orga API from a secure backend or proxy.
Request Format
All Orga API endpoints accept application/json bodies.
Example request (Node or curl):
curl https://api.orga-ai.com/v1/realtime/client-secrets \
-H "Authorization: Bearer sk_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"expires_in": 60
}'Response Format & Errors
Responses return standard HTTP status codes:
| Code | Meaning |
|---|---|
| 200 OK | Success |
| 400 Bad Request | Invalid request data |
| 401 Unauthorized | Missing or invalid token |
| 403 Forbidden | Invalid credential context |
| 500 Internal Server Error | Unhandled server error |
Versioning
The current stable API version is v1.
Future versions will be released under /v2, /v3, etc., but breaking changes will always be versioned.
📘 Tip: Orga SDKs automatically stay aligned with the current stable API version.