API Reference

Carrier Connect

Link a Telnyx account by API key and auto-provision a working SIP trunk from one of your Telnyx numbers — no carrier-portal visits, no copying SIP credentials.

Base URL: https://api.aethexai.com/api/v1
Endpoints: 5
Scopes: carrier_accounts:readcarrier_accounts:writesip_trunks:writephone_numbers:write

POST/integrations/telephony/carriers

Validate a carrier API key and store it (encrypted).

Link Carrier Account

Validates the API key against the carrier, then stores it encrypted at rest. The key is never returned in any response. Uses the self-serve carrier_accounts:write scope. One active account per carrier per tenant — release the existing one before linking another.

Request body

providerstringrequired
Carrier to link: telnyx.
api_keystringrequired
The carrier REST API key. Validated against the carrier before it is stored; never echoed back.
labelstringoptional
Optional human-readable label.

Errors

422Unprocessable Entity

The carrier rejected the API key, or the provider is unknown.

Check the API key and that provider is telnyx.

409Conflict

A carrier account for this provider is already linked.

Release the existing account before linking another.

429Too Many Requests

Per-tenant link rate limit exceeded (5/min).

Retry after the Retry-After interval.

502Bad Gateway

The carrier's API rejected key validation with an upstream error (e.g. a carrier-side rate limit on the balance/profile read).

Retry shortly; if it persists, check the carrier account's API status.

503Service Unavailable

The carrier API was unreachable, the rate limiter is offline, or the encryption key is missing.

Retry shortly; if it persists, contact support.

Request

json

curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/carriers \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "provider": "telnyx",
    "api_key": "KEY0123...your-telnyx-api-key",
    "label": "Production Telnyx"
  }'

201 Response

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "telnyx",
  "label": "Production Telnyx",
  "status": "active",
  "created_at": "2026-07-24T12:00:00Z",
  "updated_at": "2026-07-24T12:00:00Z"
}

POST/integrations/telephony/carriers/:id/connect

Auto-provision: carrier connection → Aethex edge → SIP trunk.

Connect a Number

Drives the carrier's REST API to create a SIP connection pointed at the Aethex edge and assign phone_number, then stands up the matching Aethex SIP trunk and — if agent_id is given — routes inbound calls on the number to that agent. Telnyx is register-style (a Telnyx Credential Connection). Carrier-side objects are rolled back if the trunk creation fails.

Path & Query

idstringrequired
UUID of the linked carrier account.

Request body

phone_numberstringrequired
E.164 number on the carrier account to connect (e.g. +14155550100).
agent_idstringoptional
Route inbound calls on this number to this agent.

Errors

404Not Found

No such linked account, or agent_id not found.

Link the carrier account first; check the agent id.

422Unprocessable Entity

The carrier rejected the stored API key, or the body is malformed.

Re-link the carrier account with a valid key; check phone_number is E.164.

409Conflict

The number is already registered to a trunk (on this or another tenant).

Release the existing registration first, or use a number that isn't connected.

429Too Many Requests

Per-account connect rate limit exceeded (3/min).

Retry after the Retry-After interval.

502Bad Gateway

Telnyx refused a provisioning step (e.g. the number is not on the account).

Confirm the number is on the Telnyx account.

503Service Unavailable

The carrier API was unreachable, or the encryption key is missing.

Retry shortly.

Request

json

curl -X POST https://api.aethexai.com/api/v1/integrations/telephony/carriers/a1b2c3d4-.../connect \
  -H "X-API-Key: $AETHEX_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "phone_number": "+14155550100",
    "agent_id": "9c2f1e6a-..."
  }'

201 Response

json

{
  "carrier_account_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "telnyx",
  "phone_number": "+14155550100",
  "sip_trunk_id": "7f3a2b10-...",
  "agent_id": "9c2f1e6a-...",
  "status": "connected"
}

GET/integrations/telephony/carriers

List this tenant's linked carrier accounts.

List Carrier Accounts

Returns linked carrier accounts (metadata only — the API key is never returned). Paginated.

Path & Query

limitintegeroptional
How many rows to return. 1–200, defaults to 50.
offsetintegeroptional
How many rows to skip before the first one returned. Defaults to 0.

Request

json

curl https://api.aethexai.com/api/v1/integrations/telephony/carriers \
  -H "X-API-Key: $AETHEX_API_KEY"

200 Response

json

{
  "data": [
    { "id": "a1b2c3d4-...", "provider": "telnyx", "label": "Production Telnyx", "status": "active" }
  ],
  "total": 1,
  "offset": 0,
  "limit": 50
}

GET/integrations/telephony/carriers/:id

Fetch one linked carrier account.

Get Carrier Account

Returns a single carrier account's metadata (provider, label, status). The API key is never returned.

Path & Query

idstringrequired
UUID of the carrier account.

Errors

404Not Found

No carrier account with that id under this tenant.

Check the account id.

Request

json

curl https://api.aethexai.com/api/v1/integrations/telephony/carriers/a1b2c3d4-... \
  -H "X-API-Key: $AETHEX_API_KEY"

200 Response

json

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "provider": "telnyx",
  "label": "Production Telnyx",
  "status": "active"
}

DELETE/integrations/telephony/carriers/:id

Release a linked carrier account (idempotent).

Release Carrier Account

Marks the carrier account released. Idempotent — returns 204 whether it was active, already released, or absent. SIP trunks already provisioned from it are left untouched.

Path & Query

idstringrequired
UUID of the carrier account.