dograh/docs/api-reference/calls.mdx

---
title: "Overview"
description: "Initiate outbound calls and trigger agents via the API"
---

| Method | Endpoint | Quick Link |
|---|---|---|
| `POST` | `/public/agent/{uuid}` | [Trigger an outbound call by API Trigger node](/api-reference/calls/trigger) |
| `POST` | `/public/agent/workflow/{workflow_uuid}` | [Trigger an outbound call by workflow UUID](/api-reference/calls/trigger-workflow) |
| `GET` | `/workflow/{workflow_id}/runs/{run_id}` | [Retrieve call details](/api-reference/calls/get-run) |
| `GET` | `/public/download/workflow/{token}/{artifact_type}` | [Download recordings and transcripts](/api-reference/calls/download) |
| `POST` | `/telephony/inbound/{workflow_id}` | [Inbound call webhook](/api-reference/calls/inbound) |

## Choose the right public call route

Dograh exposes two public outbound call route families. They are **not**
 interchangeable, even though both path parameters look like UUIDs.

| Use this when | Production route | Test route | Identifier you pass |
|---|---|---|---|
| You added an **[API Trigger node](/voice-agent/api-trigger)** to the workflow and want to call that trigger | `/public/agent/{uuid}` | `/public/agent/test/{uuid}` | The trigger UUID (`trigger_path`) from the API Trigger node |
| You want to execute the workflow by its stable **Agent UUID** instead of a trigger node | `/public/agent/workflow/{workflow_uuid}` | `/public/agent/test/workflow/{workflow_uuid}` | The workflow UUID from the agent's **[Agent UUID](/configurations/agent-uuid)** field |

<Note>
Do not pass a workflow UUID to `/public/agent/{uuid}` and do not pass a trigger UUID
to `/public/agent/workflow/{workflow_uuid}`. Dograh treats these as different
identifier types and the request will fail if you mix them up.
</Note>

Once Dograh resolves the target agent, both route families behave the same:

- They accept the same request body
- They return the same response shape
- They validate the same `X-API-Key` organization boundary
- They use the same telephony configuration selection rules

If you specifically need the API Trigger route, see [Trigger an outbound call by API Trigger node](/api-reference/calls/trigger). To execute by workflow UUID, see [Trigger an outbound call by workflow UUID](/api-reference/calls/trigger-workflow).

## Using initial context

`initial_context` passes runtime data into the agent at call time. Values are available as template variables in your agent's prompt using double-brace syntax.

```json
{
  "initial_context": {
    "customer_name": "Jane",
    "appointment_date": "March 15"
  }
}
```

Your agent prompt can then reference `{{customer_name}}` and `{{appointment_date}}` and they will be substituted when the call starts.

## Run status values

| Status | Description |
|---|---|
| `pending` | Call queued but not yet connected |
| `in_progress` | Call is live |
| `completed` | Call ended normally |
| `failed` | Call failed before or during execution |