duvo.ai Agents API

openapi: 3.2.0
info:
  title: Duvo Public Agent Folders Agents 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: Agents
  description: Create and manage agents for automation workloads
paths:
  /v2/agent/{agentId}/eval-scores:
    get:
      operationId: getEvalScores
      tags:
      - Agents
      description: Aggregate evaluation counts and flag distribution for an Assignment's Jobs since the given timestamp.
      parameters:
      - schema:
          type: string
          format: date-time
        in: query
        name: since
        required: true
        description: ISO 8601 timestamp; only Jobs evaluated after this are counted
      - schema:
          type: string
          enum:
          - all
          - custom
        in: query
        name: scope
        required: false
        description: When 'custom', only counts Jobs scored against the target revision's custom rubrics, and only `custom__*` rubric flags. Defaults to 'all' (platform + custom rubrics).
      - schema:
          type: string
          format: uuid
        in: query
        name: revision_id
        required: false
        description: Target a specific Assignment revision instead of the live revision. Only honoured when scope='custom' — non-custom scopes aggregate across all revisions. Defaults to the live revision when omitted.
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier (Assignment ID)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  total_evaluated:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  with_issues:
                    type: integer
                    minimum: -9007199254740991
                    maximum: 9007199254740991
                  flag_distribution:
                    type: array
                    items:
                      type: object
                      properties:
                        flag:
                          type: string
                        count:
                          type: integer
                          minimum: -9007199254740991
                          maximum: 9007199254740991
                        label:
                          type:
                          - string
                          - 'null'
                      required:
                      - flag
                      - count
                      additionalProperties: false
                required:
                - total_evaluated
                - with_issues
                - flag_distribution
                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: Get Eval Scores
  /v2/agents/{agentId}/eval-rubrics:
    get:
      operationId: getEvalRubrics
      tags:
      - Agents
      description: 'List the evaluation rubrics a Run is scored against: the platform default rubrics plus the Agent-specific rubrics for a build. Defaults to the Agent''s live build; pass build_id to target the revision a specific Run ran against.'
      parameters:
      - schema:
          type: string
          format: uuid
        in: query
        name: build_id
        required: false
        description: Return rubrics for this specific build (the revision a Run ran against). Defaults to the agent's live build when omitted.
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier (Assignment ID)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  rubrics:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        slug:
                          type: string
                        title:
                          type: string
                        description:
                          type: string
                        sort_order:
                          type: number
                        deleted_at:
                          type:
                          - string
                          - 'null'
                      required:
                      - id
                      - slug
                      - title
                      - description
                      - sort_order
                      - deleted_at
                      additionalProperties: false
                  platform_rubrics:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        label:
                          type: string
                        description:
                          type: string
                        cause:
                          type: string
                      required:
                      - key
                      - label
                      - description
                      - cause
                      additionalProperties: false
                required:
                - rubrics
                - platform_rubrics
                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: Get Eval Rubrics
    post:
      operationId: createEvalRubric
      tags:
      - Agents
      description: Add one Agent-specific evaluation rubric to a build. A build may hold at most 5 custom rubrics; this fails with 409 once that ceiling is reached. Defaults to the Agent's live build; pass build_id to target a specific revision.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 3
                  maxLength: 80
                  description: Short, human-readable Pass/Fail rubric title.
                description:
                  type: string
                  minLength: 20
                  maxLength: 400
                  description: A 1-2 sentence Pass condition phrased as a question.
                build_id:
                  description: Add the rubric to this build (revision). Defaults to the agent's live build when omitted.
                  type: string
                  format: uuid
              required:
              - title
              - description
              additionalProperties: false
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier (Assignment ID)
      security:
      - bearerAuth: []
      responses:
        '201':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  rubric:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      slug:
                        type: string
                      title:
                        type: string
                      description:
                        type: string
                      sort_order:
                        type: number
                      deleted_at:
                        type:
                        - string
                        - 'null'
                    required:
                    - id
                    - slug
                    - title
                    - description
                    - sort_order
                    - deleted_at
                    additionalProperties: false
                required:
                - rubric
                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
        '409':
          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 Eval Rubric
    put:
      operationId: replaceEvalRubrics
      tags:
      - Agents
      description: Replace a build's entire Agent-specific evaluation rubric set in one call (at most 5 rubrics). Existing custom rubrics are removed and the supplied list becomes the new set; pass an empty array to clear them. Defaults to the Agent's live build; pass build_id to target a specific revision.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                rubrics:
                  maxItems: 5
                  type: array
                  items:
                    type: object
                    properties:
                      title:
                        type: string
                        minLength: 3
                        maxLength: 80
                        description: Short, human-readable Pass/Fail rubric title.
                      description:
                        type: string
                        minLength: 20
                        maxLength: 400
                        description: A 1-2 sentence Pass condition phrased as a question.
                    required:
                    - title
                    - description
                    additionalProperties: false
                  description: The complete custom rubric set for the build. Replaces every existing custom rubric; pass an empty array to clear them.
                build_id:
                  description: Replace the custom rubrics on this build (revision). Defaults to the agent's live build when omitted.
                  type: string
                  format: uuid
              required:
              - rubrics
              additionalProperties: false
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier (Assignment ID)
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  rubrics:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                          format: uuid
                        slug:
                          type: string
                        title:
                          type: string
                        description:
                          type: string
                        sort_order:
                          type: number
                        deleted_at:
                          type:
                          - string
                          - 'null'
                      required:
                      - id
                      - slug
                      - title
                      - description
                      - sort_order
                      - deleted_at
                      additionalProperties: false
                  platform_rubrics:
                    type: array
                    items:
                      type: object
                      properties:
                        key:
                          type: string
                        label:
                          type: string
                        description:
                          type: string
                        cause:
                          type: string
                      required:
                      - key
                      - label
                      - description
                      - cause
                      additionalProperties: false
                required:
                - rubrics
                - platform_rubrics
                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
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
                additionalProperties: false
      summary: Replace Eval Rubrics
  /v2/agents/{agentId}/eval-rubrics/{rubricId}:
    patch:
      operationId: updateEvalRubric
      tags:
      - Agents
      description: Edit a single Agent-specific evaluation rubric's title and/or description. The edit produces a NEW rubric (with a new id and slug) so previously scored Runs stay attributed to the original criterion; the response contains the new rubric.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                title:
                  type: string
                  minLength: 3
                  maxLength: 80
                  description: Short, human-readable Pass/Fail rubric title.
                description:
                  type: string
                  minLength: 20
                  maxLength: 400
                  description: A 1-2 sentence Pass condition phrased as a question.
              additionalProperties: false
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier (Assignment ID)
      - schema:
          type: string
          format: uuid
        in: path
        name: rubricId
        required: true
        description: The custom rubric's unique identifier
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  rubric:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      slug:
                        type: string
                      title:
                        type: string
                      description:
                        type: string
                      sort_order:
                        type: number
                      deleted_at:
                        type:
                        - string
                        - 'null'
                    required:
                    - id
                    - slug
                    - title
                    - description
                    - sort_order
                    - deleted_at
                    additionalProperties: false
                required:
                - rubric
                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
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
                additionalProperties: false
      summary: Update Eval Rubric
    delete:
      operationId: deleteEvalRubric
      tags:
      - Agents
      description: Remove a single Agent-specific evaluation rubric. Future Runs on the build are no longer scored against it.
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier (Assignment ID)
      - schema:
          type: string
          format: uuid
        in: path
        name: rubricId
        required: true
        description: The custom rubric's unique identifier
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  success:
                    type: boolean
                required:
                - success
                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
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  message:
                    type: string
                required:
                - error
                additionalProperties: false
      summary: Delete Eval Rubric
  /v2/agents/{agent_id}:
    get:
      operationId: getAgent
      tags:
      - Agents
      description: Get an agent by ID.
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agent_id
        required: true
        description: The agent's unique identifier
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  agent:
                    type: object
                    properties:
                      id:
                        type: string
                        format: uuid
                      name:
                        type: string
                      slack_enabled:
                        type:
                        - boolean
                        - 'null'
                      microsoft_teams_enabled:
                        type:
                        - boolean
                        - 'null'
                      agentic_memory_enabled:
                        type:
                        - boolean
                        - 'null'
                      team_id:
                        type:
                        - string
                        - 'null'
                      thread_id:
                        type:
                        - string
                        - 'null'
                      folder_id:
                        type:
                        - string
                        - 'null'
                      automation_id:
                        type:
                        - string
                        - 'null'
                        format: uuid
                      created_at:
                        type:
                        - string
                        - 'null'
                      updated_at:
                        type:
                        - string
                        - 'null'
                      created_by:
                        type:
                        - object
                        - 'null'
                        properties:
                          id:
                            type: string
                          name:
                            type:
                            - string
                            - 'null'
                          email:
                            type: string
                        required:
                        - id
                        - name
                        - email
                        additionalProperties: false
                      updated_by:
                        type:
                        - object
                        - 'null'
                        properties:
                          id:
                            type: string
                          name:
                            type:
                            - string
                            - 'null'
                          email:
                            type: string
                        required:
                        - id
                        - name
                        - email
                        additionalProperties: false
                    required:
                    - id
                    - name
                    - slack_enabled
                    - microsoft_teams_enabled
                    - agentic_memory_enabled
                    - team_id
                    - thread_id
                    - created_at
                    - updated_at
                    additionalProperties: false
                  user_context:
                    type: object
                    properties:
                      pinned_at:
                        type:
                        - string
                        - 'null'
                    required:
                    - pinned_at
                    additionalProperties: false
                required:
                - agent
                - user_context
                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:
            applica

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