> ## Documentation Index
> Fetch the complete documentation index at: https://docs.duvo.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add Automation Agent

> Add an agent to an automation on a team that is on the Automations workspace, with or without revisions — membership is not versioned. The agent must not already belong to another automation; on a team that changes its automations by revision it cannot be moved between them at all, because the revisions binding it are immutable. Adding an agent that is already a member succeeds unchanged. When the automation runs as the team, the agent's personal triggers and schedules are turned off, and the add fails with 409 if its live revision sends cases to a queue in an automation that runs as its members. An agent left behind by a deleted automation that ran as the team cannot join one that runs as its members (409). Adding to an automation that runs as the team also fails with 409 when a change in flight holds the rows the add has to update, such as the agent's personal triggers and schedules; that refusal changes nothing and the add can be retried.



## OpenAPI

````yaml https://api.duvo.ai/v2/documentation/mintlify.json post /v2/automations/{automation_id}/agents/{agent_id}
openapi: 3.0.3
info:
  title: Duvo Public API
  description: >-
    Public API for programmatic access to Duvo. Authenticate with API keys
    created in the Duvo dashboard.


    ## Rate limits


    Requests are counted per API key. Every response advertises the quota with
    the IETF RateLimit fields, so a client can self-throttle without waiting for
    a rejection:


    - `RateLimit-Policy: "default";q=<quota>;w=<window seconds>` — the policy in
    force: `q` requests per `w` seconds.

    - `RateLimit: "default";r=<remaining>;t=<seconds>` — the live state: `r`
    requests left, quota resetting in `t` seconds.

    - Read the quota from the headers rather than hard-coding it; it differs per
    environment.

    - The same numbers are also sent as `ratelimit-limit`, `ratelimit-remaining`
    and `ratelimit-reset`.


    Once the quota is exhausted the API answers `429 Too Many Requests` with
    `Retry-After` set to the seconds to wait; honor it instead of retrying
    immediately.
  version: 1.0.0
servers:
  - url: https://api.duvo.ai
    description: Production server
security: []
tags:
  - name: Runs
    description: Start, monitor, and manage agent runs (Runs in the Duvo UI)
  - name: Sandboxes
    description: Create sandboxes and upload files for agent runs
  - name: Queues
    description: Manage queues and their agent bindings
  - name: Cases
    description: Create, list, and manage cases and their labels within queues
  - name: Case Approvals
    description: Submit decisions on pending case approval requests issued by an agent run
  - name: Case Attachments
    description: Upload, list, download, and remove the files attached to a case
  - name: Automations
    description: >-
      List and manage automations — the workspace container that groups the
      agents and queues making up one end-to-end process
  - name: Agents
    description: Create and manage agents for automation workloads
  - name: Revisions
    description: Create and manage agent revisions — the underlying Setup for an Agent
  - name: Agent Folders
    description: Organize agents into folders
  - name: Agent Memory
    description: Read an agent's memory files (the Memory feature in the Duvo UI)
  - name: Suggestions
    description: >-
      List, apply, and dismiss an Agent's improvement suggestions (the
      suggestions inbox in the Duvo UI)
  - name: Notifications
    description: >-
      List, read, dismiss, and clear the authenticated user's team notifications
      (the Notification Center in the Duvo UI)
  - name: Schedules
    description: List schedules configured for an agent
  - name: Duvo Pulse
    description: >-
      Create, list, iterate on, and delete Duvo Pulse dashboards — live,
      agent-generated visualizations of your Duvo data
  - name: Case Triggers
    description: >-
      Configure case triggers that automatically dispatch agent runs (Runs in
      the Duvo UI) for cases added to a queue
  - name: Triggers
    description: >-
      Configure event triggers that start a Run automatically when an external
      event fires (e.g. an email arrives, a Linear issue is created, or a file
      changes in Google Drive)
  - name: Skills
    description: Manage team and system skills (reusable knowledge packs).
  - name: Files
    description: Manage team files.
  - name: Plugins
    description: Discover plugins that can be referenced from a revision.
  - name: Organizations
    description: Inspect organizations you belong to and the teams within them
  - name: Team
    description: Inspect the team and members associated with the API key
  - name: Invites
    description: >-
      Invite people to a team — one at a time or in bulk, scoped to a Clarity
      process or the whole team — and manage the team's shareable invite link
  - name: Integrations
    description: Browse the team's catalog of available integration types
  - name: Connections
    description: Manage your connected integrations
  - name: Credentials
    description: >-
      Manage logins (domain + username + password + TOTP) used by agents to sign
      in to websites and desktop applications, and attach them to assignment
      revisions
  - name: Secrets
    description: >-
      Manage env-var secrets injected into runs, and attach them to assignment
      revisions. Only metadata is exposed; values are never returned
  - name: Revision Integrations
    description: >-
      Attach integrations to assignment revisions, pin specific connections, and
      link queues
  - name: ClarityV2
    description: >-
      Manage Clarity v2 process snapshots, automation proposals, and the
      extra-capture-request follow-up loop
paths:
  /v2/automations/{automation_id}/agents/{agent_id}:
    post:
      tags:
        - Automations
      summary: Add Automation Agent
      description: >-
        Add an agent to an automation on a team that is on the Automations
        workspace, with or without revisions — membership is not versioned. The
        agent must not already belong to another automation; on a team that
        changes its automations by revision it cannot be moved between them at
        all, because the revisions binding it are immutable. Adding an agent
        that is already a member succeeds unchanged. When the automation runs as
        the team, the agent's personal triggers and schedules are turned off,
        and the add fails with 409 if its live revision sends cases to a queue
        in an automation that runs as its members. An agent left behind by a
        deleted automation that ran as the team cannot join one that runs as its
        members (409). Adding to an automation that runs as the team also fails
        with 409 when a change in flight holds the rows the add has to update,
        such as the agent's personal triggers and schedules; that refusal
        changes nothing and the add can be retried.
      operationId: addAutomationAgent
      parameters:
        - schema:
            type: string
            format: uuid
          in: path
          name: automation_id
          required: true
          description: Automation ID
        - schema:
            type: string
            format: uuid
          in: path
          name: agent_id
          required: true
          description: Agent ID
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  current:
                    type: object
                    properties:
                      automation_id:
                        type: string
                        format: uuid
                        description: Automation this view was computed for
                      ai_description:
                        nullable: true
                        description: >-
                          AI-generated short description of what the automation
                          does (null until generated). Read from the automation
                          itself, not from a revision — the revision-less home
                          for the overview.
                        type: string
                      ai_summary:
                        nullable: true
                        description: >-
                          AI-generated detailed overview of the automation —
                          business and technical (null until generated)
                        type: string
                      overview_generated_at:
                        nullable: true
                        description: >-
                          ISO 8601 timestamp of the automation's last AI
                          overview generation
                        type: string
                      agent_count:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: >-
                          Number of member agents with a live build — the length
                          of `agents`, matching the revision detail's semantics.
                          Not the automation's member count: a member with no
                          live build has no binding to report and is absent from
                          both. Use `automation.agent_count` for members.
                      queue_count:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: Number of member queues
                      trigger_count:
                        type: integer
                        minimum: -9007199254740991
                        maximum: 9007199254740991
                        description: Number of triggers firing for the members
                      agents:
                        type: array
                        items:
                          type: object
                          properties:
                            agent_id:
                              type: string
                              format: uuid
                              description: Agent identifier
                            build_id:
                              type: string
                              format: uuid
                              description: Build referenced for the agent in this revision
                          required:
                            - agent_id
                            - build_id
                          additionalProperties: false
                        description: Member agents, each with the build that runs now
                      queues:
                        type: array
                        items:
                          type: object
                          properties:
                            case_queue_id:
                              type: string
                              format: uuid
                              description: Queue identifier
                            agent_id:
                              nullable: true
                              description: >-
                                Agent the queue routes to in this revision (null
                                when unrouted)
                              type: string
                              format: uuid
                            enabled:
                              type: boolean
                              description: Whether the queue's routing is enabled
                            name:
                              nullable: true
                              description: >-
                                Per-revision queue name override (null to keep
                                the queue's own name)
                              type: string
                            description:
                              nullable: true
                              description: Per-revision queue description override
                              type: string
                          required:
                            - case_queue_id
                            - agent_id
                            - enabled
                            - name
                            - description
                          additionalProperties: false
                        description: Member queues with the agent each routes new cases to
                      triggers:
                        type: array
                        items:
                          type: object
                          properties:
                            automation_trigger_id:
                              type: string
                              nullable: true
                              enum:
                                - null
                              description: >-
                                Always null: the current view is derived from
                                legacy trigger rows, which carry no declaration
                                identity
                            agent_id:
                              type: string
                              format: uuid
                              description: Agent this trigger routes to
                            integration_slug:
                              type: string
                              description: >-
                                Integration the declaration watches, e.g.
                                `gmail`
                            trigger_type:
                              type: string
                              description: >-
                                Trigger type within the integration, e.g.
                                `new_email`
                            filter_config:
                              type: object
                              additionalProperties: {}
                              description: Per-revision trigger filter configuration
                            enabled:
                              type: boolean
                              description: >-
                                Whether the trigger is switched on for any
                                member
                          required:
                            - automation_trigger_id
                            - agent_id
                            - integration_slug
                            - trigger_type
                            - filter_config
                            - enabled
                          additionalProperties: false
                        description: Triggers firing for the member agents
                      schedules:
                        type: array
                        items:
                          type: object
                          properties:
                            automation_schedule_id:
                              type: string
                              nullable: true
                              enum:
                                - null
                              description: >-
                                Always null: the current view is derived from
                                legacy schedule rows, which carry no declaration
                                identity
                            agent_id:
                              type: string
                              format: uuid
                              description: Agent this schedule fires
                            cron:
                              nullable: true
                              description: >-
                                5-field cron expression; when set, the frequency
                                form is unused
                              type: string
                            frequency:
                              nullable: true
                              description: Frequency form, used when `cron` is null
                              type: string
                              enum:
                                - hourly
                                - daily
                                - workday
                                - weekly
                                - monthly
                            time:
                              nullable: true
                              description: >-
                                Local time of day as HH:MM, for the frequency
                                form
                              type: string
                            timezone:
                              type: string
                              description: IANA timezone the schedule is evaluated in
                            day:
                              nullable: true
                              description: Day of week for a weekly schedule
                              type: string
                              enum:
                                - monday
                                - tuesday
                                - wednesday
                                - thursday
                                - friday
                                - saturday
                                - sunday
                            day_of_month:
                              nullable: true
                              description: Day of month for a monthly schedule
                              type: integer
                              minimum: 1
                              maximum: 31
                            task:
                              nullable: true
                              description: Prompt passed as the run's initial user message
                              type: string
                            enabled:
                              type: boolean
                              description: >-
                                Whether the schedule is switched on for any
                                member
                          required:
                            - automation_schedule_id
                            - agent_id
                            - cron
                            - frequency
                            - time
                            - timezone
                            - day
                            - day_of_month
                            - task
                            - enabled
                          additionalProperties: false
                        description: Recurring schedules firing for the member agents
                    required:
                      - automation_id
                      - ai_description
                      - ai_summary
                      - overview_generated_at
                      - agent_count
                      - queue_count
                      - trigger_count
                      - agents
                      - queues
                      - triggers
                      - schedules
                    additionalProperties: false
                    description: The automation's setup after the change
                required:
                  - current
                additionalProperties: false
        '401':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '403':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '404':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
        '409':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                  code:
                    type: string
                required:
                  - error
                additionalProperties: false
        '500':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                required:
                  - error
                additionalProperties: false
      security:
        - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your API key from the Duvo dashboard.

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.