openapi: 3.0.3
info:
  title: Duvo Public Agent Folders Triggers 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: 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)
paths:
  /v2/triggers/{agentId}:
    get:
      operationId: listAgentTriggers
      tags:
      - Triggers
      description: List the trigger definitions the authenticated user owns on an agent (Agent in the Duvo UI). Triggers start a Run automatically when an external event fires (e.g. an email arrives or a Linear issue is created).
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  triggers:
                    type: array
                    items:
                      type: object
                      properties:
                        id:
                          type: string
                        agent_id:
                          type: string
                        user_id:
                          type: string
                        integration_slug:
                          type: string
                        trigger_type:
                          type: string
                        filter_config:
                          type: object
                          additionalProperties: {}
                        integration_instance_id:
                          type: string
                        enabled:
                          type: boolean
                        auto_disabled_at:
                          nullable: true
                          type: string
                        auto_disabled_reason:
                          nullable: true
                          type: string
                        consecutive_missing_connection_failures:
                          type: integer
                          minimum: 0
                          maximum: 9007199254740991
                        first_missing_connection_failure_at:
                          nullable: true
                          type: string
                        last_missing_connection_failure_at:
                          nullable: true
                          type: string
                        created_at:
                          type: string
                        updated_at:
                          type: string
                      required:
                      - id
                      - agent_id
                      - user_id
                      - integration_slug
                      - trigger_type
                      - filter_config
                      - integration_instance_id
                      - enabled
                      - auto_disabled_at
                      - auto_disabled_reason
                      - consecutive_missing_connection_failures
                      - first_missing_connection_failure_at
                      - last_missing_connection_failure_at
                      - created_at
                      - updated_at
                      additionalProperties: false
                required:
                - triggers
                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: List Agent Triggers
    put:
      operationId: upsertAgentTrigger
      tags:
      - Triggers
      description: 'Create or update the authenticated user''s trigger for an integration on an agent. The integration must already be connected to the agent (its OAuth connection set up in the Duvo dashboard). Set `enabled: false` to pause a trigger without deleting it.'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                integration_slug:
                  type: string
                  description: Integration slug the trigger fires for (e.g. `gmail`, `outlook`, `linear-native`, `google-drive`).
                trigger_type:
                  type: string
                  description: Trigger type within the integration (e.g. `email_received`). Discover valid values via the trigger types endpoint.
                filter_config:
                  description: Integration-specific filter config (e.g. sender/subject filters). Shape comes from the integration's filter schema.
                  default: {}
                  type: object
                  additionalProperties: {}
                enabled:
                  default: true
                  description: Whether the trigger is active. Defaults to true.
                  type: boolean
              required:
              - integration_slug
              - trigger_type
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                  agent_id:
                    type: string
                  user_id:
                    type: string
                  integration_slug:
                    type: string
                  trigger_type:
                    type: string
                  filter_config:
                    type: object
                    additionalProperties: {}
                  integration_instance_id:
                    type: string
                  enabled:
                    type: boolean
                  auto_disabled_at:
                    nullable: true
                    type: string
                  auto_disabled_reason:
                    nullable: true
                    type: string
                  consecutive_missing_connection_failures:
                    type: integer
                    minimum: 0
                    maximum: 9007199254740991
                  first_missing_connection_failure_at:
                    nullable: true
                    type: string
                  last_missing_connection_failure_at:
                    nullable: true
                    type: string
                  created_at:
                    type: string
                  updated_at:
                    type: string
                required:
                - id
                - agent_id
                - user_id
                - integration_slug
                - trigger_type
                - filter_config
                - integration_instance_id
                - enabled
                - auto_disabled_at
                - auto_disabled_reason
                - consecutive_missing_connection_failures
                - first_missing_connection_failure_at
                - last_missing_connection_failure_at
                - created_at
                - updated_at
                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: Upsert Agent Trigger
  /v2/trigger-config/{agentId}:
    get:
      operationId: listAgentTriggerTypes
      tags:
      - Triggers
      description: List the trigger types available for an agent, grouped by integration. Use the returned `integration_slug` and `trigger_type` values when creating a trigger.
      parameters:
      - schema:
          type: string
          format: uuid
        in: path
        name: agentId
        required: true
        description: The agent's unique identifier
      security:
      - bearerAuth: []
      responses:
        '200':
          description: Default Response
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger_types:
                    type: array
                    items:
                      type: object
                      properties:
                        integration_slug:
                          type: string
                        integration_name:
                          type: string
                        icon_url:
                          type: string
                        trigger_type:
                          type: string
                        label:
                          type: string
                        description:
                          type: string
                        filter_schema:
                          type: object
                          additionalProperties: {}
                      required:
                      - integration_slug
                      - integration_name
                      - icon_url
                      - trigger_type
                      - label
                      - description
                      - filter_schema
                      additionalProperties: false
                required:
                - trigger_types
                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: List Agent Trigger Types
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: API key authentication. Get your API key from the Duvo dashboard.