API Reference
Agents

List everything that references an agent ("Used by")

GET
/v1/agents/{id}/usage

The "Used by" view: every place in the workspace that references this agent, so an operator can see — and click through to — where it is wired. Three workspace-scoped sources, each an array that is always present (never null) and empty when nothing references the agent:

  • numbers — inbound number bindings (a number's routing_config.inbound_agent names this agent).
  • broadcasts — outbound campaigns whose agent_id is this agent.
  • linked_by — OTHER agents that list this agent as a specialist-transfer target.

See AgentUsage for the per-source fields.

Authorization

bearerAuth
AuthorizationBearer <token>

Long-lived ES256 JWT minted from the dashboard (https://app.sautikit.com/developers/api-keys). Signed by the platform keyring. Carries workspace_id and scopes claims; revoked via the platform deny-list.

In: header

Path Parameters

id*string
Formatuuid

Response Body

application/json

application/json

application/json

curl -X GET "https://example.com/v1/agents/497f6eca-6276-4993-bfeb-53cbbbba6f08/usage"
{  "numbers": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "e164": "string",      "enabled": true,      "mode": "string"    }  ],  "broadcasts": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string",      "state": "string",      "created_at": "2019-08-24T14:15:22Z"    }  ],  "linked_by": [    {      "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",      "name": "string"    }  ]}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ]  }}
{  "error": {    "code": "validation.bad_request",    "message": "string",    "request_id": "string",    "details": [      "string"    ]  }}

Replace an agent's specialist-transfer links (full replacement) PUT

Full-replacement — see `AgentLinksInput`. Requires a writer role. Returns the saved set (server-assigned `id`/`position`/timestamps), re-read after the write rather than an echo of the request.

Place a one-off AI agent call POST

The single-call primitive: dials one number, composing the agent's `base_prompt` with the per-call `prompt_template` (+ `variables`), bypassing broadcast schedule/retry machinery. Billed normally; occupies a concurrency seat like any broadcast dial. The caller-ID is the workspace's own dialable number (422 `send.no_caller_number` if none). Pass `revision` to compose against a pinned published revision instead of the mutable draft.