docs: add developer and api reference tabs (#190)

* docs: add developer and api reference tabs

* fix: remove duplicate image

api/app.py

@@ -49,6 +49,10 @@ app = FastAPI(
     version="1.0.0",
     openapi_url=f"{API_PREFIX}/openapi.json",
     lifespan=lifespan,
+    servers=[
+        {"url": "https://app.dograh.com", "description": "Production"},
+        {"url": "http://localhost:8000", "description": "Local development"},
+    ],
 )
 
 

docs/api-reference/agents.mdx

@@ -0,0 +1,20 @@
+---
+title: "Overview"
+description: "Create and manage voice agents (workflows) via the API"
+---
+
+In Dograh, a **voice agent** is called a **workflow** in the API. A workflow defines the conversation flow, LLM configuration, voice settings, and tools available to your agent.
+
+| Method | Endpoint | Quick Link |
+|---|---|---|
+| `POST` | `/workflow/create/definition` | [Create from definition](/api-reference/agents/create-from-definition) |
+| `POST` | `/workflow/create/template` | [Create from template](/api-reference/agents/create-from-template) |
+| `GET` | `/workflow/fetch` | [List agents](/api-reference/agents/list) |
+| `GET` | `/workflow/count` | [Get agent count](/api-reference/agents/count) |
+| `GET` | `/workflow/fetch/{workflow_id}` | [Get an agent](/api-reference/agents/get) |
+| `PUT` | `/workflow/{workflow_id}` | [Update an agent](/api-reference/agents/update) |
+| `PUT` | `/workflow/{workflow_id}/status` | [Archive an agent](/api-reference/agents/archive) |
+| `POST` | `/workflow/{workflow_id}/validate` | [Validate a workflow](/api-reference/agents/validate) |
+| `POST` | `/workflow/{workflow_id}/runs` | [Create test run](/api-reference/agents/runs/create) |
+| `GET` | `/workflow/{workflow_id}/runs` | [List runs](/api-reference/agents/runs/list) |
+| `GET` | `/workflow/{workflow_id}/runs/{run_id}` | [Get a run](/api-reference/agents/runs/get) |

docs/api-reference/agents/archive.mdx

@@ -0,0 +1,7 @@
+---
+title: "Archive Agent"
+description: "Archive or restore a voice agent"
+openapi: "PUT /api/v1/workflow/{workflow_id}/status"
+---
+
+Send `{"status": "archived"}` to deactivate an agent, or `{"status": "active"}` to restore it. Archived agents cannot receive calls but their history and definition are preserved.

docs/api-reference/agents/count.mdx

@@ -0,0 +1,15 @@
+---
+title: "Get Agent Count"
+description: "Get the total number of agents broken down by status"
+openapi: "GET /api/v1/workflow/count"
+---
+
+Returns totals broken down by status — useful for dashboards or quota checks.
+
+```json
+{
+  "total": 5,
+  "active": 4,
+  "archived": 1
+}
+```

docs/api-reference/agents/create-from-definition.mdx

@@ -0,0 +1,9 @@
+---
+title: "Create from Definition"
+description: "Create a voice agent from an explicit workflow definition"
+openapi: "POST /api/v1/workflow/create/definition"
+---
+
+Creates an agent from a node and edge graph you provide directly. Use this when you want full control over the workflow structure, or when programmatically generating agents.
+
+The `workflow_definition` object contains `nodes` (the steps in the conversation) and `edges` (transitions between steps). See [Editing a Workflow](/voice-agent/editing-a-workflow) for the full schema.

docs/api-reference/agents/create-from-template.mdx

@@ -0,0 +1,9 @@
+---
+title: "Create from Template"
+description: "Generate a voice agent from a natural language description"
+openapi: "POST /api/v1/workflow/create/template"
+---
+
+Dograh uses an LLM to generate the initial workflow definition from your description. The result is a fully editable agent — use [Update](/api-reference/agents/update) to refine it after creation.
+
+This is the fastest way to get a working agent, especially for common use cases like appointment booking, lead qualification, or customer support.

docs/api-reference/agents/get.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get Agent"
+description: "Retrieve a single agent by ID, including its full workflow definition"
+openapi: "GET /api/v1/workflow/fetch/{workflow_id}"
+---
+
+Returns the full agent including `workflow_definition` (nodes and edges), `template_context_variables`, `workflow_configurations`, and run statistics.

docs/api-reference/agents/list.mdx

@@ -0,0 +1,7 @@
+---
+title: "List Agents"
+description: "Retrieve all agents in your organization"
+openapi: "GET /api/v1/workflow/fetch"
+---
+
+Returns all agents (workflows) in your organization, including both active and archived. Each item includes summary fields — use [Get an agent](/api-reference/agents/get) to retrieve the full workflow definition.

docs/api-reference/agents/runs/create.mdx

@@ -0,0 +1,7 @@
+---
+title: "Create Test Run"
+description: "Execute a workflow without placing a real phone call"
+openapi: "POST /api/v1/workflow/{workflow_id}/runs"
+---
+
+Creates a test execution of the workflow. No outbound call is placed — this is useful for validating agent behavior, checking prompt outputs, and testing tool integrations before going live.

docs/api-reference/agents/runs/get.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get Run"
+description: "Retrieve a single workflow run by ID"
+openapi: "GET /api/v1/workflow/{workflow_id}/runs/{run_id}"
+---
+
+Returns the full run record including status, transcript, recording URL, gathered context, and usage/cost info. Use `recording_url` and `transcript_url` to download artifacts, or use the [Download endpoint](/api-reference/calls/download) for time-limited public URLs.

docs/api-reference/agents/runs/list.mdx

@@ -0,0 +1,7 @@
+---
+title: "List Runs"
+description: "Retrieve all runs for a workflow"
+openapi: "GET /api/v1/workflow/{workflow_id}/runs"
+---
+
+Returns all runs for the given workflow, including both test runs and live call runs.

docs/api-reference/agents/update.mdx

@@ -0,0 +1,7 @@
+---
+title: "Update Agent"
+description: "Update an agent's name, workflow definition, or configuration"
+openapi: "PUT /api/v1/workflow/{workflow_id}"
+---
+
+All fields are optional — only include the fields you want to change. Updating `workflow_definition` creates a new versioned definition while preserving the history of previous versions.

docs/api-reference/agents/validate.mdx

@@ -0,0 +1,9 @@
+---
+title: "Validate Workflow"
+description: "Validate a workflow definition without executing it"
+openapi: "POST /api/v1/workflow/{workflow_id}/validate"
+---
+
+Checks the current workflow definition for structural errors — missing required fields, invalid node configurations, broken edge references — without placing a call or creating a run.
+
+If invalid, the response includes a list of errors each with a `kind` (`node`, `edge`, or `workflow`), the offending `id`, the `field`, and a human-readable `message`. See [Errors](/api-reference/errors) for the full error schema.

docs/api-reference/api-keys.mdx

@@ -0,0 +1,21 @@
+---
+title: "Overview"
+description: "Create and manage API keys for programmatic access"
+---
+
+API keys authenticate requests from your applications and services. Each key is scoped to your organization — all API calls made with a key create and access resources within that organization.
+
+| Method | Endpoint | Quick Link |
+|---|---|---|
+| `POST` | `/user/api-keys` | [Create an API key](/api-reference/api-keys/create) |
+| `GET` | `/user/api-keys` | [List API keys](/api-reference/api-keys/list) |
+| `DELETE` | `/user/api-keys/{api_key_id}` | [Archive an API key](/api-reference/api-keys/archive) |
+| `PUT` | `/user/api-keys/{api_key_id}/reactivate` | [Reactivate an API key](/api-reference/api-keys/reactivate) |
+
+## Best practices
+
+- **Use one key per environment** — separate keys for development, staging, and production make rotation easy and limit blast radius if a key is compromised.
+- **Use one key per service** — this allows you to revoke a single service's access without affecting others.
+- **Rotate keys regularly** — create a new key, update your secret store, then archive the old key.
+- **Never hardcode keys** — use environment variables or a secrets manager. Never commit keys to version control.
+- **Monitor `last_used_at`** — keys with no recent activity may be safe to archive.

docs/api-reference/api-keys/archive.mdx

@@ -0,0 +1,7 @@
+---
+title: "Archive API Key"
+description: "Deactivate an API key by ID"
+openapi: "DELETE /api/v1/user/api-keys/{api_key_id}"
+---
+
+Archiving immediately revokes the key. Any request using the key after archiving returns `401`. Use [Reactivate](/api-reference/api-keys/reactivate) to restore access.

docs/api-reference/api-keys/create.mdx

@@ -0,0 +1,34 @@
+---
+title: "Create API Key"
+description: "Create a new API key for programmatic access"
+openapi: "POST /api/v1/user/api-keys"
+---
+
+<Warning>
+The full key is only returned once at creation. Store it immediately in a secrets manager or environment variable — it cannot be retrieved again.
+</Warning>
+
+## Authentication
+
+This endpoint requires a valid user session token. If you do not yet have an API key, obtain a session token by logging in first and pass it as a `Bearer` token in the `Authorization` header.
+
+**Step 1 — Log in to get a session token**
+
+```bash
+curl -X POST https://your-dograh-instance/api/v1/auth/login \
+  -H "Content-Type: application/json" \
+  -d '{"email": "you@example.com", "password": "your-password"}'
+```
+
+The response contains a `token` field. Use it in the next step.
+
+**Step 2 — Create an API key**
+
+```bash
+curl -X POST https://your-dograh-instance/api/v1/user/api-keys \
+  -H "Authorization: Bearer <token>" \
+  -H "Content-Type: application/json" \
+  -d '{"name": "my-api-key"}'
+```
+
+Once you have an API key, you can use `X-API-Key: <key>` in place of `Authorization: Bearer` for all subsequent requests.

docs/api-reference/api-keys/list.mdx

@@ -0,0 +1,7 @@
+---
+title: "List API Keys"
+description: "Retrieve all API keys for your organization"
+openapi: "GET /api/v1/user/api-keys"
+---
+
+The `key` field is never returned in list responses — only `key_prefix` (the first 8 characters) is shown for identification. To include archived keys, pass `?include_archived=true`.

docs/api-reference/api-keys/reactivate.mdx

@@ -0,0 +1,7 @@
+---
+title: "Reactivate API Key"
+description: "Reactivate a previously archived API key"
+openapi: "PUT /api/v1/user/api-keys/{api_key_id}/reactivate"
+---
+
+Restores a previously [archived](/api-reference/api-keys/archive) key. The key resumes accepting requests immediately.

docs/api-reference/authentication.mdx

@@ -0,0 +1,49 @@
+---
+title: "Authentication"
+description: "How to authenticate requests to the Dograh API"
+---
+
+## API key authentication
+
+API keys are the recommended way to authenticate programmatic requests. Pass your key in the `X-API-Key` request header.
+
+```bash
+curl https://your-dograh-instance/api/v1/workflow/fetch \
+  -H "X-API-Key: dg_your_api_key"
+```
+
+API keys are scoped to an organization. All resources created or accessed using a key belong to that organization.
+
+### Create an API key
+
+Create keys in the dashboard under **Settings → API Keys**. The full key is shown **only once** at creation time — store it immediately in a secrets manager or environment variable.
+
+<Note>
+For self-hosted deployments using local auth, sign up and log in via the dashboard first, then create an API key there before making API calls.
+</Note>
+
+### Manage API keys
+
+| Action | Method | Path |
+|---|---|---|
+| List keys | `GET` | `/user/api-keys` |
+| Create key | `POST` | `/user/api-keys` |
+| Archive key | `DELETE` | `/user/api-keys/{api_key_id}` |
+| Reactivate key | `PUT` | `/user/api-keys/{api_key_id}/reactivate` |
+
+Archiving a key immediately revokes it. All subsequent requests using that key return `401`.
+
+---
+
+## Error responses
+
+| Status | Cause |
+|---|---|
+| `401 Unauthorized` | Missing, invalid, or expired credentials |
+| `403 Forbidden` | Valid credentials but insufficient permissions for the resource |
+
+```json
+{
+  "detail": "Invalid or expired API key"
+}
+```

docs/api-reference/calls.mdx

@@ -0,0 +1,36 @@
+---
+title: "Overview"
+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` | `/telephony/initiate-call` | [Initiate a call (authenticated)](/api-reference/calls/initiate) |
+| `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) |
+
+## 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 |

docs/api-reference/calls/download.mdx

@@ -0,0 +1,7 @@
+---
+title: "Download Recordings and Transcripts"
+description: "Download a recording or transcript using a time-limited public URL"
+openapi: "GET /api/v1/public/download/workflow/{token}/{artifact_type}"
+---
+
+`artifact_type` is either `recording` or `transcript`. The `token` is a time-limited download token — generate one from the run details before calling this endpoint.

docs/api-reference/calls/get-run.mdx

@@ -0,0 +1,9 @@
+---
+title: "Retrieve Call Details"
+description: "Get the details, transcript, and recording for a call"
+openapi: "GET /api/v1/workflow/{workflow_id}/runs/{run_id}"
+---
+
+Returns the full run record including call status, duration, transcript URL, recording URL, gathered context, and usage/cost info.
+
+Use the `recording_url` and `transcript_url` directly, or use the [Download endpoint](/api-reference/calls/download) to generate time-limited public URLs for sharing.

docs/api-reference/calls/inbound.mdx

@@ -0,0 +1,9 @@
+---
+title: "Inbound Call Webhook"
+description: "Webhook endpoint that routes inbound calls to a specific agent"
+openapi: "POST /api/v1/telephony/inbound/{workflow_id}"
+---
+
+Configure this URL in your telephony provider's dashboard (Twilio, Vonage, etc.) to route inbound calls to a specific agent. The `workflow_id` determines which agent handles the call.
+
+See [Inbound Calls](/integrations/telephony/inbound) for full setup instructions per provider.

docs/api-reference/calls/initiate.mdx

@@ -0,0 +1,7 @@
+---
+title: "Initiate a Call (Authenticated)"
+description: "Start an outbound call with more control than the public endpoint"
+openapi: "POST /api/v1/telephony/initiate-call"
+---
+
+Use this endpoint when you need to specify a `workflow_run_id` to resume context from a previous run, or when you want to use the workflow's integer ID instead of its public UUID.

docs/api-reference/calls/trigger.mdx

@@ -0,0 +1,15 @@
+---
+title: "Trigger an Outbound Call"
+description: "Initiate an outbound call using an agent's public UUID"
+openapi: "POST /api/v1/public/agent/{uuid}"
+---
+
+The simplest way to initiate a call programmatically. The `uuid` is visible in the dashboard URL when viewing an agent.
+
+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).
+
+<Note>
+Your telephony provider must be configured before outbound calls will connect. See [Telephony](/integrations/telephony/overview) for setup instructions.
+</Note>

docs/api-reference/campaigns.mdx

@@ -0,0 +1,29 @@
+---
+title: "Overview"
+description: "Create and manage outbound calling campaigns"
+---
+
+A **campaign** runs a workflow against a list of contacts. You upload a CSV of phone numbers, configure retry logic and scheduling, then start the campaign. Dograh dials contacts automatically up to your configured concurrency limit.
+
+| Method | Endpoint | Quick Link |
+|---|---|---|
+| `POST` | `/s3/presigned-upload-url` | [Upload contacts CSV](/api-reference/campaigns/upload-contacts) |
+| `POST` | `/campaign/create` | [Create a campaign](/api-reference/campaigns/create) |
+| `GET` | `/campaign/` | [List campaigns](/api-reference/campaigns/list) |
+| `GET` | `/campaign/{campaign_id}` | [Get a campaign](/api-reference/campaigns/get) |
+| `PATCH` | `/campaign/{campaign_id}` | [Update a campaign](/api-reference/campaigns/update) |
+| `POST` | `/campaign/{campaign_id}/start` | [Start](/api-reference/campaigns/start) |
+| `POST` | `/campaign/{campaign_id}/pause` | [Pause](/api-reference/campaigns/pause) |
+| `POST` | `/campaign/{campaign_id}/resume` | [Resume](/api-reference/campaigns/resume) |
+| `GET` | `/campaign/{campaign_id}/progress` | [Get campaign progress](/api-reference/campaigns/progress) |
+| `GET` | `/campaign/{campaign_id}/runs` | [Get campaign call runs](/api-reference/campaigns/runs) |
+
+## Campaign status values
+
+| Status | Description |
+|---|---|
+| `draft` | Created but not started |
+| `running` | Actively dialing contacts |
+| `paused` | Temporarily stopped; can be resumed |
+| `completed` | All contacts processed |
+| `failed` | Campaign encountered a fatal error |

docs/api-reference/campaigns/create.mdx

@@ -0,0 +1,20 @@
+---
+title: "Create Campaign"
+description: "Create a new outbound calling campaign"
+openapi: "POST /api/v1/campaign/create"
+---
+
+Before creating a campaign, [upload your contacts CSV](/api-reference/campaigns/upload-contacts) to get a `source_url`.
+
+The `time_slots` field controls when Dograh is allowed to place calls. If omitted, calls can be placed at any time. The `timezone` field applies to all time slot windows.
+
+```json
+{
+  "time_slots": [
+    { "day": "monday", "start": "09:00", "end": "17:00" },
+    { "day": "tuesday", "start": "09:00", "end": "17:00" }
+  ]
+}
+```
+
+Once created, the campaign is in `draft` status. Call [Start](/api-reference/campaigns/start) to begin dialing.

docs/api-reference/campaigns/get.mdx

@@ -0,0 +1,5 @@
+---
+title: "Get Campaign"
+description: "Retrieve a single campaign by ID"
+openapi: "GET /api/v1/campaign/{campaign_id}"
+---

docs/api-reference/campaigns/list.mdx

@@ -0,0 +1,5 @@
+---
+title: "List Campaigns"
+description: "Retrieve all campaigns for your organization"
+openapi: "GET /api/v1/campaign/"
+---

docs/api-reference/campaigns/pause.mdx

@@ -0,0 +1,7 @@
+---
+title: "Pause Campaign"
+description: "Temporarily stop a running campaign"
+openapi: "POST /api/v1/campaign/{campaign_id}/pause"
+---
+
+Stops dispatching new calls. In-flight calls are not interrupted — they run to completion. Use [Resume](/api-reference/campaigns/resume) to continue from where the campaign paused.

docs/api-reference/campaigns/progress.mdx

@@ -0,0 +1,16 @@
+---
+title: "Get Campaign Progress"
+description: "Get the current progress of a campaign"
+openapi: "GET /api/v1/campaign/{campaign_id}/progress"
+---
+
+Returns a real-time snapshot of how many contacts have been processed.
+
+| Field | Description |
+|---|---|
+| `total` | Total number of contacts in the campaign |
+| `processed` | Contacts that have been attempted at least once |
+| `completed` | Contacts with a successful call outcome |
+| `failed` | Contacts that exhausted all retry attempts without success |
+| `pending` | Contacts not yet attempted |
+| `completion_percentage` | `processed / total × 100` |

docs/api-reference/campaigns/resume.mdx

@@ -0,0 +1,7 @@
+---
+title: "Resume Campaign"
+description: "Resume a paused campaign"
+openapi: "POST /api/v1/campaign/{campaign_id}/resume"
+---
+
+Resumes dispatching calls from where the campaign paused. Only valid on campaigns in `paused` status.

docs/api-reference/campaigns/runs.mdx

@@ -0,0 +1,7 @@
+---
+title: "Get Campaign Runs"
+description: "Retrieve individual call records for each contact in a campaign"
+openapi: "GET /api/v1/campaign/{campaign_id}/runs"
+---
+
+Returns the individual call records for each contact in the campaign. Each record includes the same fields as a [workflow run](/api-reference/calls#retrieve-call-details), including call status, duration, transcript, and recording URL.

docs/api-reference/campaigns/start.mdx

@@ -0,0 +1,7 @@
+---
+title: "Start Campaign"
+description: "Start dialing contacts in a campaign"
+openapi: "POST /api/v1/campaign/{campaign_id}/start"
+---
+
+Transitions the campaign from `draft` or `paused` to `running`. Dograh begins dialing contacts up to the configured `max_concurrency`.

docs/api-reference/campaigns/update.mdx

@@ -0,0 +1,7 @@
+---
+title: "Update Campaign"
+description: "Update campaign settings"
+openapi: "PATCH /api/v1/campaign/{campaign_id}"
+---
+
+You can update name, concurrency, time slots, and retry config. Updates are only allowed on campaigns in `draft` or `paused` status — [pause the campaign](/api-reference/campaigns/pause) first if it is currently running.

docs/api-reference/campaigns/upload-contacts.mdx

@@ -0,0 +1,33 @@
+---
+title: "Upload Contacts CSV"
+description: "Get a presigned S3 URL to upload a contacts CSV for a campaign"
+openapi: "POST /api/v1/s3/presigned-upload-url"
+---
+
+Uploading contacts is a two-step process. First call this endpoint to get a presigned upload URL, then PUT your CSV directly to that URL.
+
+```bash
+# Step 1: Get upload URL
+curl -X POST https://your-dograh-instance/api/v1/s3/presigned-upload-url \
+  -H "X-API-Key: dg_your_api_key"
+
+# Response:
+# { "upload_url": "https://...", "s3_key": "campaigns/..." }
+
+# Step 2: Upload the CSV
+curl -X PUT "https://presigned-url..." \
+  -H "Content-Type: text/csv" \
+  --data-binary @contacts.csv
+```
+
+Use the `s3_key` from the response as the `source_url` when [creating a campaign](/api-reference/campaigns/create).
+
+### CSV format
+
+The CSV must include a `phone_number` column. Any additional columns are passed as `initial_context` to each call, making them available as template variables in the workflow.
+
+```csv
+phone_number,customer_name,plan
++14155550100,Jane Smith,premium
++14155550101,Bob Jones,basic
+```

docs/api-reference/errors.mdx

@@ -0,0 +1,106 @@
+---
+title: "Errors"
+description: "HTTP status codes and error formats returned by the Dograh API"
+---
+
+## Error format
+
+All errors return a JSON body with a `detail` field:
+
+```json
+{
+  "detail": "Human-readable error message"
+}
+```
+
+For request validation failures (status `422`), `detail` is an array of field-level errors:
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "phone_number"],
+      "msg": "field required",
+      "type": "value_error.missing"
+    }
+  ]
+}
+```
+
+---
+
+## HTTP status codes
+
+| Status | Meaning | Common causes |
+|---|---|---|
+| `400` | Bad Request | Missing required fields, invalid parameter values, unsupported operation |
+| `401` | Unauthorized | Missing auth header, invalid or expired API key or JWT token |
+| `403` | Forbidden | Valid credentials but the resource belongs to a different organization |
+| `404` | Not Found | Resource ID does not exist or is not accessible to your organization |
+| `409` | Conflict | Duplicate resource (e.g., email already registered) |
+| `422` | Unprocessable Entity | Request body or query parameter failed schema validation |
+| `500` | Internal Server Error | Unexpected server-side failure |
+| `501` | Not Implemented | Feature not supported in the current deployment |
+
+---
+
+## Workflow validation errors
+
+When validating a workflow (or creating one with invalid nodes), the API returns structured errors that reference specific nodes, edges, or fields:
+
+```json
+{
+  "errors": [
+    {
+      "kind": "node",
+      "id": "agent-1",
+      "field": "data.prompt",
+      "message": "Prompt cannot be empty"
+    },
+    {
+      "kind": "edge",
+      "id": "edge-3",
+      "field": null,
+      "message": "Edge target node does not exist"
+    },
+    {
+      "kind": "workflow",
+      "id": null,
+      "field": null,
+      "message": "Workflow must have exactly one Start Call node"
+    }
+  ]
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `kind` | `"node" \| "edge" \| "workflow"` | What the error applies to |
+| `id` | string or null | Node or edge ID from the workflow definition |
+| `field` | string or null | Dot-notation path to the specific field (e.g. `data.prompt`) |
+| `message` | string | Human-readable description of the problem |
+
+---
+
+## Telephony errors
+
+Telephony operations may fail with one of these named error types returned in the `detail` field:
+
+| Error | Description |
+|---|---|
+| `PROVIDER_MISMATCH` | The request was routed to the wrong telephony provider |
+| `WORKFLOW_NOT_FOUND` | The workflow ID in the inbound URL does not exist |
+| `ACCOUNT_VALIDATION_FAILED` | Your telephony provider credentials are invalid |
+| `PHONE_NUMBER_NOT_CONFIGURED` | The phone number is not set up in your telephony account |
+| `SIGNATURE_VALIDATION_FAILED` | Webhook signature verification failed (possible spoofed request) |
+| `QUOTA_EXCEEDED` | Your organization has exceeded its usage quota |
+| `GENERAL_AUTH_FAILED` | Generic authentication failure with the telephony provider |
+
+---
+
+## Tips for handling errors
+
+- **Retry on `500`** with exponential backoff — transient server errors can resolve on retry.
+- **Do not retry `4xx`** — these indicate problems with your request that will not self-resolve.
+- **Check `detail` carefully on `422`** — the `loc` array pinpoints exactly which field failed validation.
+- **Store API keys securely** — a `401` on a previously working key likely means the key was archived.

docs/api-reference/overview.mdx

@@ -0,0 +1,71 @@
+---
+title: "Overview"
+description: "Interact with Dograh programmatically via the REST API"
+---
+
+## Base URL
+
+All API requests are made to:
+
+```
+https://your-dograh-instance/api/v1
+```
+
+If you are using the hosted version, the base URL is `https://app.dograh.com/api/v1`.
+
+## Versioning
+
+The current API version is `v1`. The version is included in the URL path.
+
+## Request format
+
+All request bodies must be sent as JSON with the `Content-Type: application/json` header.
+
+```bash
+curl -X POST https://your-dograh-instance/api/v1/workflow/create/definition \
+  -H "Content-Type: application/json" \
+  -H "X-API-Key: dg_your_api_key" \
+  -d '{"name": "My Agent", "workflow_definition": {}}'
+```
+
+## Response format
+
+All responses are JSON. Successful responses return the relevant resource object. Error responses follow a consistent shape:
+
+```json
+{
+  "detail": "Error message describing what went wrong"
+}
+```
+
+For validation errors (422), the detail may be a list:
+
+```json
+{
+  "detail": [
+    {
+      "loc": ["body", "name"],
+      "msg": "field required",
+      "type": "value_error.missing"
+    }
+  ]
+}
+```
+
+## Health check
+
+Verify your instance is reachable before making API calls.
+
+```bash
+curl https://your-dograh-instance/api/v1/health
+```
+
+```json
+{
+  "status": "ok",
+  "version": "1.0.0",
+  "backend_api_endpoint": "https://your-dograh-instance",
+  "deployment_mode": "oss",
+  "auth_provider": "local"
+}
+```

docs/configurations/tracing.mdx

@@ -68,7 +68,7 @@ The tool descriptions shown in traces match the descriptions you set in your pat
 
 ### Custom Tools
 
-Any external tools you've attached to the node (e.g. any custom tools you created for API endpoints for booking, order submission, etc.) will appear here. See custom tools documentation here: https://docs.dograh.com/voice-agent/tools.
+Any external tools you've attached to the node (e.g. any custom tools you created for API endpoints for booking, order submission, etc.) will appear here. See the [custom tools documentation](/voice-agent/tools/http-api).
 
 ## Tool Calls in Traces
 
@@ -115,7 +115,7 @@ We provide seamless integration with Langfuse for self-hosted Dograh deployments
 **Setup steps:**
 
 1. Sign up at [Langfuse](https://langfuse.com) and create API credentials
-2. Add the following environment variables (in `docker-compose.yaml` for Docker deployments):
+2. Add the following [environment variables](/developer/environment-variables#tracing-langfuse) (in `docker-compose.yaml` for Docker deployments):
 
 ```
 ENABLE_TRACING="true"

docs/core-concepts/calls-and-runs.mdx

@@ -0,0 +1,55 @@
+---
+title: "Calls & Runs"
+description: "The lifecycle of a call and how runs capture its results"
+---
+
+Every time a workflow executes, Dograh creates a **run**. The run is the record of that execution: what was said, what data was collected, how long it took, and what it cost.
+
+## Calls vs runs
+
+A **call** is the audio connection — whether over the phone via a telephony provider, or through the browser via Web Call.
+
+A **run** is the Dograh record of the workflow execution. Every call — outbound, inbound, web, or campaign — creates a run with the same contents: transcript, recording, gathered context, usage, and cost. Campaign runs are additionally linked to their parent campaign.
+
+## Call lifecycle
+
+The call lifecycle tracks the telephony connection — from the moment a number is dialed to when the line drops.
+
+```mermaid
+stateDiagram-v2
+    [*] --> Ringing: Number dialed
+    Ringing --> Connected: Caller answers
+    Ringing --> Ended: No answer / voicemail
+    Connected --> Ended: Conversation completes
+    Connected --> Ended: Error or disconnect
+    Ended --> [*]
+```
+
+For inbound calls, the flow starts when the caller dials in and the telephony provider routes the call to Dograh.
+
+
+## Inbound vs outbound
+
+**Outbound calls** are initiated by Dograh — you trigger them via the API or dashboard with a phone number and agent. Used for proactive outreach, reminders, and campaigns.
+
+**Inbound calls** are initiated by the caller — your telephony provider routes incoming calls to a Dograh agent via a webhook URL. Used for support lines, hotlines, and IVR replacement.
+
+## Web Calls
+
+Web Call lets you talk to your agent directly from the browser — no phone number or telephony setup required. It runs the full pipeline: STT, LLM, TTS, recording, and transcript, exactly the same as a phone call.
+
+Use it to try out your agent before going live. The run view shows the live transcript as the conversation progresses, node transitions as the workflow moves through the graph, and any tool or function calls the agent makes in real time.
+
+## What a run contains
+
+After a call completes, the run record includes:
+
+| Field | Description |
+|---|---|
+| `status` | Final run state |
+| `recording_url` | Download URL for the call audio |
+| `transcript_url` | Download URL for the conversation transcript |
+| `gathered_context` | Structured data extracted by the agent during the call |
+| `initial_context` | The data passed in when the call was triggered |
+| `usage_info` | Duration in seconds, token count |
+| `cost_info` | Cost in USD |

docs/core-concepts/campaigns.mdx

@@ -0,0 +1,100 @@
+---
+title: "Campaigns"
+sidebarTitle: "Campaigns (Bulk Outbound Calls)"
+description: "Running a voice agent against a list of contacts at scale"
+---
+
+A campaign is how you run a workflow against many contacts automatically. Instead of triggering calls one by one via the API, you upload a list of phone numbers and Dograh dials them for you — respecting scheduling windows, concurrency limits, and retry rules.
+
+## How a campaign works
+
+```mermaid
+flowchart LR
+    CSV[Contacts CSV] --> Upload[Upload to Dograh]
+    Upload --> Campaign[Create Campaign]
+    Campaign --> Schedule[Scheduling & Concurrency]
+    Schedule --> Calls[Outbound Calls]
+    Calls --> Runs[Run Records]
+    Runs --> Results[Progress & Reports]
+```
+
+1. **Upload a contacts CSV** — must have a `phone_number` column; any extra columns become `initial_context` for each call
+2. **Create the campaign** — link it to a workflow, set concurrency, time slots, and retry behaviour
+3. **Start it** — Dograh begins dialing contacts up to your concurrency limit
+4. **Monitor progress** — track processed, completed, failed, and pending counts in real time
+5. **Pause and resume** — stop and restart at any point without losing progress
+
+## The contacts CSV
+
+The CSV drives the campaign. Each row is one contact.
+
+```csv
+phone_number,customer_name,account_id,plan
++14155550100,Jane Smith,acc_001,premium
++14155550101,Bob Jones,acc_002,basic
+```
+
+Columns beyond `phone_number` are automatically passed as `initial_context` to each call, making them available as template variables in your agent's prompt — so each call can feel personalised at scale.
+
+## Scheduling and concurrency
+
+**Concurrency** controls how many calls run simultaneously. It's capped by your telephony plan. Set it conservatively to start.
+
+**Time slots** restrict when Dograh is allowed to dial — useful for respecting business hours or regulations:
+
+```json
+{
+  "timezone": "America/New_York",
+  "time_slots": [
+    { "day": "monday", "start": "09:00", "end": "17:00" },
+    { "day": "tuesday", "start": "09:00", "end": "17:00" }
+  ]
+}
+```
+
+If no time slots are set, Dograh dials continuously once the campaign is started.
+
+## Retry behaviour
+
+Dograh can automatically retry contacts who didn't answer, were busy, or went to voicemail:
+
+```json
+{
+  "retry_config": {
+    "max_attempts": 3,
+    "retry_interval_minutes": 60
+  }
+}
+```
+
+## Circuit breaker
+
+The circuit breaker automatically pauses a campaign when the call failure rate gets too high — protecting against wasted spend and telephony reputation issues caused by a misconfigured agent or a bad contact list.
+
+When enabled, Dograh monitors the failure rate within a rolling time window. If it exceeds the threshold, the campaign is paused automatically and must be manually resumed after the issue is investigated.
+
+| Setting | Default | Description |
+|---|---|---|
+| Failure Threshold (%) | `50` | Pause when the failure rate within the window exceeds this percentage |
+| Window (seconds) | `120` | Rolling time window over which the failure rate is calculated |
+| Min Calls in Window | `5` | Minimum number of calls required before the circuit breaker can trip — prevents false positives on small samples |
+
+A campaign paused by the circuit breaker behaves the same as a manually paused campaign — in-flight calls complete normally, and it can be resumed once the underlying issue is resolved.
+
+## Campaign lifecycle
+
+| Status | Meaning |
+|---|---|
+| `draft` | Created but not started |
+| `running` | Actively dialing |
+| `paused` | Stopped; resumes from where it left off |
+| `completed` | All contacts processed |
+| `failed` | Encountered a fatal error |
+
+You can pause and resume a campaign at any time. In-flight calls complete normally before a pause takes effect.
+
+## Results
+
+Each contact's call creates a run record with the full transcript, recording, and gathered context — same as a manually triggered call. Use the [Get Campaign Runs](/api-reference/campaigns/runs) endpoint to retrieve them all.
+
+See the [Campaigns API reference](/api-reference/campaigns) to get started.

docs/core-concepts/context-and-variables.mdx

@@ -0,0 +1,80 @@
+---
+title: "Context & Variables"
+description: "How data flows into, through, and out of a conversation"
+---
+
+Dograh has a simple data model for passing information through a call. Understanding it is key to building agents that feel personalised and to extracting useful results after a call.
+
+## The three context objects
+
+```
+initial_context ──► Agent ──► gathered_context
+                       │
+                 [template variables](/voice-agent/template-variables)
+                 (used in prompts)
+```
+
+### initial_context
+
+Data available to the agent before the call starts — the contact's name, account details, appointment information, anything the agent should know upfront. It can be set from several places:
+
+- **API trigger** — pass it in the request body when calling `POST /public/agent/{uuid}` or `POST /telephony/initiate-call`
+- **Campaign CSV** — columns beyond `phone_number` automatically become `initial_context` fields for each contact's call
+- **Dashboard** — set default template context variables on the agent, used when no external context is provided
+
+```json
+{
+  "phone_number": "+14155550100",
+  "initial_context": {
+    "customer_name": "Jane Smith",
+    "plan": "premium",
+    "renewal_date": "April 1"
+  }
+}
+```
+
+### Template variables
+
+Values from `initial_context` are available in your agent's prompt using `{{double_brace}}` syntax.
+
+```
+You are calling {{customer_name}} about their {{plan}} plan,
+which renews on {{renewal_date}}. Be friendly and confirm
+whether they'd like to continue.
+```
+
+When the call starts, Dograh substitutes the values before sending the prompt to the LLM — so the agent speaks naturally as if it already knows the contact.
+
+### gathered_context
+
+Data the agent collects *during* the call. You configure what to extract in the agent node's extraction settings — each variable has a name, type, and a prompt that tells the LLM what to look for.
+
+<img src="../images/extracted_variables.png" alt="Extracted variables" style={{border: "1px solid #d1d5db", borderRadius: "8px", maxWidth: "100%"}} />
+
+`gathered_context` is returned in the run record after the call completes and is available in [webhook payloads](/developer/webhooks) for downstream processing.
+
+## Data flow example
+
+```mermaid
+sequenceDiagram
+    participant App as Your System
+    participant Dog as Dograh
+    participant LLM as LLM
+
+    App->>Dog: initial_context: {customer_name: "Jane", plan: "premium"}
+    Dog->>LLM: Prompt with {{customer_name}} and {{plan}} substituted
+    LLM-->>Dog: Conversation response
+    Note over Dog,LLM: Call progresses...
+    Dog->>LLM: Extract: did the customer confirm renewal?
+    LLM-->>Dog: gathered_context: {renewal_confirmed: true}
+    Dog-->>App: Run record with gathered_context
+```
+
+## Where variables are available
+
+| Location | Variables available |
+|---|---|
+| Agent node prompts | `initial_context` fields via `{{variable_name}}` |
+| Edge conditions | Evaluated against the live conversation — no explicit variable syntax needed |
+| Webhook payload templates | All context objects via `{{initial_context.field}}`, `{{gathered_context.field}}` etc. |
+| Campaign CSV columns | CSV columns beyond `phone_number` become `initial_context` fields automatically |

docs/core-concepts/how-dograh-works.mdx

@@ -0,0 +1,87 @@
+---
+title: "How Dograh Works"
+description: "The big picture — from API call to phone conversation to transcript"
+---
+
+Dograh is a platform for building and running voice AI agents. You define a conversation flow, connect a phone number, and Dograh handles the rest — transcribing the caller's speech (STT), generating intelligent responses (LLM), speaking them back in a natural voice (TTS), and returning structured results when the call ends.
+
+## The core loop
+
+```mermaid
+sequenceDiagram
+    participant U as Dashboard / Your App
+    participant API as Dograh API
+    participant STT as Transcriber (STT)
+    participant LLM as LLM Provider
+    participant TTS as Voice Synthesizer (TTS)
+    participant Tel as Telephony Provider
+    participant Cal as Caller / Contact
+
+    U->>API: Trigger call (dashboard or API)
+    API->>Tel: Initiate outbound call
+    Tel->>Cal: Phone rings
+    Cal-->>Tel: Answers
+    Tel-->>API: Raw audio stream
+    loop Conversation
+        API->>STT: Caller audio
+        STT-->>API: Transcribed text
+        API->>LLM: Transcript + agent prompt + context
+        LLM-->>API: Agent response text
+        API->>TTS: Response text
+        TTS-->>API: Synthesized audio
+        API->>Tel: Audio stream
+        Tel->>Cal: Agent speaks
+    end
+    API->>API: Extract context, run webhooks
+    API-->>U: Run record (transcript, recording, gathered data)
+```
+
+## Key components
+
+**Workflows (Agents)**
+The conversation logic. A workflow is a graph of nodes (conversation steps) connected by edges (conditional transitions). You define what the agent says, when it moves on, and what data it collects.
+
+**Runs**
+Every execution of a workflow creates a run. The run record holds the transcript, recording, extracted data, and cost information.
+
+**Telephony**
+The phone infrastructure. Dograh connects to your telephony provider (Twilio, Vonage, etc.) to place and receive calls. The audio streams between the caller and Dograh in real time.
+
+**Transcriber (STT)**
+Converts the caller's speech to text in real time. Dograh sends the audio stream to your configured speech-to-text provider and uses the transcript to drive both the LLM and the final run record.
+
+**LLM Provider**
+Processes the transcript and the active node's prompt to generate the agent's next response. It also evaluates edge conditions to decide when to move the conversation forward.
+
+**Voice Synthesizer (TTS)**
+Converts the LLM's text response to audio and streams it back to the caller. The choice of TTS provider and voice is configurable per agent.
+
+## How it fits together
+
+When you trigger a call:
+
+1. Dograh instructs your telephony provider to dial the number
+2. When the caller answers, a real-time audio pipeline opens
+3. The caller's speech is transcribed by the STT provider
+4. The transcript is sent to the LLM with the active node's prompt and conversation history
+5. The LLM responds — the response is synthesized to audio by the TTS provider and streamed to the caller
+6. When an edge condition is met, Dograh transitions to the next node
+7. When an end node is reached, the call ends
+8. Post-call: context is extracted, webhooks fire, the run record is saved
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Workflows & Agents" href="/core-concepts/workflows-and-agents">
+    How the conversation graph works
+  </Card>
+  <Card title="Calls & Runs" href="/core-concepts/calls-and-runs">
+    The lifecycle of a call
+  </Card>
+  <Card title="Context & Variables" href="/core-concepts/context-and-variables">
+    How data flows through a conversation
+  </Card>
+  <Card title="Campaigns" href="/core-concepts/campaigns">
+    Running agents at scale
+  </Card>
+</CardGroup>

docs/core-concepts/workflows-and-agents.mdx

@@ -0,0 +1,60 @@
+---
+title: "Workflows & Agents"
+description: "How conversation flows are defined in Dograh"
+---
+
+In Dograh, what you see as an **agent** in the dashboard is called a **workflow** in the API. They are the same thing — a workflow is the underlying definition, agent is the product name for it.
+
+<Note>
+Anywhere the API says `workflow`, think "agent". Anywhere the API says `workflow_definition`, think "the conversation logic inside your agent".
+</Note>
+
+## The graph model
+
+A workflow is a **directed graph** — a set of nodes connected by edges.
+
+```mermaid
+graph LR
+    A[Start Call] -->|Caller greets| B[Qualify Intent]
+    B -->|Wants support| C[Support Agent]
+    B -->|Wants sales| D[Sales Agent]
+    C -->|Issue resolved| E[End Call]
+    D -->|Demo booked| E
+```
+
+**Nodes** are the steps in the conversation. Each node has a prompt that tells the LLM what to say and do at that point.
+
+**Edges** are the transitions between nodes. Each edge has a condition — a natural language description of when to move on. The LLM evaluates whether the condition has been met based on the conversation so far.
+
+## Node types
+
+| Type | What it does |
+|---|---|
+| `startCall` | Entry point for telephony calls. The first thing the agent says when a call connects |
+| `agentNode` | An LLM-powered conversation step. The core building block |
+| `globalNode` | Defines instructions that apply across all agent nodes (e.g. tone, language, fallback behaviour) |
+| `endCall` | Terminates the call |
+| `trigger` | Entry point for API-triggered runs (non-telephony) |
+| `webhook` | Fires an HTTP request when reached — use for CRM updates, notifications, etc. |
+| `qa` | Runs automated quality analysis on the completed call |
+
+## Edges and transitions
+
+An edge connects two nodes and fires when its condition is satisfied:
+
+<img src="../images/edge.png" alt="Edge configuration" style={{border: "1px solid #d1d5db", borderRadius: "8px", maxWidth: "100%"}} />
+
+`transition_speech` is optional — if set, the agent speaks it before moving to the next node.
+
+## Versioning
+
+Every time you update a workflow's `workflow_definition`, Dograh saves a new version while keeping the history. The current version is always what runs. Old versions are retained for auditing.
+
+## Creating workflows
+
+There are two ways to create a workflow via the API:
+
+- **From a definition** — provide the full node/edge graph yourself. Best for programmatic generation.
+- **From a template** — describe the use case in natural language and Dograh generates the initial graph using an LLM. Best for getting started quickly.
+
+See the [Workflow Definition Schema](/developer/workflow-schema) for the full field reference.

docs/developer/environment-variables.mdx

@@ -0,0 +1,144 @@
+---
+title: "Environment Variables"
+description: "Complete reference for all environment variables used by the Dograh backend"
+---
+
+Core environment variables are centralized in `api/constants.py`. Variables marked **Required** in the description must be explicitly set — the application will either fail to boot or behave insecurely without them.
+
+## Deployment Modes
+
+Dograh supports two deployment modes, set via `DEPLOYMENT_MODE`:
+
+- **OSS**: The default mode. Designed for self-hosted deployments using [Docker Compose](/deployment/docker) — the fastest way to get Dograh running. Uses local JWT authentication and MinIO for storage.
+- **SaaS**: Intended for customised deployments outside of Docker. Authentication and API key management are handled through Dograh Managed Platform Services (MPS), allowing greater flexibility in how the platform is hosted and integrated.
+
+The relevant required variables for each mode are noted in the descriptions below.
+
+---
+
+## Application
+
+| Variable | Default | Description |
+|---|---|---|
+| `ENVIRONMENT` | `local` | Runtime environment. Affects logging and behaviour. One of `local`, `production`, `test` |
+| `DEPLOYMENT_MODE` | `oss` | Deployment mode. Use `oss` for self-hosted |
+| `AUTH_PROVIDER` | `local` | Authentication provider. Use `local` for OSS |
+| `ENABLE_TRACING` | `false` | Enable distributed tracing via [Langfuse](/configurations/tracing) |
+
+---
+
+## Database
+
+| Variable | Default | Description |
+|---|---|---|
+| `DATABASE_URL` | N/A | **Required.** PostgreSQL connection string. e.g. `postgresql+asyncpg://user:pass@host:5432/dbname` |
+| `REDIS_URL` | N/A | **Required.** Redis connection string. e.g. `redis://localhost:6379` |
+
+---
+
+## Authentication (OSS)
+
+| Variable | Default | Description |
+|---|---|---|
+| `OSS_JWT_SECRET` | N/A | **Required for OSS deployments.** Secret used to sign JWT tokens. Must be set to a strong random value in production |
+| `OSS_JWT_EXPIRY_HOURS` | `720` | JWT token lifetime in hours (default: 30 days) |
+
+<Warning>
+Never use the placeholder `OSS_JWT_SECRET` in a production deployment. Generate a strong random secret and store it securely.
+</Warning>
+
+---
+
+## URLs
+
+| Variable | Default | Description |
+|---|---|---|
+| `BACKEND_API_ENDPOINT` | `http://localhost:8000` | Internal URL of the backend API |
+| `UI_APP_URL` | `http://localhost:3010` | URL of the frontend application |
+| `MPS_API_URL` | `https://services.dograh.com` | Dograh Managed Platform Services URL |
+| `DOGRAH_MPS_SECRET_KEY` | `null` | **Required for non-OSS deployments.** Secret key for authenticating with MPS |
+
+---
+
+## Storage
+
+Dograh uses **MinIO by default**, which is bundled with the self-hosted deployment and requires no external setup. Set `ENABLE_AWS_S3=true` to switch to AWS S3 — typically used for cloud or managed deployments where S3 is already part of the infrastructure.
+
+### MinIO (OSS default)
+
+| Variable | Default | Description |
+|---|---|---|
+| `MINIO_ENDPOINT` | `localhost:9000` | MinIO server host and port |
+| `MINIO_PUBLIC_ENDPOINT` | `null` | Publicly accessible MinIO URL (for download links) |
+| `MINIO_ACCESS_KEY` | N/A | **Required for OSS deployments.** MinIO access key. Must be set to a secure value in production |
+| `MINIO_SECRET_KEY` | N/A | **Required for OSS deployments.** MinIO secret key. Must be set to a secure value in production |
+| `MINIO_BUCKET` | `voice-audio` | Bucket name for audio files |
+| `MINIO_SECURE` | `false` | Use HTTPS for MinIO connections |
+
+### AWS S3 (alternative)
+
+| Variable | Default | Description |
+|---|---|---|
+| `ENABLE_AWS_S3` | `false` | Set to `true` to use AWS S3 instead of MinIO |
+| `S3_BUCKET` | `null` | S3 bucket name |
+| `S3_REGION` | `us-east-1` | AWS region |
+
+---
+
+## WebRTC
+
+| Variable | Default | Description |
+|---|---|---|
+| `TURN_HOST` | `localhost` | TURN server hostname for WebRTC NAT traversal |
+| `TURN_PORT` | `3478` | TURN server port |
+| `TURN_TLS_PORT` | `5349` | TURN server TLS port |
+| `TURN_SECRET` | `null` | **Required for WebRTC.** Shared secret for TURN credential generation |
+| `TURN_CREDENTIAL_TTL` | `86400` | TURN credential validity in seconds (default: 24h) |
+
+---
+
+## Tracing (Langfuse)
+
+| Variable | Default | Description |
+|---|---|---|
+| `LANGFUSE_HOST` | `null` | Langfuse server URL |
+| `LANGFUSE_PUBLIC_KEY` | `null` | Langfuse public key |
+| `LANGFUSE_SECRET_KEY` | `null` | Langfuse secret key |
+
+Set `ENABLE_TRACING=true` alongside these to activate LLM call tracing. See the [Tracing guide](/configurations/tracing) for setup instructions.
+
+---
+
+## Monitoring
+
+| Variable | Default | Description |
+|---|---|---|
+| `SENTRY_DSN` | `null` | Sentry DSN for error tracking |
+| `ENABLE_TELEMETRY` | `false` | Enable anonymous telemetry collection |
+
+---
+
+## Logging
+
+| Variable | Default | Description |
+|---|---|---|
+| `LOG_LEVEL` | `DEBUG` | Log level: `DEBUG`, `INFO`, `WARNING`, `ERROR` |
+| `LOG_FILE_PATH` | `null` | Write logs to this file path (in addition to stdout) |
+| `LOG_ROTATION_SIZE` | `100 MB` | Rotate log file when it reaches this size |
+| `LOG_RETENTION` | `7 days` | How long to keep rotated log files |
+| `LOG_COMPRESSION` | `gz` | Compression format for rotated logs |
+| `SERIALIZE_LOG_OUTPUT` | `false` | Output logs as JSON (useful for log aggregation) |
+
+---
+
+## Campaigns
+
+| Variable | Default | Description |
+|---|---|---|
+| `DEFAULT_ORG_CONCURRENCY_LIMIT` | `2` | Maximum concurrent outbound calls per organization |
+
+---
+
+## Further Customisation
+
+The variables documented here cover the standard configuration surface. For advanced customisation — such as integrating additional services or tuning internal behaviour — consult the relevant module alongside `api/constants.py` to understand how each variable is consumed.

docs/developer/webhooks.mdx

@@ -0,0 +1,110 @@
+---
+title: "Webhook Payloads"
+description: "Context variables available in webhook nodes and the data Dograh sends after a call"
+---
+
+Dograh executes **webhook nodes** asynchronously after a workflow run completes. You configure the target URL, HTTP method, headers, and payload template directly in the workflow definition.
+
+---
+
+## How webhooks work
+
+1. A call completes (or a run finishes)
+2. Dograh executes any `webhook` nodes in the workflow asynchronously
+3. The payload template is rendered with the run's context and sent as a JSON `POST` (or your configured method) to your endpoint
+4. Non-200 responses are logged but do not block or retry by default (configure `retry_config` to change this)
+
+---
+
+## Payload context variables
+
+The following variables are available in your `payload_template` using double-brace syntax (e.g. `{{workflow_run_id}}`):
+
+| Variable | Type | Description |
+|---|---|---|
+| `workflow_run_id` | integer | ID of the completed run |
+| `workflow_run_name` | string | Name of the run |
+| `workflow_id` | integer | ID of the workflow |
+| `workflow_name` | string | Name of the workflow |
+| `initial_context` | object | Context passed when the call was initiated |
+| `gathered_context` | object | Data extracted during the call by agent nodes |
+| `cost_info` | object | Call cost breakdown |
+| `annotations` | object | QA analysis results (if a `qa` node is configured) |
+| `recording_url` | string \| null | Public download URL for the call recording |
+| `transcript_url` | string \| null | Public download URL for the call transcript |
+
+### Example payload template
+
+```json
+{
+  "run_id": "{{workflow_run_id}}",
+  "customer": "{{initial_context.customer_name}}",
+  "outcome": "{{gathered_context.resolution}}",
+  "recording": "{{recording_url}}"
+}
+```
+
+---
+
+## Authentication
+
+Webhook requests support the following authentication methods, configured via a stored credential:
+
+| Type | Description |
+|---|---|
+| `NONE` | No authentication |
+| `API_KEY` | Sends the key in a custom header (e.g. `X-API-Key`) |
+| `BEARER_TOKEN` | Sends `Authorization: Bearer <token>` |
+| `BASIC_AUTH` | HTTP Basic authentication (username + password) |
+| `CUSTOM_HEADER` | Any custom header key-value pair |
+
+---
+
+## Receiving webhooks
+
+Your endpoint should:
+
+- Accept `POST` requests with `Content-Type: application/json`
+- Respond with a `2xx` status code promptly (within 30 seconds)
+- Handle duplicate deliveries idempotently (retries may deliver the same payload more than once)
+
+### Minimal example receiver (Python)
+
+```python
+from fastapi import FastAPI, Request
+
+app = FastAPI()
+
+@app.post("/webhook/dograh")
+async def handle_dograh_webhook(request: Request):
+    payload = await request.json()
+    run_id = payload.get("run_id")
+    outcome = payload.get("outcome")
+    # process the call result...
+    return {"status": "ok"}
+```
+
+---
+
+## Webhook node in a workflow definition
+
+See [Workflow Definition Schema](/developer/workflow-schema#webhook-node) for the full configuration reference.
+
+```json
+{
+  "id": "webhook-1",
+  "type": "webhook",
+  "position": { "x": 600, "y": 0 },
+  "data": {
+    "name": "Notify CRM",
+    "enabled": true,
+    "http_method": "POST",
+    "endpoint_url": "https://your-service.com/webhook/dograh",
+    "payload_template": {
+      "run_id": "{{workflow_run_id}}",
+      "customer": "{{initial_context.customer_name}}",
+      "outcome": "{{gathered_context.resolution}}"
+    }
+  }
+}
+```

docs/developer/workflow-schema.mdx

@@ -0,0 +1,197 @@
+---
+title: "Workflow Definition Schema"
+description: "Schema reference for the workflow_definition object used in the Agents API"
+---
+
+The `workflow_definition` object passed to [Create from Definition](/api-reference/agents/create-from-definition) and [Update Agent](/api-reference/agents/update) defines the full conversation graph. It is the same structure the dashboard's visual workflow builder reads and writes — building an agent in the UI produces a `workflow_definition` under the hood, and anything you can configure visually can equally be expressed here as JSON.
+
+```json
+{
+  "nodes": [...],
+  "edges": [...]
+}
+```
+
+---
+
+## Nodes
+
+Each node represents a step in the conversation.
+
+```json
+{
+  "id": "uuid-string",
+  "type": "agentNode",
+  "position": { "x": 100, "y": 200 },
+  "data": { ... }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Unique node ID (UUID recommended) |
+| `type` | string | One of the node types below |
+| `position` | object | Visual coordinates in the workflow builder |
+| `data` | object | Node configuration — fields vary by type |
+
+### Node types
+
+| Type | Description |
+|---|---|
+| `startCall` | Entry point for telephony calls |
+| `endCall` | Terminates the call |
+| `agentNode` | LLM-powered conversation step |
+| `globalNode` | Global configuration applied across all agent nodes |
+| `trigger` | Entry point for API-triggered (non-telephony) runs |
+| `webhook` | Sends an HTTP request when reached |
+| `qa` | Runs quality analysis on the completed call |
+
+---
+
+## Node data fields
+
+### Common fields (all node types)
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `name` | string | required | Display name for the node |
+| `prompt` | string | required* | LLM system prompt. *Not required for `trigger`, `webhook`, `qa` nodes |
+| `allow_interrupt` | boolean | `false` | Allow the caller to interrupt the agent mid-speech |
+| `wait_for_user_response` | boolean | `false` | Pause and wait for caller input before continuing |
+| `wait_for_user_response_timeout` | number | `null` | Seconds to wait for input before timing out |
+| `detect_voicemail` | boolean | `false` | Detect and handle voicemail on outbound calls |
+| `delayed_start` | boolean | `false` | Delay execution of this node |
+| `delayed_start_duration` | number | `null` | Delay in seconds |
+| `add_global_prompt` | boolean | `true` | Merge the `globalNode` prompt into this node's prompt |
+
+### agentNode — data extraction
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `extraction_enabled` | boolean | `false` | Extract structured data from the conversation |
+| `extraction_prompt` | string | `null` | Custom prompt to guide extraction |
+| `extraction_variables` | array | `[]` | Variables to extract (see below) |
+
+**Extraction variable schema:**
+
+```json
+{
+  "name": "customer_intent",
+  "type": "string",
+  "prompt": "What did the customer want to achieve?"
+}
+```
+
+`type` is one of `string`, `number`, or `boolean`.
+
+### agentNode — tools
+
+| Field | Type | Description |
+|---|---|---|
+| `tool_uuids` | string[] | IDs of tools (HTTP API, call transfer, etc.) to attach to this node |
+| `document_uuids` | string[] | IDs of knowledge base documents available to this node |
+
+### trigger node
+
+| Field | Type | Description |
+|---|---|---|
+| `trigger_path` | string | Unique UUID that becomes the API trigger endpoint path |
+
+### webhook node
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `enabled` | boolean | `true` | Whether this webhook fires when reached |
+| `http_method` | string | — | `GET`, `POST`, `PUT`, `PATCH`, or `DELETE` |
+| `endpoint_url` | string | — | Target URL |
+| `credential_uuid` | string | `null` | UUID of a stored auth credential |
+| `custom_headers` | array | `[]` | Additional request headers `[{"key": "...", "value": "..."}]` |
+| `payload_template` | object | `null` | Request body template (supports context variables) |
+
+### qa node
+
+| Field | Type | Default | Description |
+|---|---|---|---|
+| `qa_enabled` | boolean | `true` | Enable QA analysis |
+| `qa_system_prompt` | string | `null` | Custom evaluation prompt |
+| `qa_model` | string | `null` | LLM model to use for evaluation |
+| `qa_min_call_duration` | integer | `15` | Minimum call duration in seconds to run QA |
+| `qa_voicemail_calls` | boolean | `false` | Include voicemail calls in QA |
+| `qa_sample_rate` | integer | `100` | Percentage of calls to analyse (1–100) |
+
+---
+
+## Edges
+
+Each edge connects two nodes and defines when the transition fires.
+
+```json
+{
+  "id": "edge-uuid",
+  "source": "node-uuid-a",
+  "target": "node-uuid-b",
+  "data": {
+    "label": "Customer confirms",
+    "condition": "The customer has confirmed their appointment",
+    "transition_speech": "Great, I've got that noted."
+  }
+}
+```
+
+| Field | Type | Description |
+|---|---|---|
+| `id` | string | Unique edge ID |
+| `source` | string | ID of the originating node |
+| `target` | string | ID of the destination node |
+| `data.label` | string | Short label shown in the workflow builder |
+| `data.condition` | string | Natural language condition the LLM evaluates to trigger this edge |
+| `data.transition_speech` | string | Optional speech the agent says before transitioning |
+
+---
+
+## Validation rules
+
+- All `source` and `target` IDs in edges must reference existing node IDs
+- All nodes except `trigger`, `webhook`, and `qa` must have a non-empty `prompt`
+- Node IDs must be unique within the workflow
+- Each workflow must have exactly one `startCall` or `trigger` node as the entry point
+
+---
+
+## Minimal example
+
+```json
+{
+  "nodes": [
+    {
+      "id": "start-1",
+      "type": "startCall",
+      "position": { "x": 0, "y": 0 },
+      "data": {
+        "name": "Start",
+        "prompt": "You are a friendly assistant. Greet the caller and ask how you can help."
+      }
+    },
+    {
+      "id": "end-1",
+      "type": "endCall",
+      "position": { "x": 400, "y": 0 },
+      "data": {
+        "name": "End",
+        "prompt": "Thank the caller and say goodbye."
+      }
+    }
+  ],
+  "edges": [
+    {
+      "id": "edge-1",
+      "source": "start-1",
+      "target": "end-1",
+      "data": {
+        "label": "Done",
+        "condition": "The caller's question has been answered and they want to end the call"
+      }
+    }
+  ]
+}
+```

docs/docs.json

@@ -12,6 +12,7 @@
     "tabs": [
       {
         "tab": "Guides",
+        "icon": "book-open",
         "groups": [
           {
             "group": "Getting started",
@@ -26,6 +27,16 @@
               }
             ]
           },
+          {
+            "group": "Core Concepts",
+            "pages": [
+              "core-concepts/how-dograh-works",
+              "core-concepts/workflows-and-agents",
+              "core-concepts/calls-and-runs",
+              "core-concepts/context-and-variables",
+              "core-concepts/campaigns"
+            ]
+          },
           {
             "group": "Configurations",
             "pages": [
@@ -75,10 +86,31 @@
             ]
           },
           {
-            "group": "Contribution",
+            "group": "Telephony",
             "pages": [
-              "contribution/introduction",
-              "contribution/setup"
+              "integrations/telephony/overview",
+              "integrations/telephony/inbound",
+              "integrations/telephony/twilio",
+              "integrations/telephony/vonage",
+              "integrations/telephony/cloudonix",
+              "integrations/telephony/vobiz",
+              "integrations/telephony/asterisk-ari",
+              "integrations/telephony/webhooks",
+              "integrations/telephony/custom"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "Developer",
+        "icon": "code",
+        "groups": [
+          {
+            "group": "Guides",
+            "pages": [
+              "developer/workflow-schema",
+              "developer/webhooks",
+              "developer/environment-variables"
             ]
           },
           {
@@ -92,24 +124,88 @@
             ]
           },
           {
-            "group": "Features",
+            "group": "Contribution",
             "pages": [
-              "features/campaigns",
-              "features/looptalk"
+              "contribution/introduction",
+              "contribution/setup"
+            ]
+          }
+        ]
+      },
+      {
+        "tab": "API Reference",
+        "icon": "square-terminal",
+        "groups": [
+          {
+            "group": "Resources",
+            "pages": [
+              {
+                "group": "API Keys",
+                "pages": [
+                  "api-reference/api-keys",
+                  "api-reference/api-keys/create",
+                  "api-reference/api-keys/list",
+                  "api-reference/api-keys/archive",
+                  "api-reference/api-keys/reactivate"
+                ]
+              },
+              {
+                "group": "Agents",
+                "pages": [
+                  "api-reference/agents",
+                  "api-reference/agents/create-from-definition",
+                  "api-reference/agents/create-from-template",
+                  "api-reference/agents/list",
+                  "api-reference/agents/count",
+                  "api-reference/agents/get",
+                  "api-reference/agents/update",
+                  "api-reference/agents/archive",
+                  "api-reference/agents/validate",
+                  {
+                    "group": "Runs",
+                    "pages": [
+                      "api-reference/agents/runs/create",
+                      "api-reference/agents/runs/list",
+                      "api-reference/agents/runs/get"
+                    ]
+                  }
+                ]
+              },
+              {
+                "group": "Calls",
+                "pages": [
+                  "api-reference/calls",
+                  "api-reference/calls/trigger",
+                  "api-reference/calls/initiate",
+                  "api-reference/calls/get-run",
+                  "api-reference/calls/download",
+                  "api-reference/calls/inbound"
+                ]
+              },
+              {
+                "group": "Campaigns",
+                "pages": [
+                  "api-reference/campaigns",
+                  "api-reference/campaigns/upload-contacts",
+                  "api-reference/campaigns/create",
+                  "api-reference/campaigns/list",
+                  "api-reference/campaigns/get",
+                  "api-reference/campaigns/update",
+                  "api-reference/campaigns/start",
+                  "api-reference/campaigns/pause",
+                  "api-reference/campaigns/resume",
+                  "api-reference/campaigns/progress",
+                  "api-reference/campaigns/runs"
+                ]
+              }
             ]
           },
           {
-            "group": "Telephony",
+            "group": "Authentication & Errors",
             "pages": [
-              "integrations/telephony/overview",
-              "integrations/telephony/inbound",
-              "integrations/telephony/twilio",
-              "integrations/telephony/vonage",
-              "integrations/telephony/cloudonix",
-              "integrations/telephony/vobiz",
-              "integrations/telephony/asterisk-ari",
-              "integrations/telephony/webhooks",
-              "integrations/telephony/custom"
+              "api-reference/overview",
+              "api-reference/authentication",
+              "api-reference/errors"
             ]
           }
         ]
@@ -137,18 +233,19 @@
   "search": {
     "prompt": "Search for Tools, Webhook, Deployment, etc..."
   },
+  "openapi": "/api-reference/openapi.json",
   "customCSS": "/custom.css",
   "contextual": {
     "options": [
-     "copy",
-     "view",
-     "chatgpt",
-     "claude",
-     "perplexity",
-     "mcp",
-     "cursor",
-     "vscode"
-   ]
+      "copy",
+      "view",
+      "chatgpt",
+      "claude",
+      "perplexity",
+      "mcp",
+      "cursor",
+      "vscode"
+    ]
   },
   "footer": {
     "socials": {
@@ -156,4 +253,4 @@
       "linkedin": "https://linkedin.com/company/dograh"
     }
   }
-}
+}

docs/features/campaigns.mdx

@@ -1,14 +0,0 @@
----
-title: "Campaigns"
-description: "Campaigns are how you can do outbound calling to your contacts."
----
-
-## Setting up
-
-It is recommended to setup telephony first using the documentation in [Telephony Integrations](/telephony/twilio).
-
-## Preparing the list of contacts
-
-You can upload a CSV list on the platform which will be used to make the calls.
-
-Rest of the documentation coming soon..

docs/features/looptalk.mdx

@@ -1,8 +0,0 @@
----
-title: "Looptalk"
-description: "You can use Looptalk to test your voice agent against another voice agent. This way, you can test your voice agents at scale and iteratively improve the Agent's prompts."
----
-
-## Setting up
-
-Documentation coming soon..

docs/voice-agent/editing-a-workflow.mdx

@@ -29,7 +29,7 @@ Contains instructions applicable across the entire call:
 ## Node-Level Toggles
 
 ### Add Global Prompt
-- Recommended to inject Global Node instructions into most nodes
+- Recommended to inject [Global Node](/voice-agent/global) instructions into most nodes
 
 ### Allow Interruption
 - **Default "On"**: Bot stops and responds to user interruption
@@ -46,7 +46,7 @@ Supported in Agent and End Call Nodes:
 - Define name, type, and description
 - Examples: customer name, budget, interest
 
-## Webhook Node
+## [Webhook Node](/voice-agent/webhook)
 
 - Executed at call end
 - Sends payload to specific endpoint
@@ -63,5 +63,5 @@ Supported in Agent and End Call Nodes:
 ## Pathways and Tool Calls
 
 - Define agent node movement
-- Use tool calls to transition between nodes
+- Use [tool calls](/voice-agent/tools/http-api) to transition between nodes
 - **"tool"** is a reserved keyword for function calls and actions

docs/voice-agent/template-variables.mdx

@@ -4,7 +4,7 @@ description: "You can use Template Variables in your prompts for your Agent node
 ---
 
 ### Template Rendering
-You can reference template variables which is passed as `initial_context` either using the API Trigger or when uploading a Sheet for a campaign. You can also use any extracted variable as `gathered_context`
+You can reference template variables which is passed as [`initial_context`](/core-concepts/context-and-variables#initial_context) either using the [API Trigger](/voice-agent/api-trigger) or when uploading a Sheet for a [campaign](/core-concepts/campaigns). You can also use any extracted variable as [`gathered_context`](/core-concepts/context-and-variables#gathered_context)
 
 The template rendering can take nested values. 
 
@@ -25,4 +25,4 @@ You can write your prompt to access the user's name as below
 Prompt: `You are Alice, who is talking to {{initial_context.user.name}}.`
 
 ### Nodes
-Dograh Voice Agents are composed of various nodes. These nodes can provide instructions to the voice agent, help you setup a trigger where you can trigger the voice agent to call someone, or help you setup a webhook, where you can update the results of the call in your CRM or trigger a downstream workflow in n8n. In the next steps, we will be documenting the nodes that you can use in building the voice agent.
+Dograh Voice Agents are composed of various nodes. These nodes can provide instructions to the voice agent, help you setup a [trigger](/voice-agent/api-trigger) where you can trigger the voice agent to call someone, or help you setup a [webhook](/voice-agent/webhook), where you can update the results of the call in your CRM or trigger a downstream workflow in n8n. In the next steps, we will be documenting the nodes that you can use in building the voice agent.

docs/voice-agent/webhook.mdx

@@ -26,8 +26,8 @@ The payload can contain a valid JSON, and you can reference variables while cons
 - `{{workflow_run_id}}` Unique ID of the Agent run
 - `{{workflow_id}}` ID of the Agent
 - `{{workflow_name}}` Name of the workflow
-- `{{initial_context.*}}` Initial context variables
-- `{{gathered_context.*}}` Extracted variables
+- `{{initial_context.*}}` [Initial context variables](/core-concepts/context-and-variables#initial_context)
+- `{{gathered_context.*}}` [Extracted variables](/core-concepts/context-and-variables#gathered_context)
 - `{{cost_info.call_duration_seconds}}` Call duration
 - `{{recording_url}}` Call recording URL
 - `{{transcript_url}}` Transcript URL