Endpoints

This page is the overview of what the API can do. Field names, example responses and the option to try calls directly live in the interactive API documentation — that is the authoritative source and always current.

All paths below are relative to the base URL https://app.scaletalk.ai/api/public/v1.

Account

Method	Path	Purpose
`GET`	`/me`	Your own account — the best test that the key works
`GET`	`/usage`	Minutes used in the current billing period
`GET`	`/voices`	Available voices
`GET`	`/prompt_templates`	The prompt templates on your account

Agents

Method	Path	Purpose
`GET` `POST`	`/agents`	List agents, create a new one
`GET` `PATCH` `DELETE`	`/agents/{id}`	Read, update or delete a single agent
`POST`	`/agents/{id}/duplicate`	Duplicate an agent
`POST`	`/agents/{id}/generate_prompt`	Generate a prompt
`GET` `PUT`	`/agents/{id}/caller_lookup`	Read and set caller context
`GET` `PUT`	`/agents/{id}/post_processing`	Read and set follow-up
`GET` `POST`	`/agents/{id}/tools`	List and create capabilities
`PATCH` `DELETE`	`/agents/{id}/tools/{toolId}`	Update or remove a single capability
`GET` `POST`	`/agents/{id}/knowledge`	The agent's knowledge documents
`DELETE`	`/agents/{id}/knowledge/{docId}`	Detach a document from the agent
`GET` `POST`	`/agents/{id}/dictionary`	Pronunciation dictionary
`PATCH` `DELETE`	`/agents/{id}/dictionary/{termId}`	Update or delete a single entry
`GET` `POST`	`/agents/{id}/keyterms`	STT keyterms
`PATCH` `DELETE`	`/agents/{id}/keyterms/{termId}`	Update or delete a single term
`POST`	`/agents/{id}/dial_out`	Trigger a single outbound call

Calls

Method	Path	Purpose
`GET`	`/calls`	List and filter calls
`GET`	`/calls/{id}`	A single call with its captured variables
`GET`	`/calls/{id}/transcript`	Full transcript
`GET`	`/calls/{id}/recording`	Recording, where one exists

Campaigns

Method	Path	Purpose
`GET` `POST`	`/campaigns`	List and create campaigns
`GET` `PATCH` `DELETE`	`/campaigns/{id}`	Read, update or delete a single campaign
`GET` `POST`	`/campaigns/{id}/leads`	List contacts and add them one at a time
`POST`	`/campaigns/{id}/leads/csv`	Upload a contact list as CSV
`POST`	`/campaigns/{id}/start`	Start a campaign
`POST`	`/campaigns/{id}/pause`	Pause
`POST`	`/campaigns/{id}/resume`	Resume
`POST`	`/campaigns/{id}/stop`	Stop for good

Phone numbers

Method	Path	Purpose
`GET`	`/phone_numbers`	List your own numbers
`POST`	`/phone_numbers/search`	Search available numbers
`POST`	`/phone_numbers/purchase`	Purchase a number
`POST`	`/phone_numbers/import_byo`	Import your own SIP number
`GET` `PATCH` `DELETE`	`/phone_numbers/{id}`	Read, assign or release a single number

Knowledge base

Method	Path	Purpose
`GET` `POST`	`/knowledge_documents`	List and upload documents
`GET` `DELETE`	`/knowledge_documents/{id}`	Read or delete a single document

Mind the permissions

Every endpoint requires the matching permission on the key. Without it you get 403 back, not 401. The mapping is straightforward: read calls need …:read, writes need …:write.

Three endpoints cost money or place real calls, so they carry their own permissions:

Endpoint	Permission
`POST /phone_numbers/purchase`	`phone_numbers:purchase`
`POST /campaigns/{id}/start`	`campaigns:execute`
`POST /agents/{id}/dial_out`	`dial_out:execute`

Errors

Errors come back as JSON with a descriptive code:

{
  "error": {
    "code": "invalid_request",
    "message": "The request body is missing required fields"
  }
}

Code	Meaning
`invalid_request`	The request is incomplete or malformed
`unauthorized`	Key missing or invalid
`forbidden`	Key valid but lacking the required permission
`not_found`	The resource does not exist
`rate_limited`	Too many requests
`internal_error`	An error on our side

On 429 the response carries a Retry-After header telling you how long to wait.

Idempotency on write calls

Every write endpoint accepts an Idempotency-Key header. Set it wherever a duplicate call would hurt — purchasing a number, placing a call, uploading a contact list. If the request times out and you retry with the same key, it is not executed twice.

On this page