Running Assignments via API

Overview

The Duvo Public API enables programmatic access to run Assignments from your own applications, scripts, or automation pipelines. Instead of triggering runs through the Duvo web interface, you can integrate Assignments directly into your workflows.

Key Concepts

Assignments (Agents): Assignments are configured through the Duvo web interface with specific instructions, connections, and capabilities. The Public API allows you to trigger runs of these pre-configured assignments.

Runs: A run represents a single execution of an Assignment. When you start a run, the Assignment begins working on its configured task. Runs are asynchronous—the API returns immediately with run information, and you poll for status updates.

Sandboxes: Sandboxes are isolated file environments where you can upload files before starting a run. If your Assignment needs to process files (CSVs, documents, images, etc.), you first upload them to a sandbox, then reference that sandbox when starting the run.

Human-in-the-Loop (HITL): Some Assignments may require human input during execution. When this happens, the run enters a "waiting" status. You can provide a webhook URL when starting a run to receive notifications when human input is needed, then respond via the API.

Base URL

All API endpoints are available at:

https://api.duvo.ai/v1

Rate Limiting

The API enforces rate limits per API key (300 requests per minute). Rate limit information is included in response headers:

Header

Description

x-ratelimit-limit

Maximum requests allowed in the window

x-ratelimit-remaining

Requests remaining in current window

x-ratelimit-reset

Unix timestamp when the window resets

retry-after

Seconds to wait before retrying (when rate limited)

When rate limited, the API returns a 429 Too Many Requests response.

Authentication

All Public API requests require authentication using an API key. API keys are scoped to a team and inherit the permissions of the user who created them.

API Key Format

API keys follow the format dv_<random> (e.g., dv_abc123xyz789...). They are approximately 35 characters long.

Using Your API Key

Include your API key in the Authorization header as a Bearer token:

curl -X GET "https://api.duvo.ai/v1/health" \
  -H "Authorization: Bearer dv_your_api_key_here"

Creating API Keys in the UI

Navigate to Settings → API Keys in the Duvo web interface
Click Create API Key
Enter a descriptive name for the key (e.g., "Production Pipeline", "CI/CD Integration")
Click Create
Copy the key immediately — it will only be shown once and cannot be retrieved later

⚠️ Important: Store your API key securely. Treat it like a password. If you lose it, you'll need to create a new one.

Managing API Keys

From the API Keys settings page, you can:

View all keys for your team, including who created them and when they were last used
Delete keys that are no longer needed or may have been compromised

Only team Admins and Owners can create and manage API keys.

Key Security

Keys are hashed before storage — Duvo cannot retrieve your full key
Keys can be revoked at any time by deleting them
The last_used_at timestamp helps you identify unused keys
Optional expiration can be set when creating keys programmatically

Endpoints

Runs

Start a Run

post

Start a new agent run. Returns immediately with run info - does not wait for completion.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Body

agent_idstring · uuidRequired

The agent ID to run

sandbox_idstringOptional

Optional sandbox ID with pre-uploaded files

webhook_urlstring · uriOptional

Webhook URL to POST events to (human_request, run_completed, run_failed, run_interrupted)

Responses

201

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

post

/v1/runs

POST /v1/runs HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 107

{
  "agent_id": "123e4567-e89b-12d3-a456-426614174000",
  "sandbox_id": "text",
  "webhook_url": "https://example.com"
}

{
  "run": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "build_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "text",
    "source": "text",
    "sandbox_id": "text",
    "started_at": "text",
    "completed_at": "text",
    "created_at": "text",
    "updated_at": "text",
    "human_in_the_loop_enabled": true
  }
}

Get Run Status

get

Get information about an agent run. Can be polled to check status.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

run_idstring · uuidRequired

Responses

200

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

get

/v1/runs/{run_id}

GET /v1/runs/{run_id} HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "run": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "agent_id": "123e4567-e89b-12d3-a456-426614174000",
    "build_id": "123e4567-e89b-12d3-a456-426614174000",
    "status": "text",
    "source": "text",
    "sandbox_id": "text",
    "started_at": "text",
    "completed_at": "text",
    "created_at": "text",
    "updated_at": "text",
    "human_in_the_loop_enabled": true
  },
  "pending_human_request": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "text",
    "description": "text",
    "created_at": "text",
    "type": "approval",
    "questions": [
      {
        "question": "text",
        "header": "text",
        "options": [
          {
            "label": "text",
            "description": "text"
          }
        ],
        "multi_select": true
      }
    ]
  }
}

Get Run Messages

get

Get paginated messages for an agent run. Messages are returned in chronological order.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

run_idstring · uuidRequired

Query parameters

limitinteger · min: 1 · max: 50Optional

Number of messages per page (1-50, default 20)

Default: 20

offsetintegerOptional

Number of messages to skip

Default: 0

Responses

200

Default Response

application/json

totalnumberRequired

Total number of messages for the run

limitnumberRequired

Number of messages per page

offsetnumberRequired

Number of messages skipped

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

get

/v1/runs/{run_id}/messages

GET /v1/runs/{run_id}/messages HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "messages": [
    {
      "id": "text",
      "type": "text",
      "role": "text",
      "timestamp": "text",
      "text_content": "text",
      "tool_call": {
        "id": "text",
        "name": "text",
        "arguments": {
          "ANY_ADDITIONAL_PROPERTY": "anything"
        }
      },
      "tool_result": {
        "tool_call_id": "text",
        "result": null,
        "error": "text"
      }
    }
  ],
  "total": 1,
  "limit": 1,
  "offset": 1
}

Post a Message to a Run

post

Post a message to an agent run. This will persist the message and resume the agent execution if the run is in a resumable state (waiting, completed, or interrupted).

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

run_idstring · uuidRequired

Body

messagestring · min: 1Required

The message content to send to the agent

Responses

201

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

post

/v1/runs/{run_id}/messages

POST /v1/runs/{run_id}/messages HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 18

{
  "message": "text"
}

{
  "message": {
    "id": "text",
    "type": "text",
    "role": "text",
    "timestamp": "text",
    "text_content": "text"
  }
}

Respond to Human Request

post

Respond to a human-in-the-loop request. Use 'approved' (true/false) for approval-type requests, or 'answers' ({question: answer}) for question-type requests. Only works when the run is in 'waiting' status.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

run_idstring · uuidRequired

request_idstring · uuidRequired

Body

approvedbooleanOptional

For approval-type requests: true to approve, false to deny

Responses

200

Default Response

application/json

400

Default Response

application/json

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

post

/v1/runs/{run_id}/human-requests/{request_id}/respond

POST /v1/runs/{run_id}/human-requests/{request_id}/respond HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62

{
  "answers": {
    "ANY_ADDITIONAL_PROPERTY": "text"
  },
  "approved": true
}

{
  "human_request": {
    "id": "123e4567-e89b-12d3-a456-426614174000",
    "run_id": "123e4567-e89b-12d3-a456-426614174000",
    "title": "text",
    "description": "text",
    "response": "text",
    "responded_at": "text",
    "created_at": "text"
  }
}

Stop a Run

post

Stop an agent run. No-op if the run is not currently running.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

run_idstring · uuidRequired

Responses

200

Default Response

application/json

successbooleanRequired

messagestringOptional

401

Default Response

application/json

403

Default Response

application/json

404

Default Response

application/json

502

Default Response

application/json

post

/v1/runs/{run_id}/stop

POST /v1/runs/{run_id}/stop HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "success": true,
  "message": "text"
}

Sandboxes

Create a Sandbox

post

Create a new sandbox for file uploads. The sandbox can then be used when starting a run.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Responses

201

Default Response

application/json

500

Default Response

application/json

post

/v1/sandboxes

POST /v1/sandboxes HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "sandbox_id": "text",
  "expires_at": "text"
}

Get Upload URLs for a Sandbox

post

Get a presigned URL for uploading a file to the sandbox. Use this for files larger than 10MB.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

sandbox_idstring · min: 1Required

Body

pathstring · min: 1Required

Path where the file will be uploaded (e.g., /workspace/data.csv)

Responses

200

Default Response

application/json

upload_urlstring · uriRequired

pathstringRequired

expires_in_secondsnumberRequired

404

Default Response

application/json

500

Default Response

application/json

post

/v1/sandboxes/{sandbox_id}/upload-urls

POST /v1/sandboxes/{sandbox_id}/upload-urls HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 15

{
  "path": "text"
}

{
  "upload_url": "https://example.com",
  "path": "text",
  "expires_in_seconds": 1
}

Get Files in a Sandbox

get

List files in a sandbox directory.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

sandbox_idstring · min: 1Required

Query parameters

pathstringOptionalDefault: /workspace

Responses

200

Default Response

application/json

404

Default Response

application/json

500

Default Response

application/json

get

/v1/sandboxes/{sandbox_id}/files

GET /v1/sandboxes/{sandbox_id}/files HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "files": [
    {
      "name": "text",
      "path": "text",
      "type": "file",
      "size_bytes": 1
    }
  ]
}

Upload Files to a Sandbox

post

Upload a file directly to the sandbox. Maximum file size is 10MB. For larger files, use the upload-urls endpoint.

Authorizations

AuthorizationstringRequired

API key authentication. Get your API key from the Duvo dashboard.

Path parameters

sandbox_idstring · min: 1Required

Responses

201

Default Response

application/json

404

Default Response

application/json

413

Default Response

application/json

500

Default Response

application/json

post

/v1/sandboxes/{sandbox_id}/files

POST /v1/sandboxes/{sandbox_id}/files HTTP/1.1
Host: api.duvo.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*

{
  "path": "text",
  "size_bytes": 1
}

Error Handling

All errors follow a consistent format:

{
  "error": "Error type",
  "message": "Detailed error description"
}

Common HTTP Status Codes

Code

Description

400

Bad Request — Invalid parameters

401

Unauthorized — Missing or invalid API key

403

Forbidden — API key doesn't have access to this resource

404

Not Found — Resource doesn't exist

413

Payload Too Large — File exceeds size limit

429

Too Many Requests — Rate limit exceeded

500

Internal Server Error — Something went wrong on our end

502

Bad Gateway — Upstream service unavailable

Webhooks

Human-in-the-Loop Webhook

When you provide a human_request_webhook_url when starting a run, Duvo will POST to that URL whenever the Assignment needs human input.

Webhook Payload

{
  "event": "human_request_created",
  "run_id": "550e8400-e29b-41d4-a716-446655440000",
  "request_id": "req_789xyz",
  "title": "Confirm data deletion",
  "description": "The agent wants to delete 150 records. Please confirm this action.",
  "created_at": "2024-01-15T10:32:00.000Z"
}

When you receive this webhook, use the Respond to Human Request endpoint to provide your response and resume the run.

Complete Example

Here's a complete example of uploading files and starting a run:

#!/bin/bash
API_KEY="dv_your_api_key"
AGENT_ID="7c9e6679-7425-40de-944b-e07fc1f90ae7"
BASE_URL="https://api.duvo.ai/v1"

# 1. Create a sandbox
SANDBOX_RESPONSE=$(curl -s -X POST "$BASE_URL/sandboxes" \
  -H "Authorization: Bearer $API_KEY")
SANDBOX_ID=$(echo $SANDBOX_RESPONSE | jq -r '.sandbox_id')
echo "Created sandbox: $SANDBOX_ID"

# 2. Upload a file
curl -X POST "$BASE_URL/sandboxes/$SANDBOX_ID/files" \
  -H "Authorization: Bearer $API_KEY" \
  -F "file=@./input-data.csv" \
  -F "path=/workspace/input-data.csv"

# 3. Start a run with the sandbox
RUN_RESPONSE=$(curl -s -X POST "$BASE_URL/runs" \
  -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" \
  -d "{
    \"agent_id\": \"$AGENT_ID\",
    \"sandbox_id\": \"$SANDBOX_ID\"
  }")
RUN_ID=$(echo $RUN_RESPONSE | jq -r '.run.id')
echo "Started run: $RUN_ID"

# 4. Poll for completion
while true; do
  STATUS_RESPONSE=$(curl -s -X GET "$BASE_URL/runs/$RUN_ID" \
    -H "Authorization: Bearer $API_KEY")
  STATUS=$(echo $STATUS_RESPONSE | jq -r '.run.status')
  echo "Run status: $STATUS"

  if [ "$STATUS" = "completed" ] || [ "$STATUS" = "failed" ] || [ "$STATUS" = "stopped" ]; then
    break
  fi

  sleep 5
done

echo "Run finished with status: $STATUS"

# 5. Get the conversation messages
curl -s -X GET "$BASE_URL/runs/$RUN_ID/messages?limit=50" \
  -H "Authorization: Bearer $API_KEY" | jq '.messages'

PreviousUploading Files to Jobs NextAssignment Memory

Last updated 13 days ago

Good night

hashtagOverview

hashtagKey Concepts

hashtagBase URL

hashtagRate Limiting

hashtagAuthentication

hashtagAPI Key Format

hashtagUsing Your API Key

hashtagCreating API Keys in the UI

hashtagManaging API Keys

hashtagKey Security

hashtagEndpoints

hashtagRuns

hashtagStart a Run

hashtagGet Run Status

hashtagGet Run Messages

hashtagPost a Message to a Run

hashtagRespond to Human Request

hashtagStop a Run

hashtagSandboxes

hashtagCreate a Sandbox

hashtagGet Upload URLs for a Sandbox

hashtagGet Files in a Sandbox

hashtagUpload Files to a Sandbox

hashtagError Handling

hashtagWebhooks

hashtagHuman-in-the-Loop Webhook

hashtagComplete Example

Overview

Key Concepts

Base URL

Rate Limiting

Authentication

API Key Format

Using Your API Key

Creating API Keys in the UI

Managing API Keys

Key Security

Endpoints

Runs

Start a Run

Get Run Status

Get Run Messages

Post a Message to a Run

Respond to Human Request

Stop a Run

Sandboxes

Create a Sandbox

Get Upload URLs for a Sandbox

Get Files in a Sandbox

Upload Files to a Sandbox

Error Handling

Webhooks

Human-in-the-Loop Webhook

Complete Example