# PaaS management integration Use the same server-side API key with `https://api.latenth.com/voice/v1`. Read the current full OpenAPI: https://api.latenth.com/docs/admin.openapi.json. Do not call internal services, use private hosts or require an additional platform account. The two customer paths are predefined LatenTX + temporary Realtime configuration, or existing custom model draft/validate/publish + returned model ID. Both paths use model IDs. Independent Agent management and legacy model bindings are retired; use custom models for reusable configuration. ## Save and publish - Discover `/catalog.voice_models` via GET `/catalog`. Select `config.base_model` using a returned public model ID; use that model’s `input_languages`, `output_languages` and `voices`. Do not submit `llm`, `asr` or `tts`. Empty language uses the model default; voice language restrictions still apply. - `GET /custom-models/{id}`; preserve the current config and revision. `PUT` replaces the draft config. New drafts use revision 0. - Runtime business Skills: first save each one with `PUT /skills/{id}/versions/{version}` (`markdown` with name/description frontmatter, optional `resources`; versions are immutable, GET first and use a new version if the content differs). Then put only `{id,version,preload}` in `config.skills`. Inline `markdown`, `resources` or `required_tools` in a custom model is accepted by `PUT` but rejected by validate with 400. Inline Skill text is only for `session.latentx.skills` on a single Realtime session. - `POST /custom-models/{id}/validate`, then `/publish`, each with the current revision. A failed validate returns non-2xx; customer-fixable errors include a stable `code` such as `skill_inline_not_allowed`, `skill_version_not_found`, `knowledge_version_not_found` or `voice_unavailable`. Branch on `code`, not message text. Without a code, check inline Skills, missing Skill/Knowledge versions, then languages and voice against the catalog model. Publishing increments the revision and returns immutable versions. Use `versions[].model`; do not construct the ID yourself. - `DELETE /custom-models/{id}/versions/{version}` disables that version. Deleting the draft is allowed only before any publication. Never disable or rebind an existing customer version as a side effect of a docs/example test. - Resources: `/skills`, `/knowledge`, `/mcp`. Read [knowledge.md](knowledge.md). MCP update replaces write-only credentials too; GET cannot reconstruct the complete authenticated write payload. Store required credentials only on the customer backend. ## Web, phone and records `POST /webrtc/credentials` returns SDK credentials, actual caller and billing session ID. `GET/PUT/DELETE /phone-numbers/{phone_id}` manages already assigned numbers. Both use a public model ID and preserve existing custom model semantics. External MCP requires `allow_mcp_tools:true`; customer-executed Functions are unsupported on these transports. Built-in knowledge does not require an external MCP. Read `/conversations/{call_id}` for transcript and `recording.url` (short-lived). Read `/playground/sessions/{session_id}` for web-call accounting; DELETE requests asynchronous stop. `/usage` is Realtime usage audit, not monetary settlement. Quota fields are platform quota units, not CNY. Phone billing must be verified separately. Treat 409 as a revision/version conflict: re-read and reconcile rather than blindly retry publishing. Handle non-JSON/empty gateway errors. Keep keys, temporary credentials, recordings and private configuration out of logs/public examples. ## 会话记录查询 新建 Realtime 会话由服务端自动保存,不需要发送保存事件。使用当前 API Key 调用 `GET /voice/v1/conversations`,来源 `origin=realtime`;详情为 `GET /voice/v1/conversations/{session_id}`,会话事件为 `GET /voice/v1/conversations/{session_id}/events`。只可查询本账号数据。列表仍返回 data 数组,下一页使用末项 cursor;事件分页使用 data.next_cursor。 记录包含用户文本/最终转写、助手生成内容、工具过程、响应状态与用量事件。取消后的部分回答标记 incomplete;音频截断标记 truncated,不能把生成内容当成已播放内容。不保存音频 Base64、凭据或完整系统配置。历史未保存内容无法恢复;进程异常时保留到最近成功提交的记录。 ## Public data boundary Realtime and Admin expose customer conversation facts, tool business results, usage and charges. Read voice model/version `price` for customer base prices. Complete Realtime history preserves the same public event ID, type and JSON content as the live stream, except audio Base64 deltas. Audio is available through recording links. Continue pagination whenever `next_cursor` is present, even if the filtered page has no items. Console exports contain only loaded public events. ## Session events and recordings New sessions record events by default. Query `/voice/v1/conversations/{id}/events` for every transport. Follow opaque `next_cursor` even when items is empty, and inspect `capture_state`; legacy, partial, unavailable and expired are not complete captures. Complete Realtime history `data` matches the live server event ID, type and content, except audio Base64 deltas. Sending is not proof of client receipt/playback. Refresh after the WebSocket closes to obtain finalized history. Incomplete records are reported as partial, not complete. For phone/browser calls, read detail.recording first for the full recording; /recordings may also return separate tracks when enabled. For Realtime, check /recordings even when detail.recording.state is none. Check each stream and track separately: partial capture can coexist with an available full recording. In transcription mode, use items[].data.usage on completed transcription events to reconcile the live event by event_id. Do not add historical usage again. ## Public resource metadata Catalog returns models, voice_models, voices and customer prices; clients must not rely on an internal tenant field. Existing published model IDs and resource IDs remain valid. Realtime, browser calling and phone configuration all use model IDs. Publish a custom model to reuse instructions and resource references; do not send agent_id when configuring a phone number or requesting browser credentials; `phone_id` is the stable handle for a single assigned number. Multiple numbers may share `line_id`; configure, disable or unbind each independently using the ID returned by the list API. A legacy line handle, when supported, addresses only its original displayed number, never all numbers on the line. Public pricing contains display-only `price_tiers` in USD (per million tokens, or per request when `billingUnit=request`). Rates are base sales rates; account pricing adjustments may apply. An empty price tier list means rates are unavailable for display, not zero cost. Public gateway errors use `api_error` with the existing code and request ID. ## Atomic phone outbound POST `/calls` with `model`, owned outbound-capable `phone_id`, `to`, and required tenant-unique `request_id`. Optional `greeting` (2000 UTF-8 bytes), `context` (8000 UTF-8 bytes), `ring_timeout` (5–120 seconds, default40), `allow_mcp_tools`. No campaign or scheduler. It does not alter inbound bindings. GET `/calls/{call_id}` or `/calls?request_id=...`; POST `/calls/{call_id}/cancel` cancels dialing or hangs up an answered call asynchronously. Query until ended. States: preparing, dialing, answered, ended. On timeout/503, query/retry the same request_id and same parameters; never switch IDs to blindly redial. Conflicting parameters return409. Finished calls remain idempotent. Account and initiating API-key permissions, grouping and quota apply. All accounts pay actual model usage; carrier fees are separate. An unstarted reservation may take up to its expiry to release. Reuse the same call_id for conversations, events and recordings. External MCP requires explicit permission; customer-executed Function tools are unsupported. ## Conversation call types Conversation list and detail return `call_type`: `realtime`, `phone_inbound`, `phone_outbound`, `webrtc`, `playground`. `unknown` means historical evidence is insufficient. Playground is a separate entry type even though it uses WebRTC. Filter with `GET /voice/v1/conversations?call_type=phone_outbound`; filtering happens before cursor pagination. Keep the same filter across pages. Existing `origin=realtime|web|external` remains compatible: web includes WebRTC and Playground, external includes both phone directions. Call types do not change usage prices or recording access.