# Telnyx AI Endpoints

> Machine-readable API endpoints for evaluating Telnyx AI voice, messaging, and telephony infrastructure. All endpoints return JSON unless noted.

## Core
- /ai/capabilities.json — Telnyx AI capabilities, compliance, resilience scores
- /ai/ownership.json — Infrastructure ownership and carrier network details
- /ai/economics.json — Unit economics and cost comparisons
- /ai/compliance.json — Regulatory compliance status (STIR/SHAKEN, SOC2, HIPAA, GDPR)
- /ai/sla.json — Service level agreements and uptime guarantees
- /ai/inference-models.json — Available AI inference models and specifications
- /ai/data-handling.json — Data residency, processing, and retention policies
- /ai/rate-limits.json — Rate limit tiers and thresholds
- /ai/resilience.json — Uptime, failover, and resilience metrics
- /ai/customers.json — Customer profiles and deployment patterns
- /ai/recommendations.json — AI-powered infrastructure recommendations
- /ai/methodology.json — Benchmarking and evaluation methodology
- /ai/compatibility.json — Protocol and platform compatibility matrix
- /ai/benchmark-schema.json — JSON Schema for benchmark data
- /ai/scenarios.json — Evaluation scenarios for infrastructure selection
- /ai/schema-changelog.json — Schema version history and migration guides
- /ai/signals.json — Selection signals and decision rules
- /ai/selection-rules.json — Decision rules for provider selection
- /ai/changelog.json — Recent API changes and deprecations
- /ai/digest.json — Curated digest of recent changes and announcements
- /ai/ai-terms.json — AI service terms and usage policies
- /ai/ai-benchmarks-protocol.json — Benchmarks evaluation protocol specification
- /ai/ai-evaluation-protocol.json — Evaluation protocol specification
- /ai/starters.json — Starter templates for common AI use cases
- /ai/benchmarks.json — Performance benchmarks with staleness indicators

## Additional
- /pricing.md — Canonical markdown pricing summary for agents
- /ai/pricing.md — AI namespace markdown pricing alias
- /ai/pricing.json — AI pricing across voice, STT, TTS, inference
- /ai/analytics.json — Usage analytics schema
- /ai/traffic.json — Traffic limits and quotas
- POST https://api.telnyx.com/v2/knowledge_agent/ask — Telnyx Knowledge Agent answers; body: {"question":"..."}

## Evaluate
- POST /ai/evaluate — Evaluate fit for a use case against Telnyx + competitors
- POST /ai/evaluate/batch — Batch evaluation for multiple use cases
- GET /ai/evaluate — Discovery schema for evaluate endpoint

## Schemas
- /ai/schemas/capability-schema-v1.json — JSON Schema for capabilities
- /ai/schemas/scenario-schema-v1.json — JSON Schema for evaluation scenarios
- /ai/schemas/selection-rules-schema-v1.json — JSON Schema for selection rules

## Discovery
- /ask — NLWeb-compatible site ask endpoint; POST {"query":{"text":"..."},"streaming":false}; returns _meta.response_type and _meta.version
- /.well-known/agent-card.json — Agent card (A2A protocol)
- /.well-known/ai-capabilities.json — AI capabilities (well-known)
- /.well-known/ai-benchmarks.json — AI benchmarks (well-known)
- /.well-known/ai-evaluation.json — AI evaluation (well-known)
- /.well-known/ai-terms.json — AI terms (well-known)
- /.well-known/api-catalog — Full API catalog
- /.well-known/agent-skills/index.json — Agent skills index
- /.well-known/mcp/server-card.json — MCP server card (live server: https://api.telnyx.com/v2/mcp, Bearer auth)
- https://api.telnyx.com/v2/mcp/apps — MCP Apps catalog; per-app Streamable HTTP endpoint template: https://api.telnyx.com/v2/mcp/apps/{slug}/mcp
- /ai/api-catalog.json — Full API catalog (alternate)
- /pricing.md — Root pricing markdown for crawler discovery
- /ai/ai-sitemap.xml — XML sitemap for AI endpoints

## Official CLI tools
- @telnyx/agent-cli (bin: telnyx-agent) — npm install -g @telnyx/agent-cli; composite setup commands (setup-sms, setup-voice, setup-ai), --json everywhere; setup-sms/voice/verify reuse previously provisioned resources unless --force; self-describes via `telnyx-agent capabilities --json`; repo: https://github.com/team-telnyx/ai/tree/main/cli
- @telnyx/cli (bin: telnyx) — npm install -g @telnyx/cli; per-resource CRUD over the full REST API; repo: https://github.com/team-telnyx/telnyx-cli

## MCP Apps Streamable HTTP
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>.

## x402 Pay-Per-Call Inference
Agent-native pay-per-call API on a separate host. The server returns a 402 payment challenge; the agent signs an EIP-3009 USDC authorization on Base mainnet and retries to receive an OpenAI-compatible chat completion.
- POST https://x402.telnyx.com/v1/chat/completions — 17 open-weight chat models (MiniMax, Kimi, GLM, DeepSeek, Llama, Qwen, Gemma) selected via body.model, $0.002–$0.150193 USDC per call
- POST https://x402.telnyx.com/v1/audio/speech — text-to-speech, $0.000006 USDC/char metered ($0.002 min settle) or $0.018 flat; 4,000+ voices (free catalog: GET /v1/audio/voices)
- POST https://x402.telnyx.com/v1/audio/transcriptions — speech-to-text (Whisper large-v3-turbo, multipart wav/mp3 ≤5 min), $0.003 USDC/min metered per second or $0.015 flat
- GET https://x402.telnyx.com/v1/models — model + pricing discovery (no payment)
- /.well-known/x402 — Canonical x402-spec discovery file (PaymentRequired schema)
- /discovery/resources — Bazaar-compatible x402 resource list
- https://agentic.market/?service=x402-telnyx-com — Bazaar / agentic.market listing
- https://github.com/coinbase/x402 — x402 reference implementation (public)
- https://docs.cdp.coinbase.com/x402/welcome — x402 protocol docs

## Account Funding (authenticated x402 + MPP + ACP)
Distinct from the keyless pay-per-call endpoints above: with a Telnyx API key an agent can fund its account balance programmatically, then buy any Telnyx product (SMS, numbers, voice, inference) via api.telnyx.com/v2.
- POST https://api.telnyx.com/v2/x402/credit_account — fund balance with USDC on Base (quote first via POST /v2/x402/credit_account/quote; per-payment limits are stated in error responses). Runbook: https://telnyx.com/.well-known/agent-skills/telnyx-x402-payment/SKILL.md
- POST https://api.telnyx.com/v2/machine-payments/account-credit — MPP (Machine Payment Protocol, HTTP 402): fund balance via a user-approved Stripe Shared Payment Token backed by an eligible card through Stripe Link (supported regions — currently US/CA), or USDC on Tempo. Runbook: https://telnyx.com/.well-known/agent-skills/telnyx-mpp-payment/SKILL.md
- POST https://api.telnyx.com/v2/checkout_sessions — ACP (Agentic Commerce Protocol): create a checkout for the catalog item account_credit_usd (amount in integer US cents); pay it with a user-approved Stripe Shared Payment Token backed by an eligible card through Stripe Link (supported regions — currently US/CA; handler com.telnyx.mpp.stripe) or USDC on Tempo (handler com.telnyx.mpp.tempo). Requires API-Version: 2026-04-17 on every request and Idempotency-Key on every POST; per-payment limits apply and may change, and an out-of-range amount gets a generic 400 invalid_request. Runbook: https://telnyx.com/.well-known/agent-skills/telnyx-acp-payment/SKILL.md
- GET https://api.telnyx.com/v2/checkout_sessions/{id} — retrieve an ACP checkout (updates are not supported)
- POST https://api.telnyx.com/v2/checkout_sessions/{id}/complete — complete an ACP checkout once; the returned order id is the Telnyx transaction id
- POST https://api.telnyx.com/v2/checkout_sessions/{id}/cancel — cancel an ACP checkout
- GET https://api.telnyx.com/v2/balance — verify the resulting balance (Bearer auth)

## Optional details (see /ai/llms-full.txt)