HTTP API
The TelAPI HTTP interface for integrations, from team API keys, scopes and request limits to authentication, errors, paging, health probes and the OpenAPI description. Browse the feature map or configuration finder.
Availability: Next. Entries that depend on an optional feature, a role or a deployment choice name it in their own Availability line.
Features in this family
- TelAPI HTTP service
- Team API keys
- API key scopes
- Daily API request limit per team
- Authenticate API requests with a key header
- Additional API authentication methods
- Lockout after repeated failed API credentials
- API rate limits
- List a team's call endpoints over the API
- Paged API responses
- API error responses
- Runtime capabilities endpoint
- Text-to-speech usage over the API
- OpenAPI description and interactive API explorer
- Allowed origins and IP addresses for browser endpoints
- Web app configuration endpoint
TelAPI HTTP service
A separate API service answers integration requests under a versioned path and is reached through its own host name and port.
For: Integrators, Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Services and containers | API host environment(TELAPI_HOST, TELAPI_PORT, TELAPI_URL) | API variables |
Read more:
- Set it up: 1. Select the operation and credential
- Reference: API description by capability profile
- Reference: API variables
Related features: OpenAPI description and interactive API explorer, Service health and readiness checks.
Team API keys
Team administrators create, label, rotate and revoke keys that let a backend system call the API on behalf of one team.
Availability: Requires the Browser SDK feature; needs the Team administrator role. The API Keys tab appears only when the Browser SDK capability is enabled for the deployment.
For: Team administrators, Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| Team settings | Settings › API Keys(apiKey, ApiKey) | Create a scoped key |
Read more:
- Set it up: Create a scoped key
- Set it up: Rotate or revoke a key
- Set it up: Verify an authenticated request
- Troubleshoot: Check what is unavailable
Related features: API key scopes, Authenticate API requests with a key header, Daily API request limit per team.
API key scopes
Each key carries only the permissions it was granted, such as creating call tokens or reading team apps and usage, limited to what the platform allows for that team.
Availability: Requires the Browser SDK feature.
For: Team administrators, Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| Team settings | Settings › API Keys › Create API Key › Scopes(scopes, CREATE_CALL_TOKEN, READ_TEAM_APPS, READ_TEAM_USAGE, READ_CALL_TOKEN) | Create a scoped key |
| Platform settings | Administration › Teams › Allowed API Scopes(allowedApiScopes) | Check what is unavailable |
Read more:
- Reference: Create a scoped key
- Troubleshoot: Check what is unavailable
Related features: Team API keys, Authenticate API requests with a key header.
Daily API request limit per team
A team can be held to a maximum number of API requests per UTC day, and the key list shows how many requests each key has made today.
Availability: Requires the Browser SDK feature.
For: Team administrators, Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Platform settings | Administration › Teams › Max Requests Per Day(maxRequestsPerDay) | Read key usage and list controls |
Read more:
- Reference: Read key usage and list controls
- Troubleshoot: 4. Interpret errors before retrying
Related features: Team API keys, API rate limits.
Authenticate API requests with a key header
Backend callers send their team key in a request header; requests without a valid key or with a missing scope are refused before any data is returned.
For: Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| HTTP API | Request header(X-API-Key) | 1. Select the operation and credential |
| Services and containers | API environment(API_TOKEN_HEADER) | API variables |
Read more:
- Set it up: 1. Select the operation and credential
- Troubleshoot: 4. Interpret errors before retrying
Related features: Additional API authentication methods, Lockout after repeated failed API credentials.
Additional API authentication methods
Authentication depends on the operation: token validation and certificate handling have separate requirements. Configuring OAuth2 environment values does not create an OAuth2 exchange.
For: Deployment operators, Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| Services and containers | API environment › token settings(JWT_SECRET, JWT_ISSUER, JWT_AUDIENCE, JWT_EXPIRES_IN, OAUTH2_CLIENT_ID, OAUTH2_CLIENT_SECRET, OAUTH2_TOKEN_URL, OAUTH2_AUTHORIZE_URL) | API tokens and listener TLS |
| Services and containers | API environment › TLS settings(TLS_ENABLED, TLS_CERT_PATH, TLS_KEY_PATH, TLS_CA_PATH, TLS_REQUEST_CERT, TLS_REJECT_UNAUTHORIZED) | API tokens and listener TLS |
Read more:
- Reference: API tokens and listener TLS
Related features: Authenticate API requests with a key header, TelAPI HTTP service.
Lockout after repeated failed API credentials
A caller that keeps presenting wrong credentials is blocked for a while, and operators can tune or relax that blocking.
For: Integrators, Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Services and containers | API environment › credential retry settings(API_CREDENTIAL_*) | Credential retry jail |
Read more:
- Reference: Credential retry jail
- Troubleshoot: 4. Interpret errors before retrying
Related features: Authenticate API requests with a key header, API rate limits.
API rate limits
Platform administrators set how many requests per time window each class of API traffic may make, and callers over the limit get a rate-limit error.
Availability: Needs the super-admin role.
For: Deployment operators, Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| Platform settings | Admin Settings › API Server Config(ApiServerConfig, rateLimitEnabled, rateLimitMax, rateLimitWindowMs) | Adjust API rate limits |
Read more:
- Reference: Adjust API rate limits
- Troubleshoot: 4. Interpret errors before retrying
Related features: Lockout after repeated failed API credentials.
List a team's call endpoints over the API
An integration can ask the API which call endpoints its team exposes, so it does not need to hard-code numbers or slugs.
For: Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| HTTP API | GET /api/v1/endpoints(/api/v1/endpoints) | 2. Send a bounded read-only request |
Read more:
- Set it up: 2. Send a bounded read-only request
- Reference: API description by capability profile
Related features: Paged API responses.
Paged API responses
List operations return results in pages with a total count, so callers request further pages on purpose rather than receiving everything at once.
For: Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| HTTP API | Query parameters(page, limit, total, totalPages) | 3. Read further pages deliberately |
Read more:
- Set it up: 3. Read further pages deliberately
Related features: List a team's call endpoints over the API.
API error responses
Failed requests return a status code and a machine-readable error code that tells the caller whether to fix the request, wait or escalate.
For: Integrators
Read more:
- Reference: 4. Interpret errors before retrying
Related features: Authenticate API requests with a key header, API rate limits.
Runtime capabilities endpoint
An integration can read which optional runtime features the deployment offers before it relies on them.
For: Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| HTTP API | GET /api/v1/runtime/capabilities(/api/v1/runtime/capabilities) | Runtime capabilities and voice |
Read more:
- Reference: Runtime capabilities and voice
Related features: Web app configuration endpoint, Enabled features overview.
Text-to-speech usage over the API
An integration can read how many synthesized speech characters its team has consumed for a period.
For: Integrators, Team administrators
| Level | Where to change it | Owner section |
|---|---|---|
| HTTP API | GET /api/v1/usage/tts-characters(/api/v1/usage/tts-characters, READ_TEAM_USAGE) | Read team TTS usage |
Read more:
- Reference: Read team TTS usage
Related features: Call and usage metrics.
OpenAPI description and interactive API explorer
The API ships with a machine-readable OpenAPI description and an optional browser explorer that operators usually keep switched off in production.
For: Integrators, Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Services and containers | API environment(TELAPI_SWAGGER_UI_ENABLED) | API variables |
Read more:
- Reference: API description by capability profile
- Reference: API variables
Related features: TelAPI HTTP service.
Allowed origins and IP addresses for browser endpoints
A browser voice or chat entry point can be limited to listed web origins and client IP ranges so other sites cannot start sessions with it.
Availability: Requires the Browser SDK feature.
For: Application builders, Integrators
| Level | Where to change it | Owner section |
|---|---|---|
| Application settings | App › Endpoints › Web voice or web chat › Allowed Origins / Allowed IPs(allowedOrigins, allowedIPs) | Web Voice and Web Chat fields |
Read more:
- Set it up: Configure the browser channel and access boundaries
- Reference: Web Voice and Web Chat fields
Related features: Team API keys.
Web app configuration endpoint
The web app reads its effective feature switches and service addresses from a small configuration endpoint, which explains why a menu entry is present or missing.
For: Deployment operators
| Level | Where to change it | Owner section |
|---|---|---|
| Services and containers | GET /api/config(/api/config) | Web UI feature conditions |
Read more:
- Reference: Web UI feature conditions
Related features: Enabled features overview, Runtime capabilities endpoint.