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

* docs: add developer and api reference tabs

* fix: remove duplicate image

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"
+}
+```