Triggers API

Auth: API key. Scopes: triggers:read / triggers:write (management) and runs:write (firing).

Base path: /v1/triggers

A trigger is how work starts. It points at a blueprint diagram (sourceId) and has a type that decides how runs are created. See Triggers (concepts).

`type`	Starts a run when	Type-specific fields
`web`	You fire `POST /v1/triggers/:triggerId`	None
`search`	A query matches (optionally on a schedule)	`queryId`, optional `schedule`
`event`	A connected-system event matches	`event`

Fire a trigger

POST /v1/triggers/:triggerId

Only type: "web" triggers can be fired over HTTP. This is what your backend, a form, or a job hits when something happens on your side. Requires runs:write.

Firing a search or event trigger returns 409 (trigger_not_web).

curl -X POST "https://api-staging.medflow.care/v1/triggers/TRIGGER_ID" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "payload": {
      "patientId": "pt-12345",
      "externalRef": "order-abc"
    },
    "autoStart": true
  }'

Field	Required	Description
`payload`	No	JSON context for the run (ids, refs)
`idempotencyKey`	No	Optional if `Idempotency-Key` header is set
`autoStart`	No	Overrides the trigger default

Response 201

{
  "runId": "<uuid>",
  "sourceId": "<uuid>",
  "triggerId": "<uuid>",
  "idempotencyKey": "<string> | null",
  "automationStatus": "<AutomationStatus>",
  "createdAt": "<ISO 8601>"
}

When autoStart is false, the run starts as queued. Otherwise it moves to scheduled and then running (see Automation status). Audited as run.create.

Create a trigger

POST /v1/triggers

Every trigger shares a small set of fields. Extra options depend on type.

Shared fields

Field	Required	Description
`name`	Yes	Display name
`sourceId`	Yes	Blueprint id (Diagrams)
`type`	Yes	`web`, `search`, or `event`
`autoStart`	No	Default `true`. Start automation when a run is created
`active`	No	Default `true`. Whether the trigger is enabled

Web trigger

No extra fields. Fire it with Fire a trigger. Partner Quickstart triggers are created as web.

curl -X POST "https://api-staging.medflow.care/v1/triggers" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Partner intake",
    "sourceId": "SOURCE_ID",
    "type": "web",
    "autoStart": true,
    "active": true
  }'

Search trigger

Field	Required	Description
`queryId`	Yes	Query that selects who to start pathways for
`schedule`	No	Recurring cadence (for example nightly). Omit to run on demand only

curl -X POST "https://api-staging.medflow.care/v1/triggers" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Nightly screening cohort",
    "sourceId": "SOURCE_ID",
    "type": "search",
    "queryId": "QUERY_ID",
    "schedule": { "interval": "daily", "timezone": "America/New_York" },
    "autoStart": true,
    "active": true
  }'

Event trigger

Field	Required	Description
`event`	Yes	Event type to match (for example `order.signed`). See Webhooks and the Connections catalog

curl -X POST "https://api-staging.medflow.care/v1/triggers" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Order signed follow-up",
    "sourceId": "SOURCE_ID",
    "type": "event",
    "event": "order.signed",
    "autoStart": true,
    "active": true
  }'

Response 201 (shape depends on type, with unused type-specific fields omitted or null)

{
  "triggerId": "<uuid>",
  "name": "<string>",
  "sourceId": "<uuid>",
  "type": "web | search | event",
  "queryId": "<uuid> | null",
  "event": "<string> | null",
  "schedule": "<Schedule> | null",
  "autoStart": <boolean>,
  "active": <boolean>,
  "createdAt": "<ISO 8601>",
  "updatedAt": "<ISO 8601>"
}

List triggers

GET /v1/triggers

Query	Description
`type`	`web` / `search` / `event`
`active`	`true` / `false`
`sourceId`	Filter by blueprint
`limit` / `cursor`	Pagination

Get a trigger

GET /v1/triggers/:triggerId

Returns the trigger configuration. To start a run from a web trigger, fire it with POST.

Update a trigger

PATCH /v1/triggers/:triggerId

Partial update. You can change shared fields (name, sourceId, autoStart, active) and the type-specific fields for the trigger’s current type. Changing type is not supported. Create a new trigger instead.

Delete a trigger

DELETE /v1/triggers/:triggerId

Response 204. Existing runs are retained, but no new runs can be started from the deleted trigger.