API Reference

Overview

The Orga AI API (v1) provides HTTP endpoints for setting up secure, real-time sessions with the Orga AI model via WebRTC.

These endpoints are designed for backend proxy implementation to prevent API key exposure on the client side (e.g., in React or React Native apps). Use them to obtain ephemeral tokens and ICE configs, then pass results to the SDK for client-side handling. For real-time events over DataChannels, see React Native SDK API Reference > Core or React SDK API Reference > Core

Prefer the SDK for integration— it abstracts proxy calls with hooks like useOrgaAI() for easy iteration without raw HTTP.

Base URL

The base URL for the Orga AI API is https://api.orga-ai.com/v1/.

Endpoints

POST /realtime/client-secrets?email=${encodeURIComponent("user@example.com)}

Exchange API key for ephemeral key. Use in proxy to secure keys.

• Method: POST

• Headers: Authorization: Bearer <your-api-key>

• Request Body: None

• Response: { "ephemeral_token": "eyJ...", "token_type": "bearer", "expires_at": "2025-09..." }

• Errors:

• Rate Limits: [Update with accurate: e.g., 100 req/min, burst 20]. Backoff on 429.

GET /realtime/ice-config

Retrieve STUN/TURN servers for WebRTC. Call after token via proxy.

• Method: GET

• Headers: Authorization: Bearer <ephemeral-token>

• Query Params: None

• Response (200 OK): [{ "urls": "stun:stun.example.com:3478" }, { "urls": "turn:turn.example.com:3478", "username": "...", "credential": "..." }]

• Errors:

• Rate Limits: [Update: e.g., 60 req/min]. Exponential backoff recommended.

POST /realtime/calls

Sends an SDP offer and ICE candidates to initiate a WebRTC session. Returns an SDP answer to complete the connection.

• Method: POST

• Headers: Authorization: Bearer <ephemeral-token>

• Request Body:

{
    offer: {
    sdp: "<SDP_OFFER>",
    type: "offer",
    candidates: [
      {
        candidate: "<CANDIDATE_STRING>",
        sdpMid: "<SDP_MID>",
        sdpMLineIndex: <INDEX>,
        usernameFragment: "<UFRAG>"
      }
    ]
  },
    params: {
      voice: "alloy",
      model: "orga-1-beta",
      temperature: 0.5,
      return_transcription: true,
      history: true,
      instructions: "Respond in a friendly tone",
      modalities: ["audio", "video"],
    },
};

• Response: [{ "urls": "stun:stun.example.com:3478" }, { "urls": "turn:turn.example.com:3478", "username": "...", "credential": "..." }]

• Errors:

• Rate Limits: [Update: e.g., 60 req/min]. Exponential backoff recommended.

Example Implementation:

const ORGA_API_KEY = process.env.ORGA_API_KEY;

const fetchIceServers = async (ephemeralToken: string) => {
  const URL = `https://api.orga-ai.com/v1/realtime/ice-config`;
  try {
    const iceServersResponse = await fetch(URL, {
      method: "GET",
      headers: {
        Authorization: `Bearer ${ephemeralToken}`,
      },
    });
    const data = await iceServersResponse.json();
    return data.iceServers;
  } catch (error) {
    console.error("Error fetching ice servers:", error);
    throw error;
  }
};

export async function GET(request: Request) {
const USER_EMAIL = process.env.USER_EMAIL
  if (!ORGA_API_KEY) {
    return Response.json({error: "Missing environment variables"}, { status: 500 });
  }

  try {
    const apiUrl = `https://api.orga-ai.com/v1/realtime/client-secrets?email=${encodeURIComponent(USER_EMAIL)}`;
    const ephemeralResponse = await fetch(apiUrl, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${ORGA_API_KEY}`
      },
    });
    
    if (!ephemeralResponse.ok) {
      throw new Error('Failed to fetch ephemeral token');
    }

    const { ephemeral_token } = await ephemeralResponse.json();
    const iceServers = await fetchIceServers(ephemeral_token);
    
    return Response.json({ ephemeralToken: ephemeral_token, iceServers }, {status: 200})
  } catch (error) {
    return Response.json({error: "Internal server error"}, { status: 500 });
  }
}

Next Steps

See SDK docs for more detailed integration guides and references