Composio Triggers API

openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform Account Management Triggers API
  description: Trigger management and execution
  contact:
    name: Composio Support
    url: https://composio.dev/support
    email: support@composio.dev
  license:
    name: Proprietary
    url: https://composio.dev/terms
servers:
- url: https://backend.composio.dev
  description: PRODUCTION API
tags:
- name: Triggers
  description: Trigger management and execution
paths:
  /api/v3/cli/realtime/credentials:
    get:
      summary: Get credentials for CLI realtime events
      description: Get the Pusher key and project nanoId for the CLI realtime trigger channel. The CLI subscribes to private-cli-{project_id}.
      tags:
      - Triggers
      operationId: getCliRealtimeCredentials
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      responses:
        '200':
          description: Credentials for CLI realtime events retrieved successfully
          content:
            application/json:
              schema:
                type: object
                properties:
                  pusher_key:
                    type: string
                    description: The Pusher client key for subscribing to the trigger
                  pusher_cluster:
                    type: string
                    description: The Pusher cluster for subscribing to the trigger
                  project_id:
                    type: string
                    description: 'The project nanoId associated with the API Key provided. Used as part of the CLI channel name: private-cli-{project_id}'
                required:
                - pusher_key
                - pusher_cluster
                - project_id
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/cli/realtime/auth:
    post:
      summary: Authenticate CLI Pusher channel access
      description: Authenticate CLI client access to a private-cli-{nanoId} Pusher channel
      tags:
      - Triggers
      operationId: postCliRealtimeAuth
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                channel_name:
                  type: string
                  description: The channel name to authenticate for
                socket_id:
                  type: string
                  description: The socket ID for Pusher authentication
              required:
              - channel_name
              - socket_id
      responses:
        '200':
          description: Pusher authentication successful
          content:
            application/json:
              schema:
                type: object
                properties:
                  auth:
                    type: string
                    description: The authentication string for Pusher
                  channel_data:
                    type: string
                    description: Channel data for presence channels
                required:
                - auth
        '400':
          description: Invalid channel name
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized. Authentication is required or the provided credentials are invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error occurred during authentication.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/trigger_instances/{slug}/upsert:
    post:
      summary: Create or update a trigger
      description: Creates a new trigger instance or updates an existing one with the same configuration. Triggers listen for events from external services (webhooks or polling) and can invoke your workflows. If a matching trigger already exists and is disabled, it will be re-enabled. Requires a connected account ID to associate the trigger with a specific user connection.
      tags:
      - Triggers
      operationId: postTriggerInstancesBySlugUpsert
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          description: The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).
        required: true
        description: The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).
        name: slug
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                connectedAuthId:
                  type: string
                  format: connectedAccountId
                  description: 'DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.'
                  deprecated: true
                triggerConfig:
                  type: object
                  additionalProperties:
                    nullable: true
                  description: 'DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.'
                  deprecated: true
                connected_account_id:
                  type: string
                  format: connectedAccountId
                  description: Connected account nanoid
                trigger_config:
                  type: object
                  additionalProperties:
                    nullable: true
                  description: Trigger configuration
                version:
                  type: string
                  description: 'DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.'
                  deprecated: true
                  example: latest
                toolkit_versions:
                  anyOf:
                  - type: string
                  - type: object
                    additionalProperties:
                      type: string
                  - nullable: true
                  description: Toolkit version specification. Supports "latest" string or a record mapping toolkit slugs to specific versions.
                  example: latest
      responses:
        '200':
          description: Successfully upserted trigger instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger_id:
                    type: string
                    description: ID of the updated trigger
                  deprecated:
                    type: object
                    properties:
                      uuid:
                        type: string
                        description: ID of the updated trigger
                    required:
                    - uuid
                required:
                - trigger_id
                - deprecated
        '201':
          description: Successfully created trigger instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger_id:
                    type: string
                    description: ID of the updated trigger
                  deprecated:
                    type: object
                    properties:
                      uuid:
                        type: string
                        description: ID of the updated trigger
                    required:
                    - uuid
                required:
                - trigger_id
                - deprecated
        '204':
          description: No content
          content:
            application/json:
              schema:
                type: object
                properties: {}
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trigger instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '408':
          description: Request timeout
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Conflict
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '422':
          description: Unprocessable entity
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/trigger_instances/active:
    get:
      summary: List active triggers
      description: Retrieves all active trigger instances for your project. Triggers listen for events from connected accounts (e.g., new emails, Slack messages, GitHub commits) and can invoke webhooks or workflows. Use filters to find triggers for specific users, connected accounts, or trigger types.
      tags:
      - Triggers
      operationId: getTriggerInstancesActive
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: array
          nullable: true
          items:
            type: string
          description: Array of user IDs to filter triggers by
        required: false
        description: Array of user IDs to filter triggers by
        name: user_ids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: connectedAccountId
          description: Array of connected account IDs to filter triggers by
        required: false
        description: Array of connected account IDs to filter triggers by
        name: connected_account_ids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: authConfigId
          description: Array of auth config IDs to filter triggers by
        required: false
        description: Array of auth config IDs to filter triggers by
        name: auth_config_ids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: triggerInstanceId
          description: Array of trigger IDs to filter triggers by
        required: false
        description: Array of trigger IDs to filter triggers by
        name: trigger_ids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
          description: Array of trigger names to filter triggers by. Case-insensitive (internally normalized to uppercase).
        required: false
        description: Array of trigger names to filter triggers by. Case-insensitive (internally normalized to uppercase).
        name: trigger_names
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: connectedAccountId
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use connected_account_ids instead.'
        deprecated: true
        name: connectedAccountIds
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: authConfigId
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use auth_config_ids instead.'
        deprecated: true
        name: authConfigIds
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
            format: triggerInstanceId
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use trigger_ids instead.'
        deprecated: true
        name: triggerIds
        in: query
      - schema:
          type: boolean
          nullable: true
          default: false
          description: When set to true, includes disabled triggers in the response.
        required: false
        description: When set to true, includes disabled triggers in the response.
        name: show_disabled
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use trigger_names instead.'
        deprecated: true
        name: triggerNames
        in: query
      - schema:
          type: boolean
          nullable: true
          default: false
          description: 'DEPRECATED: Use show_disabled instead'
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use show_disabled instead.'
        deprecated: true
        name: showDisabled
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
          description: Array of connected account UUIDs to filter triggers by
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use connected_account_ids instead.'
        deprecated: true
        name: deprecatedConnectedAccountUuids
        in: query
      - schema:
          type: array
          nullable: true
          items:
            type: string
          description: Array of auth config UUIDs to filter triggers by
        required: false
        description: 'DEPRECATED: This parameter will be removed in a future version. Please use auth_config_ids instead.'
        deprecated: true
        name: deprecatedAuthConfigUuids
        in: query
      - schema:
          type: number
          nullable: true
        required: false
        description: Number of items per page, max allowed is 1000
        name: limit
        in: query
      - schema:
          type: string
        required: false
        description: Cursor for pagination. The cursor is a base64 encoded string of the page and limit. The page is the page number and the limit is the number of items per page. The cursor is used to paginate through the items. The cursor is not required for the first page.
        name: cursor
        in: query
      responses:
        '200':
          description: Successfully retrieved active trigger instances
          content:
            application/json:
              schema:
                type: object
                properties:
                  items:
                    type: array
                    items:
                      type: object
                      properties:
                        uuid:
                          type: string
                          description: Unique identifier of the trigger instance
                        id:
                          type: string
                          format: triggerInstanceId
                          description: Nano ID of the trigger instance
                        connected_account_id:
                          type: string
                          description: ID of the connected account this trigger is associated with
                        trigger_name:
                          type: string
                          description: Name of the trigger
                        connected_account_uuid:
                          type: string
                          description: UUID of the connected account this trigger is associated with
                        user_id:
                          type: string
                          description: ID of the user this trigger is associated with
                        trigger_data:
                          type: string
                          description: Additional data associated with the trigger instance
                        version:
                          type: string
                          description: Version of the trigger instance
                        trigger_config:
                          type: object
                          additionalProperties:
                            nullable: true
                          description: Configuration for the trigger
                        state:
                          type: object
                          additionalProperties:
                            nullable: true
                          description: 'DEPRECATED: This field exposes internal state and will be removed in a future version.'
                          deprecated: true
                        updated_at:
                          type: string
                          description: ISO 8601 timestamp when the trigger instance was updated
                        disabled_at:
                          type: string
                          nullable: true
                          description: ISO 8601 timestamp when the trigger instance was disabled, if applicable
                        disabledAt:
                          type: string
                          nullable: true
                          description: 'DEPRECATED: This parameter will be removed in a future version. Please use disabled_at instead.'
                          deprecated: true
                        connectedAccountId:
                          type: string
                          description: 'DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.'
                          deprecated: true
                        triggerName:
                          type: string
                          description: 'DEPRECATED: This parameter will be removed in a future version. Please use trigger_name instead.'
                          deprecated: true
                        updatedAt:
                          type: string
                          description: 'DEPRECATED: This parameter will be removed in a future version. Please use updated_at instead.'
                          deprecated: true
                        triggerConfig:
                          type: object
                          additionalProperties:
                            nullable: true
                          description: 'DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.'
                          deprecated: true
                        deprecated:
                          type: object
                          properties:
                            createdAt:
                              type: string
                              description: Deprecated created_at for the trigger instance
                          required:
                          - createdAt
                          description: Deprecated fields for the trigger instance
                      required:
                      - id
                      - connected_account_id
                      - trigger_name
                      - connected_account_uuid
                      - user_id
                      - version
                      - trigger_config
                      - state
                      - updated_at
                      - disabled_at
                      - disabledAt
                      - connectedAccountId
                      - triggerName
                      - updatedAt
                      - triggerConfig
                  next_cursor:
                    type: string
                    nullable: true
                  total_pages:
                    type: number
                  current_page:
                    type: number
                  total_items:
                    type: number
                required:
                - items
                - total_pages
                - current_page
                - total_items
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/trigger_instances/manage/{triggerId}:
    delete:
      summary: Delete a trigger
      description: Permanently deletes a trigger instance. This stops the trigger from listening for events and removes it from your project. Use the PATCH endpoint with status "disable" if you want to temporarily pause a trigger instead.
      tags:
      - Triggers
      operationId: deleteTriggerInstancesManageByTriggerId
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: triggerInstanceId
          description: The ID of the trigger instance to delete
        required: true
        description: The ID of the trigger instance to delete
        name: triggerId
        in: path
      responses:
        '200':
          description: Successfully deleted the trigger instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger_id:
                    type: string
                    format: triggerInstanceId
                    description: The ID of the deleted trigger instance
                required:
                - trigger_id
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trigger instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Trigger instance already deleted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Trigger instance already gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
    patch:
      summary: Enable or disable a trigger
      description: Updates the status of a trigger instance to enable or disable it. Disabling a trigger pauses event listening without deleting the trigger configuration. Re-enabling restores the trigger to its active state. Use this for temporary maintenance or to control trigger execution.
      tags:
      - Triggers
      operationId: patchTriggerInstancesManageByTriggerId
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          format: triggerInstanceId
          description: The ID of the trigger instance to update
        required: true
        description: The ID of the trigger instance to update
        name: triggerId
        in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                status:
                  type: string
                  enum:
                  - enable
                  - disable
              required:
              - status
      responses:
        '200':
          description: Successfully updated trigger status
          content:
            application/json:
              schema:
                type: object
                properties:
                  status:
                    type: string
                    enum:
                    - success
                    description: Status of the operation
                required:
                - status
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Trigger instance not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '409':
          description: Trigger instance already enabled/disabled
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '410':
          description: Trigger instance already gone
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '501':
          description: Not implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/triggers_types/list/enum:
    get:
      summary: List trigger type enums
      description: Retrieves a list of all available trigger type enum values that can be used across the API from latest versions of the toolkit only
      tags:
      - Triggers
      operationId: getTriggersTypesListEnum
      security:
      - CookieAuth: []
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      responses:
        '200':
          description: Successfully retrieved trigger enum list
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                description: JSON string containing all trigger enum values
        '400':
          description: Bad request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /api/v3/triggers_types/{slug}:
    get:
      summary: Get trigger type by slug
      description: Retrieve detailed information about a specific trigger type using its slug identifier
      tags:
      - Triggers
      operationId: getTriggersTypesBySlug
      security:
      - ApiKeyAuth: []
      - UserApiKeyAuth: []
      - CookieAuth: []
      parameters:
      - schema:
          type: string
          description: The unique slug identifier for the trigger type. Case-insensitive (internally normalized to uppercase).
          example: SLACK_RECEIVE_MESSAGE
        required: true
        description: The unique slug identifier for the trigger type. Case-insensitive (internally normalized to uppercase).
        name: slug
        in: path
      - schema:
          oneOf:
          - type: 'null'
          - type: string
          - type: object
            additionalProperties:
              type: string
            description: Object representation of parsed bracket notation
        required: false
        description: Toolkit version specification. Use "latest" for latest versions or bracket notation for specific versions per toolkit.
        in: query
        name: toolkit_versions
        examples:
          latest_version:
            summary: Latest version for all toolkits
            value: latest
          bracket_notation:
            summary: Specific versions using bracket notation
            value: 'Use: toolkit_versions[gmail]=20250930_00&toolkit_versions[slack]=20250929_00'
          null_value:
            summary: No version specified (uses latest)
            value: null
      responses:
        '200':
          description: Successfully retrieved trigger type
          content:
            application/json:
              schema:
                type: object
                properties:
                  slug:
                    type: string
                    description: Unique identifier for the trigger type
                    example: SLACK_RECEIVE_MESSAGE
                  name:
                    type: string
                    description: Human-readable name of the trigger
                    example: New Message in Slack Channel
                  description:
                    type: string
                    description: Detailed description of what the trigger does
                    example: Triggers when a new message is posted to a Slack channel
                  instructions:
                    type: string
                    description: Step-by-step instructions on how to set up and use this trigger
                  type:
                    type: string
                    enum:
                    - webhook
                    - poll
                    description: The trigger mechanism - either webhook (event-based) or poll (scheduled check)
                    example: webhook
                  toolkit:
                    type: object
                    properties:
                      slug:
                        type: string
                        description: Unique identifier for the parent toolkit
                        example: slack
                      name:
                        type: string
                        description: 'Deprecated: Use slug instead'
                        example: Slack
                      logo:
                        type: string
                        description: Logo of the toolkit
                        example: https://example.com/logo.png
                    required:
                    - slug
                    - name
                    - logo
                    description: Information about the toolkit that provides this trigger
                  config:
                    type: object
                    additionalProperties:
                      nullable: true
                    description: Configuration schema required to set up this trigger
                    example:
                      channel_id:
                        type: string
                        required: true
                      message_type:
                        type: enum
                        options:
                        - all
                        - direct
                        - channel
                  payload:
                    type: object
                    additionalProperties:
               

# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/composio/refs/heads/main/openapi/composio-triggers-api-openapi.yml