--- a/docs/api-reference.md
+++ b/docs/api-reference.md
@@ -1,10 +1,20 @@
 # doany API Reference
 
-Welcome to the doany API. This page documents our endpoints.
+*Last updated: April 12, 2026*
+
+## What Is the doany API?
+
+The doany API is a RESTful interface for creating and orchestrating AI agent workflows. It lets developers define agents with custom tools and instructions, chain them into multi-step workflows with conditional logic, and monitor every execution through structured run logs — all via standard HTTP requests.
 
 ## Authentication
 
-All requests require an API key passed in the `Authorization` header as a Bearer token. You can generate API keys from the doany dashboard at app.doany.ai.
+All requests require an API key passed in the `Authorization` header as a Bearer token:
+
+```
+Authorization: Bearer YOUR_API_KEY
+```
+
+Generate API keys from the doany dashboard at [app.doany.ai](https://app.doany.ai).
 
 ## Base URL
 
@@ -14,15 +24,28 @@
 
 ## Agents
 
+Agents are the core primitive in doany. Each agent wraps an LLM with specific instructions and tools, creating a reusable unit of AI-powered logic that can call tools, chain prompts, and interact with external systems.
+
 ### Create Agent
 
 ```
 POST /v1/agents
 ```
 
-Creates a new agent with the specified configuration. Agents are the core primitive in doany — they represent a reusable unit of AI-powered logic that can call tools, chain LLM prompts, and interact with external systems.
-
-Request body:
+Creates a new agent with the specified configuration.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Unique name for the agent |
+| `model` | string | Yes | LLM model to use (e.g., `claude-sonnet-4-5-20250514`, `gpt-4o`) |
+| `instructions` | string | Yes | System prompt defining the agent's behavior |
+| `tools` | array | No | Function schemas the agent can call during execution |
+| `max_turns` | integer | No | Maximum conversation turns (default: 10) |
+| `timeout_ms` | integer | No | Execution timeout in milliseconds (default: 30000) |
+
+**Example request:**
 
 ```json
 {
@@ -48,7 +71,7 @@
 }
 ```
 
-Response:
+**Example response:**
 
 ```json
 {
@@ -65,7 +88,12 @@
 GET /v1/agents
 ```
 
-Returns all agents in your workspace. Supports pagination via `cursor` and `limit` query params.
+Returns all agents in your workspace. Supports pagination via `cursor` and `limit` query parameters.
+
+| Parameter | Type | Description |
+|-----------|------|-------------|
+| `cursor` | string | Pagination cursor from previous response |
+| `limit` | integer | Results per page (default: 20, max: 100) |
 
 ### Get Agent
 
@@ -73,7 +101,7 @@
 GET /v1/agents/{agent_id}
 ```
 
-Returns details for a specific agent.
+Returns configuration and status for a specific agent.
 
 ### Delete Agent
 
@@ -85,15 +113,26 @@
 
 ## Workflows
 
+Workflows chain multiple agents together. Each step can pass its output to the next step, with support for conditional branching and parallel execution — enabling complex multi-agent pipelines.
+
 ### Create Workflow
 
 ```
 POST /v1/workflows
 ```
 
-Workflows chain multiple agents together. Each step in a workflow can pass its output to the next step, enabling complex multi-agent pipelines.
-
-Request body:
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `name` | string | Yes | Unique name for the workflow |
+| `steps` | array | Yes | Ordered list of workflow steps |
+| `steps[].agent_id` | string | Yes | Agent to execute at this step |
+| `steps[].name` | string | Yes | Step identifier for data mapping |
+| `steps[].input_mapping` | object | No | JSONPath expressions mapping data between steps |
+| `steps[].condition` | string | No | JSONPath condition for conditional execution |
+
+**Example request:**
 
 ```json
 {
@@ -126,9 +165,16 @@
 POST /v1/workflows/{workflow_id}/runs
 ```
 
-Starts a new execution of the workflow. Returns immediately with a run ID. Use the run status endpoint to poll for completion, or configure a webhook.
-
-Request body:
+Starts a new execution of the workflow. Returns immediately with a run ID. Poll the run status endpoint for completion, or configure a webhook for async notification.
+
+**Request body:**
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `input` | object | Yes | Input data passed to the first workflow step |
+| `webhook_url` | string | No | URL to receive a POST when the run completes |
+
+**Example request:**
 
 ```json
 {
@@ -139,7 +185,7 @@
 }
 ```
 
-Response:
+**Example response:**
 
 ```json
 {
@@ -156,17 +202,21 @@
 GET /v1/workflows/{workflow_id}/runs/{run_id}
 ```
 
-Returns the current status and output of a workflow run.
+Returns the current status, output, and step-by-step execution log of a workflow run.
 
 ## Rate Limits
 
-- Free tier: 100 requests/minute
-- Pro tier: 1,000 requests/minute
-- Enterprise: Custom
-
-## Errors
-
-All errors return a JSON body:
+| Tier | Rate Limit | Price |
+|------|-----------|-------|
+| **Free** | 100 requests/minute | $0/month |
+| **Pro** | 1,000 requests/minute | $49/month |
+| **Enterprise** | Custom | Contact sales |
+
+Rate-limited requests return HTTP 429 with a `Retry-After` header.
+
+## Error Handling
+
+All errors return a JSON body with a structured error object:
 
 ```json
 {
@@ -177,8 +227,42 @@
 }
 ```
 
-Common error codes: `invalid_request`, `authentication_failed`, `rate_limited`, `agent_not_found`, `workflow_execution_failed`, `timeout`.
+| Error Code | HTTP Status | Description |
+|-----------|-------------|-------------|
+| `invalid_request` | 400 | Missing or invalid request parameters |
+| `authentication_failed` | 401 | Invalid or missing API key |
+| `rate_limited` | 429 | Request rate exceeded for your tier |
+| `agent_not_found` | 404 | Agent ID does not exist |
+| `workflow_execution_failed` | 500 | Workflow step failed during execution |
+| `timeout` | 408 | Execution exceeded `timeout_ms` |
 
 ## SDKs
 
-We offer official SDKs for Python and TypeScript. See our GitHub repositories for installation and usage.
+doany offers official SDKs for Python and TypeScript:
+
+| SDK | Install | Repository |
+|-----|---------|-----------|
+| **Python** | `pip install doany` | [github.com/doany-ai/doany-python](https://github.com/doany-ai/doany-python) |
+| **TypeScript** | `npm install @doany/sdk` | [github.com/doany-ai/doany-node](https://github.com/doany-ai/doany-node) |
+
+## Frequently Asked Questions
+
+### What models can I use with the doany API?
+
+doany supports models from OpenAI (GPT-4o, GPT-4), Anthropic (Claude Sonnet 4.5, Claude Opus 4), and other providers. Specify the model ID in the `model` field when creating an agent.
+
+### How do I handle long-running workflows?
+
+Use the `webhook_url` parameter when running a workflow. doany sends a POST request to your webhook URL with the completed run data. Alternatively, poll `GET /v1/workflows/{workflow_id}/runs/{run_id}` for status updates.
+
+### Can agents call other agents?
+
+Yes. Use workflows to chain agents sequentially or in parallel with conditional logic. Each step's output can be mapped as input to subsequent steps using JSONPath expressions.
+
+### What happens if an agent's tool call fails?
+
+doany retries tool calls based on your agent's `max_turns` configuration. If all retries fail, the run status is set to `failed` with a detailed error log showing which tool call failed and why.
+
+### Is the doany API SOC 2 compliant?
+
+doany is SOC 2 Type II certified. Enterprise plans include additional security features including SSO, audit logs, and dedicated infrastructure. Contact [sales@doany.ai](mailto:sales@doany.ai) for details.
