API Reference

Use this section to reproduce working requests: URLs, bodies, authentication, pagination, errors, and the WebSocket stream. It is intentionally limited to what you need to connect your servers and clients to Kallglot. The API follows common REST patterns: JSON over HTTPS, standard status codes, and Bearer API keys.

Base URL

All API endpoints are relative to:

https://api.kallglot.com/v1

Request Format

The API accepts JSON-encoded request bodies and returns JSON-encoded responses. All requests must include the Content-Type: application/json header for POST/PUT/PATCH requests.

curl https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"mode": "bidirectional_translation"}'

Response Format

All responses follow a consistent structure:

Success Response

{
  "id": "sess_01HXYZ123456789",
  "object": "session",
  "status": "created",
  "created_at": "2026-03-26T10:00:00Z"
}

Error Response

{
  "error": {
    "code": "invalid_request",
    "message": "The 'mode' field is required.",
    "type": "validation_error",
    "param": "mode"
  }
}

Object Types

Object	Description
`session`	A real-time voice processing session
`agent`	Configurable AI agent
`transcript`	Text transcript of a session
`recording`	Audio recording of a session
`analysis`	AI analysis of a session
`webhook_event`	Event delivered via webhook

ID Formats

All objects use prefixed identifiers for easy identification:

Prefix	Object Type
`sess_`	Session
`rec_`	Recording
`anl_`	Analysis
`agt_`	AI agent (ids are issued by Kallglot)
`kst_`	Stream token
`wh_`	Webhook endpoint
`evt_`	Webhook event

Pagination

There is no GET /v1/sessions list endpoint. Cursor-style query parameters apply only where a list route exists:

GET /v1/agents
GET /v1/sessions/{session_id}/recordings

curl "https://api.kallglot.com/v1/agents?limit=20&starting_after=agt_01HXYZ"

Parameter	Type	Description
`limit`	integer	Page size (`1`–`100`; default `20`)
`starting_after`	string	Cursor for forward pagination
`ending_before`	string	Cursor for backward pagination (where supported)

Paginated list response shape

{
  "object": "list",
  "data": [{ "id": "agt_01HXYZ", "object": "agent", "name": "Support" }],
  "has_more": false,
  "next_cursor": null,
  "url": "/v1/agents"
}

Idempotency

For POST requests that create resources, include an Idempotency-Key header to ensure the request is processed only once:

curl -X POST https://api.kallglot.com/v1/sessions \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Idempotency-Key: unique-request-id-12345" \
  -H "Content-Type: application/json" \
  -d '{"mode": "bidirectional_translation"}'

Keys are valid for roughly 24 hours (server-defined TTL)
Retrying with the same key returns the cached response when the JSON body matches the original request (see mismatches below)
Use UUIDs or other unique identifiers

See Idempotency for supported routes, conflict codes, and body-matching behavior.

Versioning

The API version is included in the URL path (/v1/). We release new versions when making backwards-incompatible changes.

Version	Status	End of Life
v1	Current	-

Endpoints

Agents

Method	Endpoint	Description
`GET`	`/v1/agents`	List AI agents
`GET`	`/v1/agents/:id`	Retrieve an AI agent
`POST`	`/v1/agents`	Create an AI agent
`PATCH`	`/v1/agents/:id`	Update an AI agent
`DELETE`	`/v1/agents/:id`	Delete an AI agent

Sessions

Method	Endpoint	Description
`POST`	`/v1/sessions`	Create a new session
`GET`	`/v1/sessions/:id`	Retrieve a session
`POST`	`/v1/sessions/:id/end`	End a session
`POST`	`/v1/sessions/:id/dial`	Start an outbound SIP dial (use Create Session with SIP `routing`; session is typically `created` first)
`POST`	`/v1/sessions/:id/hangup`	Hang up an active SIP leg
`GET`	`/v1/sessions/:id/transcript`	Get session transcript
`GET`	`/v1/sessions/:id/recordings`	List session recordings

Recordings

Method	Endpoint	Description
`GET`	`/v1/recordings/:id`	Retrieve recording metadata
`GET`	`/v1/recordings/:id/audio`	Download recording audio

Analysis

Method	Endpoint	Description
`POST`	`/v1/sessions/:id/analysis`	Queue session analysis (`202 Accepted`)
`GET`	`/v1/analyses/:id`	Retrieve analysis results

Streaming

Protocol	Endpoint	Description
WebSocket	`wss://api.kallglot.com/v1/sessions/:id/connect?token=...`	Real-time audio and transcript streaming

​API Reference

​Base URL

​Request Format

​Response Format

​Success Response

​Error Response

​Object Types

​ID Formats

​Pagination

​Paginated list response shape

​Idempotency

​Versioning

​Endpoints

​Agents

​Sessions

​Recordings

​Analysis

​Streaming