Developer Platform API

The Duvo Public API lets you drive Duvo from your own code, scripts, and pipelines. This page is the orientation hub: what you can do, which endpoints to reach for, and how to put them together into real integrations. For request and response schemas, follow the links into the API Reference.

What you can do with the API

Goal	Entities involved
Start a Run from your application or pipeline	Runs
Create and update Agents programmatically	Agents, Revisions
Sync AOPs from a Git repository into Duvo	Skills
Push work items into a queue from an external system	Queues, Cases
Schedule recurring Runs	Schedules
Connect and provision Connections without the UI	Connections
Upload files for an Agent to process	Sandboxes

Authentication

All requests use an API key in the Authorization header:

curl https://api.duvo.ai/v2/teams/$TEAM_ID/agents \
  -H "Authorization: Bearer $DUVO_API_KEY"

Generate a key at Your Profile → API keys in the Duvo dashboard — scope it to a single team or to all teams you can access. Users with the Manager role or above can also create keys for a specific team at Team Settings → API keys. Keys inherit the permissions of the user who created them, use the format dv_<random>, and are shown once at creation, so store them immediately.

Base URL: https://api.duvo.ai/v2
Rate limit: 300 requests per minute per API key. Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset headers. On 429, honor the retry-after header.
Error model: errors return { "error": "...", "message": "..." } with a standard HTTP status code (400, 401, 403, 404, 413, 429, 5xx).

API keys are shown once at creation and inherit the permissions of the user who created them. Store them securely, treat them like a password, and stay under the 300 requests per minute per-key rate limit — on a 429, honor the retry-after header.

For the full auth, rate-limit, and error reference, see Running Agents via API.

Collection endpoints are team-scoped (/teams/\{teamId\}/...); endpoints that act on a specific resource are addressed directly by ID (/agents/\{agent_id\}, /runs/\{run_id\}).

Agents and Revisions

Agents are the units of work in Duvo. A Revision is a versioned snapshot of an Agent’s Setup — AOP, model settings, and attached skills. Runs always run against an Agent’s latest Revision. What you can do:

List, create, and update Agents
Create Revisions to deploy AOP changes programmatically
Organize Agents into folders

Action	Method	Path
List Agents	`GET`	`/teams/{teamId}/agents`
Create an Agent	`POST`	`/teams/{teamId}/agents`
Get an Agent	`GET`	`/agents/{agent_id}`
Update an Agent	`PATCH`	`/agents/{agent_id}`
List Revisions	`GET`	`/agents/{agent_id}/revisions`
Create a Revision	`POST`	`/agents/{agent_id}/revisions`

See the API Reference for request and response schemas, and Creating Agents via API for worked examples including folders and the full create flow. You can create an Agent and its first Revision in a single request — pass a build object in the body:

curl -X POST https://api.duvo.ai/v2/teams/$TEAM_ID/agents \
  -H "Authorization: Bearer $DUVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Invoice Processor",
    "build": {
      "name": "v1",
      "config": {
        "version": "v2",
        "data": {
          "input": "Process invoices from uploaded files, extract line items, and post a summary to Slack."
        }
      }
    }
  }'

Organize Agents into folders:

Action	Method	Path
List folders	`GET`	`/teams/{teamId}/agent-folders`
Create a folder	`POST`	`/teams/{teamId}/agent-folders`
Update a folder	`PATCH`	`/agent-folders/{folder_id}`
Delete a folder	`DELETE`	`/agent-folders/{folder_id}`
Move Agents to folder	`POST`	`/teams/{teamId}/agent-folders/move-agents`

Runs

A Run is a single execution of an Agent. Runs are asynchronous — the API returns immediately and you poll or use a webhook to track completion. What you can do:

Start a Run with optional file input, an initial message, and a webhook for event notifications
Poll for status (pending, running, waiting, completed, failed, stopped)
Read the conversation — everything the Agent did, step by step
Respond to human-in-the-loop requests programmatically
Stop a running Run

Action	Method	Path
Start a Run	`POST`	`/teams/{teamId}/runs`
List Runs	`GET`	`/teams/{teamId}/runs`
Get Run status	`GET`	`/runs/{run_id}`
Read messages	`GET`	`/runs/{run_id}/messages`
Send a message	`POST`	`/runs/{run_id}/messages`
Respond to HITL request	`POST`	`/runs/{run_id}/human-requests/{request_id}/respond`
Stop a Run	`POST`	`/runs/{run_id}/stop`

See the API Reference for schemas, and Running Agents via API for the full flow including file uploads and HITL webhooks. Starting a Run and polling for completion:

#!/bin/bash
# Start a Run
RUN=$(curl -s -X POST https://api.duvo.ai/v2/teams/$TEAM_ID/runs \
  -H "Authorization: Bearer $DUVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d "{\"agent_id\": \"$AGENT_ID\"}")
RUN_ID=$(echo $RUN | jq -r '.run.id')

# Poll until the Run finishes
while true; do
  STATUS=$(curl -s https://api.duvo.ai/v2/runs/$RUN_ID \
    -H "Authorization: Bearer $DUVO_API_KEY" | jq -r '.run.status')
  [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "stopped" ] && break
  sleep 5
done

# Read what the Agent did
curl -s "https://api.duvo.ai/v2/runs/$RUN_ID/messages?limit=100" \
  -H "Authorization: Bearer $DUVO_API_KEY" | jq '.messages[]'

Skills

Skills package reusable knowledge — AOPs, rule books, taxonomies — into a zip that any Agent can use. Managing skills via the API lets you keep your AOPs in a Git repository and sync them to Duvo on every push, without anyone clicking through the UI. What you can do:

List team skills and system skills
Create a skill from text content
Upload a multi-file skill as a zip
Download a skill as a zip
Update individual skill files
Delete a skill

Action	Method	Path
List team skills	`GET`	`/teams/{teamId}/skills`
List system skills	`GET`	`/skills/system`
Create a skill (text)	`POST`	`/teams/{teamId}/skills`
Upload a skill (zip)	`POST`	`/teams/{teamId}/skills/upload`
Get skill files	`GET`	`/skills/{skill_id}/files`
Get a skill file	`GET`	`/skills/{skill_id}/files/{path}`
Update a skill file	`PUT`	`/skills/{skill_id}/files/{path}`
Download skill as zip	`GET`	`/skills/{skill_id}/download`
Delete a skill	`DELETE`	`/skills/{skill_id}`

See the API Reference for schemas and Creating Custom Skills for how to structure your SKILL.md files. Creating a skill from text:

curl -X POST https://api.duvo.ai/v2/teams/$TEAM_ID/skills \
  -H "Authorization: Bearer $DUVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "refund-policy",
    "description": "Guidelines for processing customer refund requests. Use when evaluating refund eligibility or drafting refund responses.",
    "content": "---\nname: refund-policy\ndescription: Guidelines for processing customer refund requests.\n---\n\n# Refund Policy\n\nRefunds are accepted within 30 days of purchase..."
  }'

Uploading a multi-file skill as a zip: A zip must contain a SKILL.md at the root with name and description frontmatter. Supporting documents, templates, and examples can live in subfolders.

# Zip your skill folder first
cd my-skill && zip -r ../my-skill.zip . && cd ..

curl -X POST https://api.duvo.ai/v2/teams/$TEAM_ID/skills/upload \
  -H "Authorization: Bearer $DUVO_API_KEY" \
  -F "file=@my-skill.zip"

Syncing skills from a Git repository (CI example): This script pushes a directory of skill folders to Duvo on every deploy. It deletes stale skills by name and re-creates them from the latest source.

#!/bin/bash
# skills-sync.sh — run on every push to your skills repo
DUVO_API_KEY="${DUVO_API_KEY}"
TEAM_ID="${DUVO_TEAM_ID}"
BASE_URL="https://api.duvo.ai/v2"
SKILLS_DIR="./skills"  # directory of skill folders

# Fetch existing team skills
EXISTING=$(curl -s "$BASE_URL/teams/$TEAM_ID/skills" \
  -H "Authorization: Bearer $DUVO_API_KEY")

for SKILL_DIR in "$SKILLS_DIR"/*/; do
  SKILL_NAME=$(basename "$SKILL_DIR")

  # Delete the old version if it exists
  OLD_ID=$(echo $EXISTING | jq -r ".skills[] | select(.name == \"$SKILL_NAME\") | .id")
  if [ -n "$OLD_ID" ] && [ "$OLD_ID" != "null" ]; then
    curl -s -X DELETE "$BASE_URL/skills/$OLD_ID" \
      -H "Authorization: Bearer $DUVO_API_KEY"
    echo "Deleted old version of $SKILL_NAME"
  fi

  # Zip and upload the updated skill
  cd "$SKILL_DIR" && zip -r "/tmp/${SKILL_NAME}.zip" . && cd -
  RESULT=$(curl -s -X POST "$BASE_URL/teams/$TEAM_ID/skills/upload" \
    -H "Authorization: Bearer $DUVO_API_KEY" \
    -F "file=@/tmp/${SKILL_NAME}.zip")
  echo "Uploaded $SKILL_NAME: $(echo $RESULT | jq -r '.skill.id')"
done

echo "Skill sync complete."

Queues and Cases

Queues hold individual work items — called Cases — that Agents process one at a time. You can push Cases into a queue from any external system, which makes it the standard pattern for high-volume integrations where events arrive faster than a single Agent can handle them. What you can do:

List and inspect queues
Push Cases into a queue (one at a time or in batch)
List and search Cases in a queue
Bulk-update, bulk-reprocess, or bulk-delete Cases
Track Case status through the processing lifecycle

Action	Method	Path
List queues	`GET`	`/teams/{teamId}/queues`
Get a queue	`GET`	`/queues/{queue_id}`
List Cases in a queue	`GET`	`/queues/{queue_id}/cases`
Search Cases	`POST`	`/queues/{queue_id}/cases/search`
Create Cases	`POST`	`/queues/{queue_id}/cases`
Bulk-update Case status	`POST`	`/queues/{queue_id}/cases/bulk-update-status`
Bulk-reprocess Cases	`POST`	`/queues/{queue_id}/cases/bulk-reprocess`
Bulk-delete Cases	`POST`	`/queues/{queue_id}/cases/bulk-delete`
Delete a Case	`DELETE`	`/cases/{case_id}`

See the API Reference for schemas. Case statuses:

Status	Meaning
`pending`	Waiting to be picked up
`claimed`	An Agent is actively working on it
`completed`	Processing finished successfully
`failed`	Processing failed

When listing Cases you can also filter by needs_input (Cases with an open human request) and postponed (Cases scheduled to retry later). These are derived from Case fields (pending_human_request_id, postponed_to) rather than stored status values. Pushing a Case from an external system. Wrap a single Case in a case object. The data field is free-form text or a JSON string — Agents receive it when they claim the Case:

curl -X POST "https://api.duvo.ai/v2/queues/$QUEUE_ID/cases" \
  -H "Authorization: Bearer $DUVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "case": {
      "title": "Order #ORD-20240115-4821",
      "data": "{\"order_id\":\"ORD-20240115-4821\",\"customer_email\":\"buyer@example.com\",\"total\":89.97,\"notes\":\"Gift wrap requested\"}"
    }
  }'

Batch-pushing Cases for high-volume intake. Use a cases array instead:

curl -X POST "https://api.duvo.ai/v2/queues/$QUEUE_ID/cases" \
  -H "Authorization: Bearer $DUVO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "cases": [
      { "title": "Invoice #INV-001", "data": "{\"supplier\":\"ACME\",\"amount\":1200.00}" },
      { "title": "Invoice #INV-002", "data": "{\"supplier\":\"GlobalParts\",\"amount\":580.50}" },
      { "title": "Invoice #INV-003", "data": "{\"supplier\":\"ShipFast\",\"amount\":345.00}" }
    ]
  }'

The response returns the created Cases under added_cases, each with its id and status. Once Cases are in the queue, an Agent with a Case Trigger picks them up automatically — see Queue for how to configure the trigger. Validate queue wiring before you start work. Check that a Revision’s queue integration slots are linked to real queues. The response reports, per producer/consumer slot, how many queues are linked. A slot with linked_queue_count of 0 is attached but points at no queue and will fail at runtime — link a queue before starting Runs.

Action	Method	Path
Validate a Revision’s queue	`GET`	`/agents/{agent_id}/revisions/{build_id}/case-queue-validation`

Schedules

You can create, list, update, and delete an Agent’s schedules via the API to run recurring Runs.

Action	Method	Path
List schedules	`GET`	`/agents/{agent_id}/schedules`
Create a schedule	`POST`	`/agents/{agent_id}/schedules`
Update a schedule	`PATCH`	`/agents/{agent_id}/schedules/{schedule_id}`
Delete a schedule	`DELETE`	`/agents/{agent_id}/schedules/{schedule_id}`

See the API Reference for schedule fields and limits.

Connections

Connections link your Agents to external services. The API lets you list and inspect connections, create user-provided connections (custom MCP servers with an API key), and initiate OAuth flows.

Action	Method	Path
List connections	`GET`	`/teams/{teamId}/connections`
Get a connection	`GET`	`/connections/{connection_id}`
Create a connection (user-provided)	`POST`	`/teams/{teamId}/connections`
Update a connection	`PATCH`	`/connections/{connection_id}`
Delete a connection	`DELETE`	`/connections/{connection_id}`
Start native OAuth (Gmail, Sheets, Outlook…)	`POST`	`/teams/{teamId}/connections/oauth/native/{provider}/start`
Probe a connection’s tool catalog	`POST`	`/teams/{teamId}/connections/mcp/probe`

Probe by integration_slug (catalog connections — the backend resolves the server URL for you) or by a custom server_url. A response with success: false includes a code: listing_unavailable means there’s nothing to list yet (not an error — some connections only expose tools once connected), while probe_failed means the probe genuinely failed. See the API Reference for schemas and Creating Agents via API for the full OAuth flows.

Sandboxes and file uploads

When your Agent needs to process files — CSVs, PDFs, images — upload them to a Sandbox before starting the Run, then pass the sandbox_id when you start the run.

Action	Method	Path
Create a Sandbox	`POST`	`/sandboxes`
Get upload URLs	`POST`	`/sandboxes/{sandbox_id}/upload-urls`
Upload a file	`POST`	`/sandboxes/{sandbox_id}/files`
List files	`GET`	`/sandboxes/{sandbox_id}/files`

See the API Reference for schemas and Running Agents via API for the complete file-upload pattern.

End-to-end example: order management integration

This example shows an order management system (OMS) pushing new orders into Duvo for processing whenever they arrive. Duvo validates each order, checks inventory, and posts the result back to the OMS. Architecture:

Configure Duvo

Create an Agent with a Queue trigger pointed at your order-processing queue. The Agent’s AOP instructs it to read Case data, validate the order, check inventory via your ERP connection, and post the result to your OMS webhook.

OMS integration code

const DUVO_API_KEY = process.env.DUVO_API_KEY;
const DUVO_QUEUE_ID = process.env.DUVO_ORDER_QUEUE_ID;
const BASE_URL = "https://api.duvo.ai/v2";

interface Order {
  orderId: string;
  customerEmail: string;
  items: Array<{ sku: string; quantity: number; unitPrice: number }>;
  total: number;
}

async function submitOrderToDuvo(order: Order): Promise<string> {
  const response = await fetch(`${BASE_URL}/queues/${DUVO_QUEUE_ID}/cases`, {
    method: "POST",
    headers: {
      Authorization: `Bearer ${DUVO_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      case: {
        title: `Order ${order.orderId}`,
        data: JSON.stringify(order),
      },
    }),
  });

  if (!response.ok) {
    const err = await response.json();
    throw new Error(`Duvo API error: ${err.error} — ${err.message}`);
  }

  const { added_cases } = await response.json();
  return added_cases[0].id;
}

// Called when a new order arrives in the OMS
async function onNewOrder(order: Order) {
  const caseId = await submitOrderToDuvo(order);
  console.info(`Order ${order.orderId} submitted as Case ${caseId}`);
}

Track results

List Cases to see their status and retrieve Agent output:

# Check failed orders
curl "https://api.duvo.ai/v2/queues/$QUEUE_ID/cases?status=failed" \
  -H "Authorization: Bearer $DUVO_API_KEY" | jq '.cases[] | {id, title, status}'

Next steps

Creating Agents via API

Agents, Revisions, Folders, Connections, Schedules

Running Agents via API

Runs, Sandboxes, HITL webhooks

Creating Custom Skills

How to structure skills for the API

Queue

Queue architecture and Case Trigger setup

API Reference

Full request and response schemas for every endpoint

Welcome

Getting Started

Examples

Building Agents

Running Agents

Agent Features

Skills

Connections

Playbooks

Solutions

Analytics

Advanced

Reliability

Security

Resources

Organizations

Teams

Developer Platform API

What you can do with the API

Authentication

Agents and Revisions

Runs

Skills

Queues and Cases

Schedules

Connections

Sandboxes and file uploads

End-to-end example: order management integration

Next steps

Creating Agents via API

Running Agents via API

Creating Custom Skills

Queue

API Reference

​What you can do with the API

​Authentication

​Agents and Revisions

​Runs

​Skills

​Queues and Cases

​Schedules

​Connections

​Sandboxes and file uploads

​End-to-end example: order management integration

​Next steps

Creating Agents via API

Running Agents via API

Creating Custom Skills

Queue

API Reference

What you can do with the API

Authentication

Agents and Revisions

Runs

Skills

Queues and Cases

Schedules

Connections

Sandboxes and file uploads

End-to-end example: order management integration

Next steps