Skip to main content

Documentation Index

Fetch the complete documentation index at: https://developer.kallglot.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Authentication

Every programmatic call uses an organization API key. Sign up at kallglot.com, open the Developer Portal, and create keys per environment (sk_live_* vs sk_test_*).

​
API Keys

Every API key belongs to a single organization.

​
Key Types

TypePrefixUsage
Livesk_live_Production traffic
Testsk_test_Test or sandbox traffic

​
Why calls fail (401, 402, 403)

Typical gate checks: unknown or revoked keys, wrong live/test environment, inactive subscription, or exhausted API credits. See Errors when wiring retries.
Never expose your API keys in client-side code. Use API keys only in trusted server-side environments. Browser and mobile clients should connect with short-lived session stream tokens created by your backend.

​
Making Authenticated Requests

Use the Authorization header with a Bearer token: 
curl https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key"

​
Request Headers

HeaderRequiredDescription
AuthorizationYesPreferred format: Bearer <api_key>
X-API-KeyNoAlternative to Authorization
Content-TypeYes for JSON bodiesUse application/json for POST requests
Idempotency-KeyRecommended on POSTPrevents duplicate writes on retry

​
WebSocket Authentication

WebSocket connections use the session stream token returned by POST /v1/sessions, not your API key. 
const session = await fetch('https://api.kallglot.com/v1/sessions', {
  method: 'POST',
  headers: {
    'Authorization': `Bearer ${process.env.KALLGLOT_API_KEY}`,
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    mode: 'bidirectional_translation',
    source_language: 'de',
    target_language: 'en'
  })
}).then((response) => response.json());

const ws = new WebSocket(
  `${session.stream.url}?token=${session.stream.token}`
);
That JSON body is WebSocket-only (no PSTN leg). For Twilio, Telnyx, or SIP, add routing on POST /v1/sessions as documented in Create Session—do not use a nested provider object.

​
Token Expiration

Stream tokens expire after 5 minutes. The stream.expires_at field tells you exactly when the token expires. Token expiry is checked only when the WebSocket connects, so an already-connected stream stays active after that point.

​
API Key Permissions

API keys can be scoped to the smallest permission set your application needs:
PermissionDescription
sessions:readRetrieve session details
sessions:writeCreate and end sessions
recordings:readAccess recordings
analysis:readRetrieve analysis results
analysis:writeRequest session analysis
webhooks:manageManage webhook endpoints
New keys are created with the full standard scope set listed above so integrations work out of the box; prefer the smallest viable set whenever you can customize scopes.

​
Response Headers

Authenticated HTTP responses may include these headers:
HeaderDescription
X-Request-IDStable request identifier for support and debugging
X-RateLimit-LimitMaximum requests allowed in the current rate-limit window
X-RateLimit-RemainingRequests remaining in the current rate-limit window
X-RateLimit-ResetUnix timestamp when the current rate-limit window resets
X-API-Credits-RemainingRemaining API credits for the organization
X-API-Credits-UsedAPI credits used in the current billing period
For billable write requests, the credit headers reflect the post-request balance when the request succeeds.

​
Authentication And Billing Errors

{
  "error": {
    "type": "permission_error",
    "code": "insufficient_api_credits",
    "message": "API credits exhausted. Purchase more credits to continue.",
    "request_id": "req_123"
  }
}
StatusCodeMeaning
401api_key_invalidThe API key is missing, malformed, or unknown
401api_key_expiredThe API key has expired
401api_key_revokedThe API key has been revoked
401api_key_wrong_environmentA test key was used against live, or vice versa
403organization_inactiveThe organization subscription is inactive
402insufficient_api_creditsThe organization has no API credits remaining
403insufficient_permissionsThe key lacks a required permission (scopes); this is unrelated to 402 (billing / credits exhaustion)
Examples: POST /v1/sessions needs sessions:write. A key missing that scope receives 403 even when credits are available (402).

​
Security Best Practices

Create new API keys periodically and revoke old ones to reduce exposure if a key is leaked.
Store API keys in environment variables or a secret manager, never in source control.
export KALLGLOT_API_KEY=sk_live_your_api_key
Live keys should only be used against the live API environment. Test keys should only be used in test or sandbox environments.
Watch the Developer Portal for unusual API activity, rate-limit pressure, and low API-credit balances.
If a key may have been exposed, revoke it immediately and replace it with a new scoped key.
See Error Codes for the full error catalog and Rate Limits for throughput limits and retry guidance.