duvo.ai Sandboxes API
Create sandboxes and upload files for agent runs
OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders Sandboxes API
description: Public API for programmatic access to Duvo. Authenticate with API keys created in the Duvo dashboard.
version: 1.0.0
servers:
- url: https://api.duvo.ai
description: Production server
tags:
- name: Sandboxes
description: Create sandboxes and upload files for agent runs
paths:
/v2/sandboxes:
post:
operationId: createSandbox
tags:
- Sandboxes
description: Create a new sandbox for file uploads. The returned sandbox_id can be passed to POST /v2/teams/:team_id/runs to stage data for a run.
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
sandbox_id:
type: string
description: The newly created sandbox's identifier
expires_at:
type: string
description: ISO 8601 timestamp when the sandbox will expire
required:
- sandbox_id
- expires_at
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Create Sandbox
/v2/sandboxes/{sandbox_id}/upload-urls:
post:
operationId: createSandboxUploadUrl
tags:
- Sandboxes
description: Get a presigned URL for uploading a file into a sandbox. Use for files larger than 10MB; smaller files can be uploaded directly via POST /v2/sandboxes/:sandbox_id/files.
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
path:
type: string
minLength: 1
description: Path where the file will be uploaded (e.g. /workspace/data.csv)
required:
- path
parameters:
- schema:
type: string
minLength: 1
in: path
name: sandbox_id
required: true
description: The sandbox's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
upload_url:
type: string
format: uri
description: Presigned upload URL
path:
type: string
description: Path the file will be uploaded to
expires_in_seconds:
type: number
description: Seconds until the presigned URL expires
required:
- upload_url
- path
- expires_in_seconds
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Create Sandbox Upload URL
/v2/sandboxes/{sandbox_id}/files:
get:
operationId: listSandboxFiles
tags:
- Sandboxes
description: List files in a sandbox directory.
parameters:
- schema:
default: /workspace
type: string
in: query
name: path
required: false
description: Directory to list files from (defaults to /workspace)
- schema:
type: string
minLength: 1
in: path
name: sandbox_id
required: true
description: The sandbox's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
files:
type: array
items:
type: object
properties:
name:
type: string
description: File or directory name (basename)
path:
type: string
description: Absolute path inside the sandbox
type:
type: string
enum:
- file
- dir
description: Whether this entry is a regular file or a directory
size_bytes:
type: number
description: Size of the file in bytes (0 for directories)
required:
- name
- path
- type
- size_bytes
additionalProperties: false
description: Entries in the requested directory
required:
- files
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: List Sandbox Files
post:
operationId: uploadSandboxFile
tags:
- Sandboxes
description: Upload a file directly to the sandbox. Maximum file size is 10MB. For larger files, use POST /v2/sandboxes/:sandbox_id/upload-urls.
parameters:
- schema:
type: string
minLength: 1
in: path
name: sandbox_id
required: true
description: The sandbox's unique identifier
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
path:
type: string
description: Path the file was uploaded to
size_bytes:
type: number
description: Size of the uploaded file in bytes
required:
- path
- size_bytes
additionalProperties: false
'400':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'401':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'403':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'404':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'413':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
'500':
description: Default Response
content:
application/json:
schema:
type: object
properties:
error:
type: string
message:
type: string
required:
- error
additionalProperties: false
summary: Upload Sandbox File
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
description: API key authentication. Get your API key from the Duvo dashboard.