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

* docs: add developer and api reference tabs

* fix: remove duplicate image

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.