aethexDocs
Dashboard

Scopes

Every API key carries a set of scopes that gate which endpoints it can hit. Keys are minted with the full default bundle below; narrow a key by picking its scopes when you create it in the dashboard, or by passing a custom `scopes` list over the API. Keys without a required scope get a 403 Forbidden from the matching endpoint.

Agents

Create and manage voice agents, their tools, and knowledge base.

  • agents:readRead

    List, fetch, and inspect agents, agent tools, and knowledge-base contents.

    Also covers running knowledge-base queries.

  • agents:writeWrite

    Create, update, duplicate, and delete agents; manage tools; upload knowledge-base docs.

    Required at presign time for POST /uploads/presign with kind="doc/knowledge-base". The bytes are PUT directly to the presigned storage URL.

Calls

Place outbound calls and drive live WebRTC conversation sessions.

  • calls:readRead

    List and fetch call records and batch jobs.

    Also covers GET /conversation/{session_id}/status for live session polling.

  • calls:writeWrite

    Place outbound calls and drive live conversation sessions (connect, send text, end).

    Covers REST-triggered calls (/calls, /calls/trigger, /calls/batch), ending a live call (/calls/:call_id/end) and WebRTC session control.

Conversations

Read transcripts, recordings, and diagnostics for completed calls.

  • conversations:readRead

    List, search, and fetch conversation transcripts, diagnostics, and recordings.

    Includes audio-token endpoints and feedback (which mutate but scope to the read role since they only attach to existing conversations).

Recordings

Recording metadata and audio downloads.

  • recordings:readRead

    List recordings, fetch metadata, download audio.

  • recordings:writeWrite

    Delete recordings.

    DELETE /recordings/{id}.

Speech

Transcription and text-to-speech.

  • transcribe:useUse

    Submit audio for transcription (sync, async, presigned-upload), poll job status, cancel jobs.

    Required at presign time for POST /uploads/presign with kind="audio/transcribe".

  • tts:useUse

    Synthesize speech (sync, streaming, batch) and generate voice previews.

    Every route under /tts plus POST /voices/preview.

Voices

Browse the voice catalog and clone voices.

  • voices:readRead

    List the voice catalog and fetch individual voice metadata.

    GET /voices, GET /voices/{voice_id}, GET /voices/clone/script and GET /voices/clone/{job_id}.

  • voices:writeWrite

    Clone voices and delete your clones. Not granted by default.

    POST /voices/clone, POST /voices/clone/by-upload, DELETE /voices/clone/{job_id}, and presigning `audio/voice-clone` uploads.

Phone numbers

Register and manage the numbers your agents can dial out from.

  • phone_numbers:readRead

    List and fetch phone numbers registered to your account.

  • phone_numbers:writeWrite

    Register Twilio numbers, change routing config, release them.

Twilio accounts

Per-account Twilio sub-account credentials.

  • twilio_accounts:readRead

    List and fetch Twilio sub-account credentials registered to your account.

  • twilio_accounts:writeWrite

    Register and remove Twilio sub-account credentials.

Text messages

The messages an agent may text, the customer threads those texts create, and the carrier that carries them.

  • sms_messages:readRead

    View the messages agents can send.

  • sms_messages:writeWrite

    Write and manage the messages agents send.

    Covers the message library only. It cannot send free text to a person — that is `sms_inbox:write`.

  • sms_inbox:readRead

    Read customer text threads and their messages.

  • sms_inbox:writeWrite

    Reply as a person, hand threads to and from the agent, and mark them read.

    Separate from `sms_messages:*` because it sends free text to a real recipient and reads what customers wrote.

  • sms_campaigns:readRead

    View text campaigns and who they reached.

  • sms_campaigns:writeWrite

    Create text campaigns, and start, pause or cancel them.

    Texts thousands of people who never wrote to you first, and every message is billable. Grant it deliberately.

  • messaging_accounts:readRead

    View the linked carrier that sends text messages.

  • messaging_accounts:writeWrite

    Link and manage the carrier that sends text messages.

WhatsApp

Linked WhatsApp Business numbers, the conversations on them, and what may be sent.

  • whatsapp_accounts:readRead

    View linked WhatsApp Business numbers.

  • whatsapp_accounts:writeWrite

    Link and manage WhatsApp Business numbers.

  • whatsapp_messages:writeWrite

    Send template messages and place calls on a linked WhatsApp number.

    Spends money: every template message opens a billable conversation with WhatsApp. It is not implied by `whatsapp_accounts:write`.

  • whatsapp_inbox:readRead

    Read customer threads and messages on linked numbers.

  • whatsapp_inbox:writeWrite

    Reply as an operator, hand threads between agent and human, run campaigns, and permanently erase a customer's conversation.

    Campaigns bill per conversation, so this grants spending as well as replying. It can also permanently erase a customer's conversation on a number: their messages, call transcripts and recordings, and the agent's memory of them.

Carrier connect

Carrier accounts Aethex links on your behalf to provision numbers and trunks.

  • carrier_accounts:readRead

    View linked carrier accounts.

  • carrier_accounts:writeWrite

    Link a carrier API key and auto-provision SIP trunks.

    Provisions real trunks on your carrier account, so it reaches beyond Aethex.

Microsoft Teams

The Teams tenant connection and the numbers attached through it.

  • msteams:readRead

    View the linked Microsoft Teams connection.

  • msteams:writeWrite

    Connect and disconnect a Microsoft Teams tenant, attach its numbers, and place calls on them.

    Kept separate from `calls:write` because placing a Teams call reaches into your Microsoft tenant.

Integrations

Third-party connections an agent can read from and write to during a call.

  • integrations:readRead

    View connected third-party integrations.

    Also covers browsing a connected system's entities and fields when importing from it.

  • integrations:writeWrite

    Connect and manage third-party integrations.

SIP trunks

Bring-your-own-carrier SIP trunks and their provisioning.

  • sip_trunks:readRead

    List and fetch SIP trunks registered to your account.

  • sip_trunks:writeWrite

    Create, onboard, update, delete SIP trunks and set the default outbound trunk.

    POST /sip-trunks/onboard also needs `phone_numbers:write` for the one-shot number registration.

Usage

Read usage metrics and configure usage-based webhook triggers.

  • usage:readRead

    Read usage metrics (current period, daily, monthly, summary) and inspect usage triggers.

  • usage:writeWrite

    Create and update usage triggers, redeliver firings, rotate the webhook signing secret.

Models

Browse the LLM model catalog used for the `llm_model` field on agents.

  • models:readRead

    List available LLM models and inspect catalog metadata.

    GET /models. Required for every call to the model catalog endpoint.

Most integrations want `agents:write`, `calls:write`, and the matching read scopes. Add others as you grow into them.