---
title: "Create or update a trigger"
method: POST
path: "/api/v3.1/trigger_instances/{slug}/upsert"
tags: ["Triggers"]
---

# Create or update a trigger

`POST /api/v3.1/trigger_instances/{slug}/upsert`

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.

## Path parameters

- `slug` string, required — The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).

## Request body

- object
  - `connectedAuthId` string, connectedAccountId — DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.
  - `triggerConfig` object — DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.
  - `connected_account_id` string, connectedAccountId — 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` string — 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 and the project has 2FA enabled, user_id is validated against the owner of that connection.
  - `trigger_config` object — Trigger configuration
  - `version` string — DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.
  - `toolkit_versions` union — Toolkit version specification. Supports "latest" string or a record mapping toolkit slugs to specific versions.
    - string
    - object
    - unknown

## Response `200`

Successfully upserted trigger instance

- object
  - `trigger_id` string, required — ID of the updated trigger

## Other responses

- `201` — Successfully created trigger instance
- `204` — No content
- `400` — Bad request
- `401` — Unauthorized
- `403` — Forbidden
- `404` — Trigger instance not found
- `408` — Request timeout
- `409` — Conflict
- `410` — Gone
- `422` — Unprocessable entity
- `500` — Internal server error
- `501` — Not implemented

## Changes

- **2026-07-08** `1d3aac1128ef` — 2 warning
  - removed the optional property `deprecated` from the response with the `200` status
  - removed the optional property `deprecated` from the response with the `201` status
- **2026-06-17** `589a7d115a5e` — 3 info
  - the endpoint scheme security `CookieAuth` was removed from the API
  - added the new optional request property `user_id`
  - added the non-success response with the status `403`
- **2026-06-11** `2f373d80a589` — 2 breaking
  - the response property `deprecated` became optional for the status `200`
  - the response property `deprecated` became optional for the status `201`
- **2026-06-09** `c3f42a0d0fcb` — 2 info
  - the response property `deprecated` became required for the status `200`
  - the response property `deprecated` became required for the status `201`
- **2026-06-09** `2f373d80a589` — 2 breaking
  - the response property `deprecated` became optional for the status `200`
  - the response property `deprecated` became optional for the status `201`

[Full history](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/changes/api/v3.1/trigger_instances/:slug/upsert/post.md)

---

[API](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1.md) · [All operations](https://skmtc.dev/composiohq/apis/composio-platform-api-v3-1/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/composiohq/composio-platform-api-v3-1/revisions/4239836857f8/schema)