API overview

The MedFlow API lets you manage the pieces of a Workflow (diagrams and care pathways, triggers, and queries), start runs by firing a trigger, and follow run status. Every request authenticates with an API key.

Base URL

Environment	Base URL
Production	https://api.medflow.care
Staging	https://api-staging.medflow.care

All paths in this reference are relative to the base URL above. The auth headers in each example read your key from $MEDFLOW_API_KEY in your shell.

Authentication

bashCopy

curl "https://api-staging.medflow.care/v1/me" \
  -H "Authorization: Bearer $MEDFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json"

The key is scoped to a tenant and workspace and may carry scopes. See Authentication to request a key.

Versioning

Breaking changes ship under a new major prefix (/v2). Additive changes stay on /v1.

Idempotency (optional)

When you fire a trigger or deliver webhook data, send an Idempotency-Key header (or idempotencyKey in the body) so retries do not create duplicates. Reusing a key with the same body returns the original result. Reusing it with a different body returns 409.

The same key is how you trace what a request produced. Every run created from it carries the key, so GET /v1/runs?idempotencyKey=… lists the runs a single fire or delivery started. Use one key per real-world event.

Request ids (optional)

You can send an X-Request-Id on each call, or let MedFlow generate one. The same id comes back in the response header and appears in audit events, so it is worth quoting when you contact support.

Errors

jsonCopy

{
  "error": "<string>",
  "code": "<string> | null",
  "requestId": "<string>"
}

Status	Typical cause
400	Validation / missing fields
401	Auth missing or invalid
403	Authenticated but missing scope or permission
404	Unknown id for this tenant
409	Idempotency or state conflict
429	Rate limit
500	Unexpected server error

Public IDs

ID	Means
id	Diagram id, blueprint or instance (Diagrams)
runId	Pathway run. Also the id of the pathway instance for that run
sourceId	Blueprint id a run or instance was copied from
triggerId	How work starts
queryId	Find query
nodeId	Step on a pathway
automationId	Automated action on a node

Naming convention: diagrams return their own id as id. Triggers, queries, runs, and webhooks return their own id as {resource}Id (triggerId, queryId, runId, webhookId). When one resource references another it uses the referenced id name, so a trigger and a run both carry sourceId (the blueprint they came from).

Resources

Area	Base path	Docs
Search (Find)	/v1/search	Search
Queries	/v1/queries	Queries
Diagrams	/v1/diagrams	Diagrams
Triggers	/v1/triggers	Triggers
Runs	/v1/runs	Runs
Webhooks	/v1/webhooks	Webhooks
Metrics		Metrics (read API in development)
Full path list		Endpoint index
Status values		Automation status
Security		Security
Service status		status.medflow.care