> ## Documentation Index
> Fetch the complete documentation index at: https://composio-preview.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Create or update a trigger

> 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. Provide either a connected_account_id to pin a specific user connection, or a user_id to auto-resolve the first active connection for that user and the trigger's toolkit. For a trigger that supports both webhooks and polling, Composio chooses the best way for the instance to receive events unless type sets one. When the instance polls because a webhook could not be set up, fallback_reason says why. An existing instance keeps its type, so an upsert asking for the other type returns 409.



## OpenAPI

````yaml /api-reference/openapi-v3.json post /api/v3/trigger_instances/{slug}/upsert
openapi: 3.0.0
info:
  version: 3.0.0
  title: Composio Platform API
  description: >-
    Composio v3 API — legacy endpoints under /api/v3/. Use v3.1 for new
    integrations.
  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: Composio production API
security:
  - ApiKeyAuth: []
tags:
  - name: Authentication
    description: Authentication related endpoints
    x-group: Authentication
  - name: Auth Configs
    description: Authentication configuration management
    x-group: Auth Configs
  - name: Connected Accounts
    description: Connected account management
    x-group: Connected Accounts
  - name: Logs
    description: Logging and monitoring
    x-group: Logs
  - name: OpenAPI
    description: OpenAPI specification management
    x-group: OpenAPI
  - name: Organization
    description: Organization management
    x-group: Organization
  - name: API Keys
    description: API key management
    x-group: API Keys
  - name: Webhooks
    description: Webhook configuration
    x-group: Webhooks
  - name: Webhook Endpoints
    description: >-
      Per-OAuth-app webhook ingress endpoints. Inbound URLs the provider posts
      to, plus signing secret storage and verification.
    x-group: Webhook Endpoints
  - name: Webhook Subscriptions
    description: >-
      Webhook delivery subscriptions. Outbound URLs Composio posts trigger
      events to, plus signing secret rotation and event-type filters.
    x-group: Webhook Subscriptions
  - name: Team
    description: Team member management
    x-group: Team
  - name: Consumer Skills
    description: Organization-authored Skill management
    x-group: Consumer Skills
  - name: Toolkits
    description: Toolkit and tool management
    x-group: Toolkits
  - name: Tools
    description: Tool execution endpoints
    x-group: Tools
  - name: Triggers
    description: Trigger management and execution
    x-group: Triggers
  - name: Payments
    description: Payment and subscription management
    x-group: Payments
  - name: Billing
    description: Dashboard billing state — usage, subscription, contract (cookie-auth only)
    x-group: Billing
  - name: Compliance
    description: Organization compliance agreements and acceptance state
    x-group: Compliance
  - name: Files
    description: File management
    x-group: Files
  - name: MCP
    description: MCP server management
    x-group: MCP
  - name: MCP Partner
    description: MCP partner management
    x-group: MCP Partner
  - name: Stripe Projects
    description: Stripe Projects provisioning
    x-group: Stripe Projects
  - name: Tool Router
    description: (Labs) Tool router endpoints
    x-group: Sessions (Prev Tool Router)
  - name: Playground
    description: Dashboard playground chat
    x-group: Playground
  - name: Arena
    description: Arena conversations, messages and terms
    x-group: Arena
  - name: Organization Management
    description: Organization Management API endpoints.
    x-group: Organization Management
  - name: Projects
    description: Projects API endpoints.
    x-group: Projects
paths:
  /api/v3/trigger_instances/{slug}/upsert:
    post:
      tags:
        - Triggers
      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. Provide
        either a connected_account_id to pin a specific user connection, or a
        user_id to auto-resolve the first active connection for that user and
        the trigger's toolkit. For a trigger that supports both webhooks and
        polling, Composio chooses the best way for the instance to receive
        events unless type sets one. When the instance polls because a webhook
        could not be set up, fallback_reason says why. An existing instance
        keeps its type, so an upsert asking for the other type returns 409.
      operationId: postTriggerInstancesBySlugUpsert
      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: {}
                  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. Optional when user_id is provided
                    — the first active connection for that user and the
                    trigger's toolkit is auto-resolved.
                user_id:
                  type: string
                  description: >-
                    The user id (entity id) that owns the connection. When
                    connected_account_id is omitted, the first active connection
                    for this user and the trigger's toolkit is auto-resolved
                    (same as tool execution). When connected_account_id is also
                    provided, user_id is checked against that connection: always
                    against a SHARED connection's ACL (user_id is then
                    required), and against a PRIVATE connection's owner when the
                    project has 2FA enabled.
                egress_url:
                  type: string
                  nullable: true
                  maxLength: 2048
                  format: uri
                  description: >-
                    Overrides the delivery URL for this trigger instance only:
                    its events are sent to this HTTPS URL instead of the project
                    webhook URL. Your project webhook subscription is still
                    required and still controls signing (the webhook secret),
                    the payload version and which events are enabled; only the
                    destination changes for this instance. Omit to leave the
                    current value unchanged; pass null to remove the override
                    and deliver to the project webhook URL again.
                trigger_config:
                  type: object
                  additionalProperties: {}
                  description: Trigger configuration
                type:
                  type: string
                  enum:
                    - poll
                    - webhook
                  description: >-
                    Whether this instance receives events by webhook or by
                    polling, for a trigger that supports both. Omit it to let
                    Composio choose the best one.
                polling_interval:
                  type: integer
                  minimum: 1
                  maximum: 10080
                  description: >-
                    Minutes between polls, for an instance that polls for its
                    events. It is checked whenever the instance could poll, even
                    when Composio tries a webhook first, so an interval outside
                    the toolkit's allowed range fails the request.
                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
                      type: object
                  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
                  type:
                    type: string
                    enum:
                      - webhook
                      - poll
                    description: >-
                      How this trigger instance gets events: webhook (the
                      provider notifies) or poll (a scheduled check).
                    example: webhook
                  fallback_reason:
                    type: string
                    nullable: true
                    description: >-
                      Set when Composio downgraded to a poll-based mechanism
                      instead of webhooks for this trigger.
                    example: >-
                      No webhook endpoint found for toolkit "gmail". Create a
                      webhook endpoint before setting up triggers.
                  polling_interval:
                    type: integer
                    nullable: true
                    description: Minutes between scheduled polls for a poll instance.
                    example: 15
                required:
                  - trigger_id
                  - type
                  - fallback_reason
                  - polling_interval
        '201':
          description: Successfully created trigger instance
          content:
            application/json:
              schema:
                type: object
                properties:
                  trigger_id:
                    type: string
                    description: ID of the updated trigger
                  type:
                    type: string
                    enum:
                      - webhook
                      - poll
                    description: >-
                      How this trigger instance gets events: webhook (the
                      provider notifies) or poll (a scheduled check).
                    example: webhook
                  fallback_reason:
                    type: string
                    nullable: true
                    description: >-
                      Set when Composio downgraded to a poll-based mechanism
                      instead of webhooks for this trigger.
                    example: >-
                      No webhook endpoint found for toolkit "gmail". Create a
                      webhook endpoint before setting up triggers.
                  polling_interval:
                    type: integer
                    nullable: true
                    description: Minutes between scheduled polls for a poll instance.
                    example: 15
                required:
                  - trigger_id
                  - type
                  - fallback_reason
                  - polling_interval
        '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'
        '403':
          description: Forbidden
          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'
        '429':
          description: Too many requests
          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'
      security:
        - ApiKeyAuth: []
        - UserApiKeyAuth: []
components:
  schemas:
    Error:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            code:
              type: number
            slug:
              type: string
            status:
              type: number
            request_id:
              type: string
            suggested_fix:
              type: string
            errors:
              type: array
              items:
                type: string
          required:
            - message
            - code
            - slug
            - status
      required:
        - error
  securitySchemes:
    ApiKeyAuth:
      type: apiKey
      in: header
      name: x-api-key
      description: >-
        Your Composio project API key. Create or copy it from the Composio
        dashboard.
      x-default: your-project-api-key
    UserApiKeyAuth:
      type: apiKey
      in: header
      name: x-user-api-key
      description: Your Composio user API key for user-scoped endpoints.
      x-default: your-user-api-key

````