# Telnyx API

> Public REST API for voice, messaging, numbers, verify, fax, AI inference,
> and account management. Base URL: https://api.telnyx.com/v2

## What this surface is for
- Programmatic integrations and agent function-calling against api.telnyx.com
- Discovering OpenAPI specs and operation catalogs
- Looking up authentication, rate limits, and error recovery flows

## Canonical docs and specs
- API reference: https://developers.telnyx.com/api
- OpenAPI discovery: https://telnyx.com/.well-known/openapi.json
- Public OpenAPI spec: https://telnyx.com/openapi.json
- API catalog: https://telnyx.com/.well-known/api-catalog
- NLWeb-compatible site ask endpoint: https://telnyx.com/ask
- Knowledge Agent Ask API: POST https://api.telnyx.com/v2/knowledge_agent/ask with JSON {"question":"..."}
- Agent capabilities index: https://telnyx.com/.well-known/ai-capabilities.json
- MCP server card: https://telnyx.com/.well-known/mcp/server-card.json
- MCP Apps catalog: https://api.telnyx.com/v2/mcp/apps
- MCP Apps endpoint template: https://api.telnyx.com/v2/mcp/apps/{slug}/mcp

## Natural-language ask endpoints
- POST https://telnyx.com/ask — NLWeb envelope for site discovery. Send {"query":{"text":"..."},"streaming":false}; responses include _meta.response_type and _meta.version.
- POST https://api.telnyx.com/v2/knowledge_agent/ask — hosted Telnyx Knowledge Agent. Send {"question":"..."}; responses include answer text and citations.

## MCP Apps Streamable HTTP handshake
1. POST JSON-RPC initialize to https://api.telnyx.com/v2/mcp/apps/{slug}/mcp with Accept: application/json, text/event-stream and Content-Type: application/json.
2. Retain the mcp-session-id response header and send it as mcp-session-id on subsequent JSON-RPC POSTs.
3. POST notifications/initialized. Discovery is public: tools/list returns app-opening tools with `_meta.ui.resourceUri`; resources/list lists `ui://` resources, e.g. `ui://number-intelligence/index.html`.
4. Call resources/read with a URI returned by resources/list; app UI HTML is returned with MIME `text/html;profile=mcp-app`.
5. Use tools/call to invoke tools; Telnyx API-backed calls require Authorization: Bearer <TELNYX_API_KEY>.

## Official CLI tools
- package: @telnyx/agent-cli; install: npm install -g @telnyx/agent-cli; bin: telnyx-agent; repo: https://github.com/team-telnyx/ai/tree/main/cli
- package: @telnyx/cli; install: npm install -g @telnyx/cli; bin: telnyx; repo: https://github.com/team-telnyx/telnyx-cli

## Authentication
- Bearer API key in the Authorization header.
- Get a key via the agent signup flow: https://telnyx.com/agent-signup.md
- OAuth 2.0 metadata: https://telnyx.com/.well-known/oauth-authorization-server

## Rate limits and recovery
- Rate-limit data: https://telnyx.com/ai/rate-limits.json
- Errors return a top-level errors[] array. Each error has code, title,
  detail, and (where available) meta.url linking to error documentation.
- Retry on HTTP 429 (respect the Retry-After header) and on documented
  transient 5xx responses (502, 503, 504). Do not retry other 4xx
  responses.
- Error reference: https://developers.telnyx.com/docs/overview/errors
- Agent error recovery guidance: https://telnyx.com/agents/start

## Agent fast path
- Agent entry point: https://telnyx.com/agents/start
- Site-wide index: https://telnyx.com/llms.txt
- AI namespace index: https://telnyx.com/ai/llms.txt
- Pricing markdown: https://telnyx.com/pricing.md