FLOWWATCH / API PORTAL / V1

Observe every automation.
Prove every outcome.

The first-party API for sending runtime signals, recording business outcomes and operating FlowWatch from your own tooling.

Send your first event ↓Browse endpoints

HTTPS JSON API API-key ingestion Tenant isolated No prompt capture by default

01 / QUICKSTART

A useful signal in
under a minute.

Use an ingestion key from Connect & settings in your FlowWatch workspace. The key is shown once; store it in your runtime’s secret manager.

Create an ingestion key

Connect & settings → API keys → Create key.

Post an execution event

Send safe operational metadata as each workflow finishes.

Let FlowWatch decide

Policies detect failures, cost drift and missing outcomes.

curl -X POST http://localhost:8000/api/v1/events \
  -H "X-API-Key: fw_your_ingestion_key" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_external_id": "lead-router",
    "workflow_name": "Lead Router",
    "platform": "n8n",
    "execution_id": "run-1042",
    "status": "success",
    "duration_ms": 842,
    "cost_usd": 0.018,
    "business_result": true
  }'

02 / ACCESS MODEL

One API. Clear
trust boundaries.

Ingestion keys

Use X-API-Key only for runtime telemetry and outcome ingestion. Each key belongs to exactly one organization.

Best for n8n, agents and bots

Session access

Use a workspace session or bearer token for workflows, incidents, budgets and configuration.

Owner, admin, operator or viewer

Privacy by default

Do not send prompts, messages, tool arguments or outputs. FlowWatch uses bounded operational metadata.

Safe metrics, IDs and status only

TELEMETRY

Workflow events

One endpoint for n8n, custom runtimes and workflow engines.

POST/api/v1/eventsIngest a workflow execution+

Send a bounded execution signal

Creates or updates a workflow, stores the execution and evaluates reliability policy. Repeating the same execution ID is idempotent.

Authentication: X-API-Key
Returns: 202 Accepted
Required: workflow_external_id, execution_id, status

{ "workflow_external_id": "lead-router", "execution_id": "run-1042", "status": "error", "duration_ms": 8450, "cost_usd": 0.18 }

GET/api/v1/eventsList recent executions+

Review execution history

Workspace-authenticated list for filtering and investigation.

GET /api/v1/events?limit=100

AGENTOPS

Agents & sessions

Capture model, tool and business signals without collecting content.

POST/api/v1/telemetry/eventsIngest an agent lifecycle event+

Track an agent’s work

Use lifecycle types such as session.completed, model.failed and business.succeeded.

Authentication: X-API-Key
Returns: 202 Accepted

{ "agent_external_id": "support-agent", "session_external_id": "session-998", "event_type": "session.completed", "duration_ms": 1200 }

GET/api/v1/agent-sessionsList agent sessions+

Investigate sessions

Retrieve workspace-scoped session data and compare it with successful peers.

GET /api/v1/agent-sessions?limit=100

OUTCOMES

Business results

Keep technical success distinct from the outcome the business needs.

POST/api/v1/outcome-contractsDefine an expected outcome+

Create a contract

Attach a measurable business goal to a workflow or agent.

Authentication: Owner or admin
Returns: 201 Created

{ "resource_kind": "workflow", "resource_id": 42, "name": "Qualified lead created", "target_success_rate": 0.95, "confirmation_window_minutes": 1440 }

POST/api/v1/outcome-contracts/{id}/records/ingestConfirm an outcome from a runtime+

Record business truth

Use an ingestion key from a CRM, payment flow or downstream service to confirm or miss a result.

{ "external_id": "lead-1042", "status": "confirmed", "value": 1200 }

INTELLIGENCE

Evidence, spend & change

Read the facts behind an operational decision.

GET/api/v1/traces/compareCompare a run with healthy peers+

Find what diverged

Pass exactly one event_id or session_id. Safe metrics are compared with successful peers.

GET /api/v1/traces/compare?event_id=1042

GET/api/v1/health-explanationExplain the health score+

Inspect score evidence

Shows failures, business misses, incidents and unhealthy resources.

GET /api/v1/health-explanation?days=30

GET/api/v1/cost-intelligenceRead spend and outcome efficiency+

Measure operating cost

Returns platform breakdown, cost per operation and budget forecasts.

GET /api/v1/cost-intelligence?days=30

GET/api/v1/optimization-advisorRank token, model and operational risk+

Find the expensive and vulnerable path

Ranks agents and workflows using measured token use, cost, failures, missed outcomes and risky tool events. Returns evidence-led optimisation suggestions.

GET /api/v1/optimization-advisor?days=30

GET/api/v1/api-balance-monitorsList safe provider credit checks+

Inspect external API runway

Returns balance state and masked endpoint hints; provider credentials and response bodies are never returned.

GET /api/v1/api-balance-monitors

OPERATIONS

Control the response

Operate incidents, workflows and cross-workspace views.

GET/api/v1/incidents/{id}/roomOpen the Incident Room+

Collect incident context

Returns changes, contracts, dependencies, delivery and recovery actions.

GET /api/v1/incidents/82/room

POST/api/v1/topology/dependenciesMap a dependency path+

Expose blast radius

Connect workflow, agent and notification resources.

{ "source_kind": "workflow", "source_id": 42, "target_kind": "agent", "target_id": 7, "relationship": "depends_on" }

GET/api/v1/command-centerRead ranked operational decisions+

Build your own control view

Groups runtime health and prioritizes decisions by risk and exposure.

GET /api/v1/command-center?days=7&group_by=platform

Observe every automation.Prove every outcome.

A useful signal inunder a minute.