Skip to content
Documentation

Quickstart

The fastest way to integrate MedFlow is a web trigger: a trigger you fire directly over HTTP. Your system POSTs a payload to the trigger’s own URL with your API key, MedFlow starts a care pathway run, and you poll that run until it finishes.

This guide covers web triggers end to end: request access, fire the trigger, poll the run, and cancel it if you need to. If you instead need MedFlow to react to events from an external system, use an event trigger, which can receive those events by webhook.

Prerequisites

Section titled “Prerequisites”
  • A MedFlow tenant and workspace.
  • An API key and a triggerId for a web trigger (type: "web"). Request access with what you want to build; for this Quickstart, ask for a web trigger.

See Authentication for keys and scopes, and Triggers for the other ways a run can start.

Export your API key once in your shell. The examples show TRIGGER_ID and RUN_ID as placeholders. Enter your own under Sample values in the sidebar and they fill in automatically. Use the Environment switcher there to point at staging or production.

bash
export MEDFLOW_API_KEY='your-api-key'

Confirm the key is valid and resolves to the tenant and workspace you expect with GET /v1/me.

1. Fire the web trigger

Section titled “1. Fire the web trigger”

Each web trigger (type: "web") has its own URL. POST your payload to it, just as you would call any HTTP endpoint. MedFlow copies the trigger’s blueprint pathway into a new run and, unless you say otherwise, starts it.

POST /v1/triggers/:triggerId

bash
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
  }'
FieldRequiredDescription
payloadNoJSON context for the run, such as ids and references
idempotencyKeyNoSame as the Idempotency-Key header (see Idempotency)
autoStartNoWhether to start automation immediately. Defaults to the trigger’s own setting

The trigger must have type: "web". Firing a search or event trigger returns 409.

Response 201 returns the created run. Fields:

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

Keep the runId to check status. sourceId is the blueprint the run was copied from, and automationStatus starts at queued, or scheduled once autoStart kicks in. See Automation status.

2. Poll the run

Section titled “2. Poll the run”
bash
curl "https://api-staging.medflow.care/v1/runs/RUN_ID" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY"

Poll until automationStatus is terminal: completed, errored, canceled, or stopped. For polling cadence and the per-trigger aggregate view, see Monitoring runs.

Idempotency

Section titled “Idempotency”

To fire the same trigger safely on retries, send an idempotency key, either as the Idempotency-Key header or an idempotencyKey field in the body (the header wins if you set both). Reusing a key with the same body returns the original run. Reusing it with a different body returns 409. Use one key per real-world event so a retry never starts a duplicate run.

3. Cancel (optional)

Section titled “3. Cancel (optional)”
bash
curl -X POST "https://api-staging.medflow.care/v1/runs/RUN_ID/cancel" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY"

Next steps

Section titled “Next steps”