duvo.ai Cases API

openapi: 3.2.0
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:
                          type:
                          - string
                          - 'null'
                        claimed_by_run_id:
                          type:
                          - string
                          - 'null'
                        completed_at:
                          type:
                          - string
                          - 'null'
                        postponed_to:
                          type:
                          - string
                          - 'null'
                        created_at:
                          type: string
                        updated_at:
                          type: string
                        created_by_user_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        created_by_user_name:
                          type:
                          - string
                          - 'null'
                        created_by_user_email:
                          type:
                          - string
                          - 'null'
                        agent_run_status:
                          type:
                          - string
                          - 'null'
                        agent_run_user_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        pending_human_request_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        pending_approval_batch_id:
                          type:
                          - string
                          - 'null'
                          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:
                          type:
                          - object
                          - 'null'
                          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:
                          type:
                          - string
                          - 'null'
                        claimed_by_run_id:
                          type:
                          - string
                          - 'null'
                        completed_at:
                          type:
                          - string
                          - 'null'
                        postponed_to:
                          type:
                          - string
                          - 'null'
                        created_at:
                          type: string
                        updated_at:
                          type: string
                        created_by_user_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        created_by_user_name:
                          type:
                          - string
                          - 'null'
                        created_by_user_email:
                          type:
                          - string
                          - 'null'
                        agent_run_status:
                          type:
                          - string
                          - 'null'
                        agent_run_user_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        pending_human_request_id:
                          type:
                          - string
                          - 'null'
                          format: uuid
                        pending_approval_batch_id:
                          type:
                          - string
                          - 'null'
                          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:
                          type:
                          - object
                          - 'null'
                          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:
                        type:
                        - string
                        - 'null'
                      claimed_by_run_id:
                        type:
                        - string
                        - 'null'
       

# --- truncated at 32 KB (146 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/duvo-ai/refs/heads/main/openapi/duvoai-cases-api-openapi.yml