Realtime API - Client Documentation

Base URL: https://api.scriptix.io/api/v4/realtime

Authentication

All endpoints require API key authentication:

x-zoom-s2t-key: your-api-token-here

Endpoints

1. Initialize Realtime Service

Endpoint: POST /api/v4/realtime/initialize

Authentication: Requires admin scope

Description: Initializes the realtime service and ensures it's running and ready. Behavior depends on auto-scaling configuration: - If auto-scaling enabled: Scales up service if at 0 replicas and waits for ready - If auto-scaling disabled: Returns endpoint immediately (assumes manual management)

Request Example (curl):

curl -X POST "https://api.scriptix.io/api/v4/realtime/initialize" \
  -H "x-zoom-s2t-key: your-api-token" \
  -H "Content-Type: application/json"

Request Example (Python):

import requests

url = "https://api.scriptix.io/api/v4/realtime/initialize"
headers = {
    "x-zoom-s2t-key": "your-api-token",
    "Content-Type": "application/json"
}

response = requests.post(url, headers=headers)
data = response.json()
print(data)

Request Example (JavaScript/Node.js):

const response = await fetch('https://api.scriptix.io/api/v4/realtime/initialize', {
  method: 'POST',
  headers: {
    'x-zoom-s2t-key': 'your-api-token',
    'Content-Type': 'application/json'
  }
});

const data = await response.json();
console.log(data);

Response (200 OK):

{
  "status": "ready",
  "message": "Realtime service is ready for connections",
  "ready": true,
  "endpoint": "wss://realtime.scriptix.io/v2/realtime"
}

Response Fields: - status (string): Status of the realtime service ("ready") - message (string): Human-readable status message - ready (boolean): Whether the service is ready for connections - endpoint (string): WebSocket endpoint URL for realtime connections

2. Get Realtime Service Status

Endpoint: GET /api/v4/realtime/status

Description: Gets the current status of the realtime service. This is a lightweight check that doesn't trigger scaling - use /initialize to start the service if needed.

Request Example (curl):

curl -X GET "https://api.scriptix.io/api/v4/realtime/status" \
  -H "x-zoom-s2t-key: your-api-token"

Request Example (Python):

import requests

url = "https://api.scriptix.io/api/v4/realtime/status"
headers = {
    "x-zoom-s2t-key": "your-api-token"
}

response = requests.get(url, headers=headers)
data = response.json()
print(f"Ready: {data['ready']}, Status: {data['status']}")

Request Example (JavaScript/Node.js):

const response = await fetch('https://api.scriptix.io/api/v4/realtime/status', {
  method: 'GET',
  headers: {
    'x-zoom-s2t-key': 'your-api-token'
  }
});

const data = await response.json();
console.log(`Ready: ${data.ready}, Status: ${data.status}`);

Response (200 OK) - Service Ready:

{
  "status": "ready",
  "message": "Realtime service is ready",
  "ready": true,
  "endpoint": "wss://realtime.scriptix.io/v2/realtime"
}

Response (200 OK) - Service Scaled Down:

{
  "status": "scaled_down",
  "message": "Realtime service is scaled down. Call /initialize to start it.",
  "ready": false,
  "endpoint": "wss://realtime.scriptix.io/v2/realtime"
}

Response (200 OK) - Service Starting:

{
  "status": "starting",
  "message": "Realtime service is starting up",
  "ready": false,
  "endpoint": "wss://realtime.scriptix.io/v2/realtime"
}

Response Fields: - status (string): Status of the realtime service ("ready", "scaled_down", or "starting") - message (string): Human-readable status message - ready (boolean): Whether the service is ready for connections - endpoint (string): WebSocket endpoint URL for realtime connections

Error Responses

401 Unauthorized

{
  "detail": "Not authenticated"
}

Cause: Missing or invalid authentication credentials

403 Forbidden

{
  "detail": "Not enough permissions"
}

Cause: Valid credentials but insufficient scope/role permissions

500 Internal Server Error

{
  "detail": "Failed to initialize realtime service: <error details>"
}

Cause: Server-side error during processing

503 Service Unavailable

{
  "detail": "Realtime service failed to start"
}

Cause: Service initialization failed (only for /initialize endpoint)

Typical Workflow

Check Status (optional): Call GET /status to check if service is available
Initialize Service: Call POST /initialize to ensure service is running
Connect to WebSocket: Use the endpoint URL from the response to establish WebSocket connection
Begin Realtime Transcription: Send audio data through WebSocket connection