feat: add google stt and tts. add folders to organize agents

docs/api-reference/calls.mdx

@@ -5,11 +5,37 @@ description: "Initiate outbound calls and trigger agents via the API"
 
 | Method | Endpoint | Quick Link |
 |---|---|---|
-| `POST` | `/public/agent/{uuid}` | [Trigger an outbound call](/api-reference/calls/trigger) |
+| `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.

docs/api-reference/calls/trigger-workflow.mdx

@@ -0,0 +1,25 @@
+---
+title: "Trigger an Outbound Call by Workflow UUID"
+description: "Initiate an outbound call using a workflow's stable Agent UUID"
+openapi: "POST /api/v1/public/agent/workflow/{workflow_uuid}"
+---
+
+Use this endpoint when you want to execute a workflow directly by its stable Agent UUID instead of through an API Trigger node.
+
+The `workflow_uuid` is the workflow's Agent UUID. It is different from an API Trigger node's `trigger_path`.
+
+To find and copy the Agent UUID in the UI, see [Agent UUID](/configurations/agent-uuid).
+
+Use `workflow_run_id` from the response to later [retrieve call details](/api-reference/calls/get-run), recordings, and transcripts.
+
+Pass `initial_context` to inject runtime data as template variables into the agent's prompt. See [Using initial context](/api-reference/calls#using-initial-context).
+
+Pass `telephony_configuration_id` to route the call through a specific telephony configuration instead of your organization's default. The id is shown on each row in **Telephony configurations** (`https://app.dograh.com/telephony-configurations` for hosted or `http://localhost:3010/telephony-configurations` for local).
+
+<Note>
+This route expects a workflow UUID. Do not pass an API Trigger node UUID here. If you want to execute via an API Trigger node, use [Trigger an outbound call](/api-reference/calls/trigger) instead.
+</Note>
+
+<Note>
+Your telephony provider must be configured before outbound calls will connect. See [Telephony](/integrations/telephony/overview) for setup instructions.
+</Note>

docs/api-reference/calls/trigger.mdx

@@ -1,10 +1,12 @@
 ---
-title: "Trigger an Outbound Call"
-description: "Initiate an outbound call using an agent's public UUID"
+title: "Trigger an Outbound Call by API Trigger Node"
+description: "Initiate an outbound call using an API Trigger node UUID"
 openapi: "POST /api/v1/public/agent/{uuid}"
 ---
 
-The simplest way to initiate a call programmatically. The `uuid` comes from the [API Trigger node](/voice-agent/api-trigger) in your agent — add the node to your workflow and copy its auto-generated `trigger_path`.
+Use this endpoint when you want to execute a workflow through an [API Trigger node](/voice-agent/api-trigger).
+
+The `uuid` comes from the API Trigger node in your agent. Add the node to your workflow and copy its auto-generated `trigger_path`.
 
 Use `workflow_run_id` from the response to later [retrieve call details](/api-reference/calls/get-run), recordings, and transcripts.
 
@@ -12,6 +14,10 @@ Pass `initial_context` to inject runtime data as template variables into the age
 
 Pass `telephony_configuration_id` to route the call through a specific telephony configuration instead of your organization's default. The id is shown on each row in **Telephony configurations** (`https://app.dograh.com/telephony-configurations` for hosted or `http://localhost:3010/telephony-configurations` for local).
 
+<Note>
+This route expects an API Trigger node UUID (`trigger_path`). Do not pass a workflow UUID here. If you want to execute by workflow UUID, use [Trigger an outbound call by workflow UUID](/api-reference/calls/trigger-workflow) instead.
+</Note>
+
 <Note>
 Your telephony provider must be configured before outbound calls will connect. See [Telephony](/integrations/telephony/overview) for setup instructions.
 </Note>