> ## Documentation Index
> Fetch the complete documentation index at: https://docs.beta.adapter.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Create trigger
## OpenAPI
````yaml POST /v1/triggers
openapi: 3.1.0
info:
title: Adapter API
description: Connect and sync data from any SaaS tool.
version: 0.1.0
servers:
- url: https://api.adapter.com
security:
- ApiKeyAuth: []
tags:
- name: connections
description: Manage OAuth connections to data sources.
paths:
/v1/triggers:
post:
tags:
- Triggers
summary: Create trigger
operationId: create_trigger
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerCreateRequest'
required: true
responses:
'201':
description: Successful Response
content:
application/json:
schema:
$ref: '#/components/schemas/TriggerResponse'
'401':
content:
application/json:
schema:
$ref: '#/components/schemas/AuthenticationErrorModel'
description: Unauthorized
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/PermissionDeniedErrorModel'
description: Forbidden
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/UnprocessableEntityErrorModel'
description: Unprocessable Content
'500':
content:
application/json:
schema:
$ref: '#/components/schemas/InternalServerErrorModel'
description: Internal Server Error
components:
schemas:
TriggerCreateRequest:
properties:
name:
anyOf:
- type: string
maxLength: 128
minLength: 1
- type: 'null'
title: Name
description: >-
Optional display name to tell your triggers apart in lists and the
console. Purely cosmetic — it has no effect on matching or delivery.
examples:
- New-hire emails from recruiting
kind:
anyOf:
- type: string
- items:
type: string
type: array
title: Kind
description: >-
What the trigger fires on — one or more kind ids from `GET
/triggers/kinds`, or a single id as shorthand. Kinds come in two
families: **connector data** kinds (e.g. `email`, `calendar_event`)
that fire on events from your connected accounts, and **entity**
kinds (e.g. `person`, `organization`) that fire when an extracted
entity of that type changes. Use `'*'` to match every kind.
examples:
- - email
- calendar_event
- person
action:
type: string
enum:
- observed
- created
- updated
- deleted
- '*'
title: Action
description: >-
Which change to fire on. `created`/`updated`/`deleted` are lifecycle
changes to the underlying record. `observed` fires whenever an
entity of the given kind is seen in evidence, even if nothing about
it changed — useful for entity kinds. `'*'` matches any action.
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
description: >-
Optional predicate for deeper rules — narrow the trigger beyond kind
+ action by matching against fields on the event payload. A leaf
clause is `{"field": "", "op": "", "value":
...}`; operators are `eq`, `ne`, `exists`, `contains`,
`starts_with`, `ends_with`, `regex`, `in`, `includes`,
`domain_matches`, and `gt`/`lt`/`gte`/`lte`. Clauses compose via
`all` / `any` / `not`, nested to any depth. The fields you can
reference are listed on each kind's `predicate_fields` in `GET
/triggers/kinds`. For entity kinds with `action: observed`, filter
on `entity_urn` — `exists` fires only for observations that resolved
to a known entity, `eq` scopes to one specific entity — or on `via`
(`identity` = structured field like a sender or attendee, `content`
= name found in body text).
examples:
- field: entity_urn
op: exists
- all:
- field: entity_urn
op: eq
value:
- field: via
op: eq
value: content
- field: sender.email
op: domain_matches
value: example.com
entity_observation_fuzzy:
type: boolean
title: Entity Observation Fuzzy
description: >-
For `observed`-action triggers on entity kinds, also match name
variants and minor misspellings — not just exact aliases. Ignored on
other kinds and actions.
default: false
delivery:
$ref: '#/components/schemas/WebhookDelivery'
enabled:
type: boolean
title: Enabled
default: true
type: object
required:
- kind
- action
- delivery
title: TriggerCreateRequest
TriggerResponse:
properties:
id:
type: string
title: Id
user_id:
type: string
title: User Id
name:
anyOf:
- type: string
- type: 'null'
title: Name
description: Display name, if you set one.
kind:
items:
type: string
type: array
title: Kind
description: Kind ids this trigger fires for; ['*'] means any kind.
action:
type: string
title: Action
filter:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Filter
entity_observation_fuzzy:
type: boolean
title: Entity Observation Fuzzy
description: >-
Whether fuzzy-matched entity observations are accepted in addition
to exact matches.
default: false
delivery:
additionalProperties: true
type: object
title: Delivery
enabled:
type: boolean
title: Enabled
secret:
anyOf:
- type: string
- type: 'null'
title: Secret
description: >-
Webhook signing secret, returned only in the create response — store
it. Each delivery carries an 'Adapter-Signature: v1=' header;
verify it by computing HMAC-SHA256 over '.' with this secret and comparing hex
digests. Reject deliveries whose timestamp is older than your replay
window.
created_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Created At
updated_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Updated At
last_fired_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Last Fired At
description: >-
When this trigger last matched an event and delivery was attempted,
including failed deliveries.
last_status:
anyOf:
- type: string
enum:
- delivered
- failed
- type: 'null'
title: Last Status
description: >-
Outcome of your most recent delivery. Null until the trigger first
fires.
consecutive_failures:
type: integer
title: Consecutive Failures
description: >-
Consecutive events that failed to deliver, counted once per event
after its final retry. Resets to 0 on success. At 50 the trigger is
disabled automatically.
default: 0
auto_disabled_at:
anyOf:
- type: string
format: date-time
- type: 'null'
title: Auto Disabled At
description: >-
Set when the trigger was disabled automatically after 50 consecutive
events failed to deliver. Fix your endpoint, then update the trigger
with enabled=true to resume.
type: object
required:
- id
- user_id
- kind
- action
- delivery
- enabled
title: TriggerResponse
AuthenticationErrorModel:
properties:
error_code:
type: string
const: authentication_error
title: Error Code
default: authentication_error
message:
type: string
title: Message
default: Invalid or missing credentials.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: AuthenticationErrorModel
PermissionDeniedErrorModel:
properties:
error_code:
type: string
const: permission_denied
title: Error Code
default: permission_denied
message:
type: string
title: Message
default: You do not have permission to perform this action.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: PermissionDeniedErrorModel
UnprocessableEntityErrorModel:
properties:
error_code:
type: string
const: unprocessable_entity
title: Error Code
default: unprocessable_entity
message:
type: string
title: Message
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
required:
- message
title: UnprocessableEntityErrorModel
InternalServerErrorModel:
properties:
error_code:
type: string
const: internal_server_error
title: Error Code
default: internal_server_error
message:
type: string
title: Message
default: An unexpected error occurred.
details:
anyOf:
- additionalProperties: true
type: object
- type: 'null'
title: Details
type: object
title: InternalServerErrorModel
WebhookDelivery:
properties:
kind:
type: string
const: webhook
title: Kind
default: webhook
url:
type: string
title: Url
description: Target URL to POST events to.
examples:
- https://example.com/hooks/adapter
type: object
required:
- url
title: WebhookDelivery
securitySchemes:
ApiKeyAuth:
type: http
scheme: bearer
description: Pass your `pk_live_...` API key as a Bearer token.
````