Your workflows.
One observable timeline.

A database-independent liveness check. This confirms the HTTP service responds, not that PostgreSQL or ingestion is ready.

curl "$FLOWMARK_API_URL/api/health"

{"status":"ok","service":"flowmark-api"}

Response codes

Accepts one event envelope, resolves the project from the key, and acknowledges only after persistence. Server-side only: no browser CORS handler is provided here.

Keep write keys on a trusted server. Never put them in NEXT_PUBLIC_* variables, browser bundles, screenshots, or client-side requests. Reuse the same eventId when retrying the same event.

curl "$FLOWMARK_API_URL/v1/events" \
  -H "Authorization: Bearer $FLOWMARK_WRITE_KEY" \
  -H "Content-Type: application/json" \
  --data '{
  "eventId": "11111111-1111-4111-8111-111111111111",
  "event": {
    "type": "started",
    "workflow": "checkout",
    "runId": "checkout-example-001",
    "timestamp": "2026-01-01T12:00:00.000Z",
    "properties": {
      "source": "reference-example"
    },
    "correlationId": "checkout-request-123",
    "parentRunId": "browser-run-id-from-application-propagation"
  }
}'

{"accepted":true}

Response codes

Uses a separate browser credential with an exact origin allowlist. Workflow names are prefixed with browser. unless already prefixed. Browser telemetry is not trusted server evidence.

The browser sets Origin; JavaScript cannot choose it. Public keys cannot query data or use private ingestion. CORS is a browser restriction, not proof of caller identity: a non-browser client can forge Origin. The shared key quota is consumed before payload validation. Auth/origin failures and unavailable-storage responses do not include CORS headers.

// Run only from an origin configured for YOUR public browser key.
// Explicit example: this writes an event when you execute it.
await fetch("https://api.flowmark.dev/v1/browser-events", {
  method: "POST",
  headers: {
    "Content-Type": "application/json",
    Authorization: "Bearer YOUR_PUBLIC_BROWSER_KEY",
  },
  body: JSON.stringify({
  "eventId": "11111111-1111-4111-8111-111111111111",
  "event": {
    "type": "started",
    "workflow": "checkout",
    "runId": "checkout-example-001",
    "timestamp": "2026-01-01T12:00:00.000Z",
    "properties": {
      "source": "reference-example"
    },
    "correlationId": "checkout-request-123",
    "parentRunId": "browser-run-id-from-application-propagation"
  }
}),
});

{"accepted":true}

Response codes

Preflight checks whether any configured browser key allows the origin and the requested method is POST. It does not authenticate a key; the subsequent POST checks that key’s own allowlist.

curl -i -X OPTIONS "$FLOWMARK_API_URL/v1/browser-events" \
  -H "Origin: http://localhost:3004" \
  -H "Access-Control-Request-Method: POST" \
  -H "Access-Control-Request-Headers: content-type, authorization"

HTTP 204 (empty body)
Access-Control-Allow-Origin: <allowed request origin>
Access-Control-Allow-Methods: POST
Access-Control-Allow-Headers: content-type, authorization, traceparent, b3
Access-Control-Max-Age: 600
Vary: Origin
Cache-Control: no-store

Response codes

The route exports GET, POST, and OPTIONS. All current procedures are queries: use GET. POST is wired to the tRPC adapter, but there are no mutations and query-over-POST is not enabled.

The dashboard CORS origin is https://app.flowmark.dev. CORS does not authorize a read; protected procedures still require a read key. Prefer a same-origin server proxy to keep dashboard read keys out of browsers. Standard tRPC batching may return 207 for mixed outcomes.

curl -i -X OPTIONS "$FLOWMARK_API_URL/api/trpc/project.snapshot" \
  -H "Origin: https://app.flowmark.dev" \
  -H "Access-Control-Request-Method: GET"

HTTP 204 (empty body)
// Only when Origin equals FLOWMARK_DASHBOARD_ORIGIN:
Access-Control-Allow-Origin: <configured dashboard origin>
Access-Control-Allow-Methods: GET, POST, OPTIONS
Access-Control-Allow-Headers: content-type, authorization
Vary: Origin

Response codes

The typed equivalent of the HTTP health check. No input, authentication, or database access.

curl "$FLOWMARK_API_URL/api/trpc/health.check"

{"result":{"data":{"status":"ok","service":"flowmark-api"}}}

Response codes

No input. Returns the latest 100 runs, workflow summaries, volume/success/duration metrics, 30-day daily insight, slowest operations, and failure codes. Project scope comes from the read key, never a client-supplied project ID.

Success rate is a percentage across terminal runs and is null when no runs have finished. Keep the read key server-side: it grants access to project workflow data.

curl "$FLOWMARK_API_URL/api/trpc/project.snapshot" \
  -H "Authorization: Bearer $FLOWMARK_READ_KEY"

// Schema of result.data (not a literal JSON response)
{
  runs: Array<{
    id: UUID, externalId: string, workflow: string, startedAt: string,
    status: "Completed" | "Failed" | "Running",
    durationMs: number | null, step: string | null,
    correlationId: string | null, parentRunId: string | null
  }>,
  workflows: Array<{
    name: string, runs: number, successRate: number | null,
    medianDurationMs: number, p95DurationMs: number
  }>,
  metrics: {
    totalRuns: number, failedRuns: number,
    successRate: number | null, medianDurationMs: number, p95DurationMs: number
  },
  daily: Array<{
    date: string, count: number, completed: number, failed: number,
    successRate: number | null, medianDurationMs: number | null,
    p95DurationMs: number | null
  }>,
  operations: Array<{
    name: string, workflow: string, count: number, failed: number,
    medianDurationMs: number, p95DurationMs: number, totalDurationMs: number
  }>,
  failureCodes: Array<{ code: string, workflow: string, count: number }>
}

Response codes

No input. Returns the workflows portion of the authorized project snapshot, ordered by workflow name.

curl "$FLOWMARK_API_URL/api/trpc/workflow.list" \
  -H "Authorization: Bearer $FLOWMARK_READ_KEY"

// Schema of result.data
Array<{
  name: string,
  runs: number,
  successRate: number | null,
  medianDurationMs: number,
  p95DurationMs: number
}>

Response codes

Input: { id: UUID }. Use the internal runs[].id from project.snapshot, not the external runId supplied during ingestion. Events are ordered by occurrence time, then insertion time. Error and result values are recorded on their corresponding events.

An unknown run UUID, or a run belonging to a different project, returns an empty array with HTTP 200, not 404. properties contains each event's own payload; merge started/properties event patches chronologically for run context. receivedAt is when the API persisted that event.

curl --get "$FLOWMARK_API_URL/api/trpc/run.detail" \
  -H "Authorization: Bearer $FLOWMARK_READ_KEY" \
  --data-urlencode 'input={"id":"11111111-1111-4111-8111-111111111111"}'

// Schema of result.data
Array<{
  id: UUID,
  type: "started" | "step" | "properties" | "error" | "operation_started" | "operation_completed" | "operation_failed" | "progress" | "completed" | "failed",
  step: string | null, reason: string | null,
  operationId: UUID | null, operationName: string | null,
  durationMs: number | null,
  completed: number | null, total: number | null, unit: string | null,
  error: { code: string, message?: string, retryable?: boolean, handled?: boolean } | null,
  result: Record<string, JsonValue> | null,
  properties: Record<string, JsonValue> | null,
  timestamp: string, receivedAt: string, workflow: string, externalId: string,
  environment: string | null, release: string | null,
  correlationId: string | null, parentRunId: string | null
}>

Response codes

Input: { id: UUID } using the internal runs[].id from project.snapshot. Returns project-scoped parentMatches for the supplied parentRunId external ID and all other related runs sharing correlationId. It does not limit matches to the latest-100 snapshot.

Unknown or cross-project run IDs return empty arrays. Empty parentMatches means no same-project parent run is currently recorded; multiple matches are possible because external IDs are unique within a workflow. Shared correlation IDs group application-declared runs and do not prove causation or create a distributed trace.

curl --get "$FLOWMARK_API_URL/api/trpc/run.related" \
  -H "Authorization: ******" \
  --data-urlencode 'input={"id":"11111111-1111-4111-8111-111111111111"}'

// Schema of result.data
{
  parentMatches: Array<{
    id: UUID, externalId: string, workflow: string, startedAt: string,
    status: "Completed" | "Failed" | "Running",
    correlationId: string | null, parentRunId: string | null
  }>,
  related: Array<{
    id: UUID, externalId: string, workflow: string, startedAt: string,
    status: "Completed" | "Failed" | "Running",
    correlationId: string | null, parentRunId: string | null
  }>
}

Response codes

Input: { id: UUID }. Returns the current run and the last 20 finished or recorded peers of the same workflow, plus peer success rate, median duration, and p95 duration.

curl --get "$FLOWMARK_API_URL/api/trpc/run.compare" \
  -H "Authorization: Bearer $FLOWMARK_READ_KEY" \
  --data-urlencode 'input={"id":"11111111-1111-4111-8111-111111111111"}'

// Schema of result.data
{
  current: StoredRun | null,
  peers: StoredRun[],
  peerSuccessRate: number | null,
  peerMedianDurationMs: number | null,
  peerP95DurationMs: number | null
}

Response codes