API ReferenceTriggers

Create or update a triggerv3.0

POST
/api/v3/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.

Authorization

x-api-key<token>

Project API key authentication

In: header

Path Parameters

slugstringRequired

The slug of the trigger instance. Case-insensitive (internally normalized to uppercase).

Request Body

application/json

connectedAuthIdstringDeprecated

DEPRECATED: This parameter will be removed in a future version. Please use connected_account_id instead.

Format: connectedAccountId
triggerConfigobjectDeprecated

DEPRECATED: This parameter will be removed in a future version. Please use trigger_config instead.

connected_account_idstring

Connected account nanoid. Optional when user_id is provided — the first active connection for that user and the trigger's toolkit is auto-resolved.

Format: connectedAccountId
user_idstring

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.

egress_urlnullable string

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.

Format: uri
trigger_configobject

Trigger configuration

versionstringDeprecated

DEPRECATED: This parameter will be removed in a future version. Please use toolkit_versions instead.

toolkit_versionsstring | object | nullable object

Toolkit version specification. Supports "latest" string or a record mapping toolkit slugs to specific versions.

Response Body

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

application/json

curl -X POST "https://example.com/api/v3/trigger_instances/string/upsert" \  -H "Content-Type: application/json" \  -d '{}'
{  "trigger_id": "string"}
Edit this page on GitHub