--- 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.