API reference

Ingestion endpoints are under https://app.flowpulse.xyz/api/v1/ingest/…, on the same origin as the FlowPulse dashboard.

Relative base path: /api/v1/ingest/

Event	Method	Path
Run succeeded	`POST`	`/api/v1/ingest/run-success`
Run failed	`POST`	`/api/v1/ingest/run-failure`

Successful acceptance returns 202 with a JSON body including event_id and status: "accepted". The event is processed asynchronously.

Choosing `workflow_id` vs `workflow_slug`

You must identify the FlowPulse workflow with one of workflow_id, workflow_slug, or workflow_name (exact name).

Approach	When to use
`workflow_id`	Stable CUID from the dashboard or `GET /api/v1/workflows`. Preferred for integrations that should survive renames.
`workflow_slug`	URL-friendly slug from the workflow page (for example `lead-enrichment`). Handy for scripts and quick tests.
`workflow_name`	Exact display name match. Not recommended for automation; names can change.

POST /api/v1/ingest/run-success

Field	Type	Required	Description
`workflow_slug`	string	One of slug/id/name	Workflow slug from the workflow page.
`workflow_id`	string	One of slug/id/name	FlowPulse workflow ID.
`workflow_name`	string	One of slug/id/name	Exact workflow name (legacy).
`ended_at`	string (ISO 8601)	Yes	When the run completed.
`started_at`	string (ISO 8601)	No	When the run started.
`duration_ms`	number	No	Duration in ms. If omitted, may be derived from `started_at` and `ended_at` when both are set.
`external_execution_id`	string	No	ID from the source platform (n8n execution id, etc.).
`source_platform`	string	No	e.g. `n8n`, `make`, `zapier`
`source_workflow_id`	string	No	Workflow ID in the source platform.
`correlation_id`	string	No	For linking related runs.
`metadata`	object	No	Arbitrary JSON object for extra context.

POST /api/v1/ingest/run-failure

Same workflow identification and timing fields as run success, plus:

Field	Type	Required	Description
`error_message`	string	Yes	Human-readable failure description.
`error_type`	string	No	e.g. `RateLimitError`, `ValidationError`

HTTP	Meaning
401	Invalid or missing API key.
400	Validation failed (missing required fields, bad JSON).
404	Workflow not found. Create the workflow in FlowPulse first.
500	Server error. Retry after a delay.

Symptom	Fix
401 Unauthorized	Check `X-API-Key` or `Bearer` header and that the key was not revoked.
404 Workflow not found	Create the workflow under Workflows in the app, then use its `workflow_id` or `workflow_slug`.
400 Validation failed	Ensure `ended_at` is present and workflow identification is included; for failures, include `error_message`.