Skip to content
Echopoint Echopoint Docs

API reference

The Echopoint API is a REST API with server-sent events for live streams. The OpenAPI contract defines 91 operations; this page covers the surfaces most users automate. A fully generated, per-operation reference built from the contract is coming — until then, treat this overview plus the CLI as the practical interface.

Base URL

Section titled “Base URL”
https://api.echopoint.dev

The OpenAPI spec omits a servers block, so the base URL is stated here explicitly: all paths below are relative to https://api.echopoint.dev.

Authentication

Section titled “Authentication”
HeaderUsed by
Authorization: Bearer <Clerk JWT>App sessions (the browser app)
X-Api-Key: <org key>Automation — CI, scripts, integrations

Most routes also require the X-Organization-Id header to scope the request to your organization. Create keys under API Keys in the app — see API keys & permissions.

One deliberate exception: the webhook capture endpoint /webhook/{id} is unauthenticated, so any external system can deliver events to it.

Resource groups

Section titled “Resource groups”

The spec is organized into 11 tags:

TagKey endpoints
AuthSession endpoints used by the app sign-in
Webhook/webhooks CRUD · /webhook/{id} unauthenticated capture (GET/POST/PUT/PATCH/DELETE) · /webhooks/{id}/stream (SSE) · /webhooks/{id}/requests/search
AnalyticsWebhook traffic analytics — request volumes over time, method breakdown
Flows/flows CRUD · /flows/search · /flows/{id}/launch · /flows/{id}/publish · /flows/{id}/versions and /{vid}/restore · /flows/{id}/environments · /flows/{id}/export · /flows/{flowId}/executions/{executionId} with /stream (SSE) and /nodes
Collections/collections · /collections/import/openapi · OpenAPI-sync endpoints
ResourcesSupporting resources referenced by flows and collections
Administration/api-keys · GET /permissions (the scope catalog)
ExtractorsNode output extractors — jsonPath, xmlPath, statusCode, header, body
AssertionsNode assertions — the 14 comparison operators
SpecialNodesNon-request node types: Delay and Module nodes
RunnerRunner protocol — /runners, /runner/jobs/next, heartbeat

Conventions

Section titled “Conventions”
  • SSE wire format — streams (/webhooks/{id}/stream, execution /stream) emit data:-prefixed flat JSON events. There is no event: field; dispatch on the payload itself.
  • Pagination — list endpoints cap page size at 100.
  • Idempotency — flow launch accepts an Idempotency-Key header, so a retried pipeline does not start a duplicate execution.

Examples

Section titled “Examples”

Create a webhook endpoint:

Terminal window
curl -X POST https://api.echopoint.dev/webhooks \
  -H "X-Api-Key: $ECHOPOINT_API_KEY" \
  -H "X-Organization-Id: $ECHOPOINT_ORGANIZATION_ID" \
  -H "Content-Type: application/json" \
  -d '{"name": "payment-events"}'

Anything can then deliver to the capture URL — no auth, any of GET/POST/PUT/PATCH/DELETE, answered with a JSON receipt (message, request_id, received_at):

Terminal window
curl -X POST https://api.echopoint.dev/webhook/wh_9f2k81 \
  -H "Content-Type: application/json" \
  -d '{"event": "payment_intent.succeeded", "amount": 4200}'

List flows with an API key:

Terminal window
curl https://api.echopoint.dev/flows \
  -H "X-Api-Key: $ECHOPOINT_API_KEY" \
  -H "X-Organization-Id: $ECHOPOINT_ORGANIZATION_ID"

Launch a flow, idempotently:

Terminal window
curl -X POST https://api.echopoint.dev/flows/$FLOW_ID/launch \
  -H "X-Api-Key: $ECHOPOINT_API_KEY" \
  -H "X-Organization-Id: $ECHOPOINT_ORGANIZATION_ID" \
  -H "Idempotency-Key: deploy-2026-06-09-01"

Launches can also pick an environment key and pin a published version — the CLI and GitHub Action expose both as flags and are the recommended way to launch from CI.

Next steps

Section titled “Next steps”