duvo.ai Cases API
Create, list, and manage cases and their labels within queues
OpenAPI Specification
openapi: 3.0.3
info:
title: Duvo Public Agent Folders Cases 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: Cases
description: Create, list, and manage cases and their labels within queues
paths:
/v2/queues/{queue_id}/cases:
delete:
operationId: clearQueueCases
tags:
- Cases
description: Delete every case in a queue. Interrupts any associated active runs first. Destructive — not exposed via MCP.
parameters:
- schema:
type: string
format: uuid
in: path
name: queue_id
required: true
description: The queue's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
deletedCount:
type: number
interruptedRunIds:
type: array
items:
type: string
format: uuid
required:
- success
- deletedCount
- interruptedRunIds
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: Clear Queue Cases
get:
operationId: listCases
tags:
- Cases
description: List cases in a queue. Supports status, date-range, and free-text filters via query params. For label filters, use POST /v2/teams/:team_id/queues/:queue_id/cases/search.
parameters:
- schema:
default: 20
type: integer
minimum: 1
maximum: 100
in: query
name: limit
required: false
description: Number of cases per page (1-100, default 20).
- schema:
type: integer
minimum: 0
maximum: 9007199254740991
in: query
name: offset
required: false
description: Zero-based offset for pagination.
- schema:
type: string
in: query
name: status
required: false
description: 'Filter by one or more case statuses (comma-separated). Values: pending, claimed, completed, failed, needs_input, postponed.'
- schema:
type: string
in: query
name: priority
required: false
description: 'Filter by one or more priority levels (comma-separated). Values: none, medium, high.'
- schema:
type: string
in: query
name: search
required: false
description: Full-text search across case title and data.
- schema:
type: string
in: query
name: created_at_from
required: false
description: Return only cases created on or after this ISO-8601 timestamp.
- schema:
type: string
in: query
name: updated_at_from
required: false
description: Return only cases updated on or after this ISO-8601 timestamp.
- schema:
default: created_at
type: string
enum:
- created_at
- updated_at
- postponed_to
in: query
name: sort_by
required: false
description: 'Field to sort by. Default: created_at.'
- schema:
default: desc
type: string
enum:
- asc
- desc
in: query
name: sort_order
required: false
description: 'Sort direction. Default: desc.'
- schema:
type: string
format: uuid
in: path
name: queue_id
required: true
description: The queue's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
cases:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
queue_id:
type: string
format: uuid
title:
type: string
data:
type: string
status:
type: string
enum:
- pending
- completed
- failed
priority:
type: string
enum:
- none
- medium
- high
display_status:
type: string
enum:
- pending
- in_progress
- needs_input
- postponed
- completed
- failed
claimed_at:
nullable: true
type: string
claimed_by_run_id:
nullable: true
type: string
completed_at:
nullable: true
type: string
postponed_to:
nullable: true
type: string
created_at:
type: string
updated_at:
type: string
created_by_user_id:
nullable: true
type: string
format: uuid
created_by_user_name:
nullable: true
type: string
created_by_user_email:
nullable: true
type: string
agent_run_status:
nullable: true
type: string
agent_run_user_id:
nullable: true
type: string
format: uuid
pending_human_request_id:
nullable: true
type: string
format: uuid
pending_approval_batch_id:
nullable: true
type: string
format: uuid
pending_approval_assignee_user_ids:
type: array
items:
type: string
format: uuid
approval_approved_count:
type: integer
minimum: 0
maximum: 9007199254740991
approval_rejected_count:
type: integer
minimum: 0
maximum: 9007199254740991
eval_summary:
nullable: true
type: object
properties:
passed:
type: number
total:
type: number
final_comment:
type: string
status:
type: string
enum:
- ready
- unavailable
- in_progress
severityCounts:
type: object
properties:
critical:
type: integer
minimum: 0
maximum: 9007199254740991
medium:
type: integer
minimum: 0
maximum: 9007199254740991
low:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- critical
- medium
- low
additionalProperties: false
required:
- passed
- total
- status
additionalProperties: false
search_match_data_snippet:
type: object
properties:
before:
type: string
match:
type: string
after:
type: string
required:
- before
- match
- after
additionalProperties: false
labels:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
key:
type: string
value:
type: string
minLength: 1
color_hue:
type: integer
minimum: 0
maximum: 360
required:
- id
- key
- value
- color_hue
additionalProperties: false
required:
- id
- queue_id
- title
- data
- status
- priority
- display_status
- claimed_at
- claimed_by_run_id
- completed_at
- postponed_to
- created_at
- updated_at
- created_by_user_id
- created_by_user_name
- created_by_user_email
- agent_run_status
- agent_run_user_id
- pending_human_request_id
- pending_approval_batch_id
- pending_approval_assignee_user_ids
- approval_approved_count
- approval_rejected_count
- labels
additionalProperties: false
total:
type: number
limit:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
offset:
type: integer
minimum: -9007199254740991
maximum: 9007199254740991
required:
- cases
- total
- limit
- offset
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
'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 Cases
post:
operationId: createCases
tags:
- Cases
description: 'Create one or more cases in a queue. Provide either a single `case` object or a `cases` array (1-100); providing both returns 400. Each case accepts a title (max 500 chars), optional free-form `data`, optional labels that will be assigned to the case on creation (missing labels are created on the queue), and an optional priority (`none`, `medium`, or `high`; `medium`/`high` raise it above the default in the queue, `none` is the default). Priority only affects the order pending cases are picked up in: due postponed cases are handled first, then higher priority.'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
case:
type: object
properties:
title:
type: string
minLength: 1
maxLength: 500
description: Short title for the case (max 500 characters). Put long context in `data`.
data:
description: Additional data for the case. Free-form text or JSON; Agents receive this on claim.
type: string
labels:
description: Optional labels to assign to the case at creation. Labels are created on the queue if they don't already exist.
maxItems: 50
type: array
items:
type: object
properties:
key:
default: ''
description: Label key (omit for a simple tag).
type: string
value:
type: string
minLength: 1
description: Label value (required).
required:
- value
priority:
description: Case priority. `medium` or `high` raise the case above the default in the queue; omit (or `none`) for normal priority. Only set this when the AOP or the user explicitly instructs prioritization — do not infer it on your own.
type: string
enum:
- none
- medium
- high
required:
- title
cases:
minItems: 1
maxItems: 100
type: array
items:
type: object
properties:
title:
type: string
minLength: 1
maxLength: 500
description: Short title for the case (max 500 characters). Put long context in `data`.
data:
description: Additional data for the case. Free-form text or JSON; Agents receive this on claim.
type: string
labels:
description: Optional labels to assign to the case at creation. Labels are created on the queue if they don't already exist.
maxItems: 50
type: array
items:
type: object
properties:
key:
default: ''
description: Label key (omit for a simple tag).
type: string
value:
type: string
minLength: 1
description: Label value (required).
required:
- value
priority:
description: Case priority. `medium` or `high` raise the case above the default in the queue; omit (or `none`) for normal priority. Only set this when the AOP or the user explicitly instructs prioritization — do not infer it on your own.
type: string
enum:
- none
- medium
- high
required:
- title
parameters:
- schema:
type: string
format: uuid
in: path
name: queue_id
required: true
description: The queue's unique identifier
security:
- bearerAuth: []
responses:
'201':
description: Default Response
content:
application/json:
schema:
type: object
properties:
added_cases:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
queue_id:
type: string
format: uuid
title:
type: string
data:
type: string
status:
type: string
enum:
- pending
- completed
- failed
priority:
type: string
enum:
- none
- medium
- high
display_status:
type: string
enum:
- pending
- in_progress
- needs_input
- postponed
- completed
- failed
claimed_at:
nullable: true
type: string
claimed_by_run_id:
nullable: true
type: string
completed_at:
nullable: true
type: string
postponed_to:
nullable: true
type: string
created_at:
type: string
updated_at:
type: string
created_by_user_id:
nullable: true
type: string
format: uuid
created_by_user_name:
nullable: true
type: string
created_by_user_email:
nullable: true
type: string
agent_run_status:
nullable: true
type: string
agent_run_user_id:
nullable: true
type: string
format: uuid
pending_human_request_id:
nullable: true
type: string
format: uuid
pending_approval_batch_id:
nullable: true
type: string
format: uuid
pending_approval_assignee_user_ids:
type: array
items:
type: string
format: uuid
approval_approved_count:
type: integer
minimum: 0
maximum: 9007199254740991
approval_rejected_count:
type: integer
minimum: 0
maximum: 9007199254740991
eval_summary:
nullable: true
type: object
properties:
passed:
type: number
total:
type: number
final_comment:
type: string
status:
type: string
enum:
- ready
- unavailable
- in_progress
severityCounts:
type: object
properties:
critical:
type: integer
minimum: 0
maximum: 9007199254740991
medium:
type: integer
minimum: 0
maximum: 9007199254740991
low:
type: integer
minimum: 0
maximum: 9007199254740991
required:
- critical
- medium
- low
additionalProperties: false
required:
- passed
- total
- status
additionalProperties: false
search_match_data_snippet:
type: object
properties:
before:
type: string
match:
type: string
after:
type: string
required:
- before
- match
- after
additionalProperties: false
labels:
type: array
items:
type: object
properties:
id:
type: string
format: uuid
key:
type: string
value:
type: string
minLength: 1
color_hue:
type: integer
minimum: 0
maximum: 360
required:
- id
- key
- value
- color_hue
additionalProperties: false
required:
- id
- queue_id
- title
- data
- status
- priority
- display_status
- claimed_at
- claimed_by_run_id
- completed_at
- postponed_to
- created_at
- updated_at
- created_by_user_id
- created_by_user_name
- created_by_user_email
- agent_run_status
- agent_run_user_id
- pending_human_request_id
- pending_approval_batch_id
- pending_approval_assignee_user_ids
- approval_approved_count
- approval_rejected_count
- labels
additionalProperties: false
required:
- added_cases
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
'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 Cases
/v2/cases/{case_id}:
get:
operationId: getCase
tags:
- Cases
description: Get a case by ID. Returns the case, its event history, and every case-approval batch ever created on the case (newest first).
parameters:
- schema:
type: string
format: uuid
in: path
name: case_id
required: true
description: The case's unique identifier
security:
- bearerAuth: []
responses:
'200':
description: Default Response
content:
application/json:
schema:
type: object
properties:
case:
type: object
properties:
id:
type: string
format: uuid
queue_id:
type: string
format: uuid
title:
type: string
data:
type: string
status:
type: string
enum:
- pending
- completed
- failed
priority:
type: string
enum:
- none
- medium
- high
display_status:
type: string
enum:
- pending
- in_progress
- needs_input
- postponed
- completed
- failed
claimed_at:
nullable: true
type: string
claimed_by_run_id:
nullable: true
type: string
completed_at:
nullable: true
type: string
postponed_to:
nullable: true
type: string
created_at:
type: string
updated_at:
type: string
created_by_user_id:
nullable: true
type: string
format: uuid
created_by_user_name:
# --- truncated at 32 KB (144 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvoai/refs/heads/main/openapi/duvoai-cases-api-openapi.yml