API Reference
- Where to find the full AutoTalk API documentation
- How to authenticate requests with your API key
- Key API endpoints and what they do
AutoTalk exposes a public REST API that lets external applications send messages to contacts and work with dynamic data (Dynadata). The API follows the OpenAPI 3.0 specification.
Live API documentation
The full, interactive API documentation is available at:
From there you can browse every endpoint, see request and response schemas, and try out calls directly in the browser.
Authentication
Every request must carry one of three headers. All three resolve to the same company context, share the same rate limits (api_requests monthly meter), and grant access to the same endpoints — they differ only in how the token is issued.
x-api-key (recommended for external integrations)
A long-lived API key (format sk-…) created from the AutoTalk dashboard.
x-api-key: sk-YOUR_API_KEY
To generate one, go to Integrations > API Tokens and click the + button. See API Tokens for step-by-step instructions. This is the header you want for any CRM, helpdesk, script, or custom bridge calling AutoTalk from outside.
x-jwt-token (internal use by AutoTalk assistants)
A short-lived JWT signed by AutoTalk and issued by the actions/security/auth/jwt/generate assistant workflow action. The payload is {companyId, ips?, dur?}; the default lifetime is 300 seconds, optionally bounded by an IP allow-list that is enforced against the caller's real public IP as seen by AutoTalk's edge (forwarded headers such as x-forwarded-for are not trusted).
x-jwt-token: YOUR_JWT_TOKEN
Agents use this to call /v1/ on behalf of their own company — typically from a JavaScript step (actions/code/javascript/execute) that receives step(N).jwt as input. There is no user-facing endpoint to mint one; external integrators should use x-api-key instead.
A complete working example is available in Discord Spam Moderator — an actor agent that mints a JWT and uses it to delete Discord spam, warn offenders, and kick repeat violators.
x-auth-token (unified header)
A convenience header that accepts either form. Values starting with sk- are treated as API keys; other values are validated as JWTs (and if the value is ambiguous, JWT is tried first).
x-auth-token: sk-YOUR_API_KEY
# or
x-auth-token: YOUR_JWT_TOKEN
When multiple headers are present, x-jwt-token wins over x-api-key, and both win over x-auth-token.
Treat all three token types like passwords. Never commit them to source control or share them in public channels. If a token is compromised, revoke it (API keys) or wait for expiration (JWTs) and rotate.
Base URL
All API requests use the following base URL:
https://api.autotalk.io/v1
Key endpoints
Below is an overview of the main API areas. For full request/response details, visit the live documentation.
Company
| Method | Path | Description |
|---|---|---|
| GET | /v1/self | Retrieve the authenticated company's profile |
Contacts
| Method | Path | Description |
|---|---|---|
| POST | /v1/contacts/{contactId}/send_message | Send a message to a specific contact |
Dynadata (dynamic data)
Dynadata endpoints let you manage custom data entities (contacts, orders, tickets, or any type your company defines).
| Method | Path | Description |
|---|---|---|
| GET | /v1/dynadata/types | List all available Dynadata types |
| POST | /v1/dynadata/type/{type}/list | List items of a specific type |
| GET | /v1/dynadata/type/{type}/item/{_id} | Retrieve a single item by ID |
| POST | /v1/dynadata/type/{type}/create | Create a new item |
| POST | /v1/dynadata/type/{type}/update | Update an existing item |
| DELETE | /v1/dynadata/type/{type}/item/{_id} | Delete an item by ID |
| POST | /v1/dynadata/type/{type}/validate | Validate an item without saving |
| GET | /v1/dynadata/type/{type}/schema | Get the JSON schema for a type |
| GET | /v1/dynadata/type/{type}/schema/zod | Get the Zod schema for a type |
| POST | /v1/dynadata/type/{type}/executeFunction/{functionName} | Execute a function on a type |
| POST | /v1/dynadata/type/{type}/item/{_id}/executeFunction/{functionName} | Execute a function on a specific item |
Storage
Upload files (images, PDFs, audio) and get a first-party {bucket, fullPath} reference you can pass to send_message, Dynadata document fields, or functions like createWhatsappWebEvoProduct. See Uploading files.
| Method | Path | Description |
|---|---|---|
| POST | /v1/storage/upload-url | Reserve a signed upload URL (step 1) |
| POST | /v1/storage/upload-complete | Finalize the upload; returns {bucket, fullPath} (step 2) |
| GET | /v1/storage/url | Get a short-lived download URL for a stored object |
Transcriptions
The standalone async transcription API (issue #822). Enqueue a transcription job for a stored audio file and poll for its status and result. Authenticated with your x-api-key.
| Method | Path | Description |
|---|---|---|
| POST | /v1/transcriptions | Enqueue a transcription job |
| GET | /v1/transcriptions/{id} | Fetch a job's status and result |
Example request
Here is an example of sending a text message to a contact using curl:
curl -X POST https://api.autotalk.io/v1/contacts/CONTACT_ID/send_message \
-H "x-api-key: YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"type": "text",
"body": {
"text": "Hello! How can we help you today?"
}
}'
Next steps
- API Tokens -- Generate and manage your API keys
- Webhooks -- Receive event notifications from AutoTalk
- Workflows -- Automate tasks inside AutoTalk