HTTP API

Overview

This page is a narrative reference (human-readable, grouped by topic). The closest thing to a universal standard for HTTP APIs is OpenAPI (formerly Swagger): a YAML or JSON description of paths, parameters, request bodies, responses, and security schemes. Tools generate interactive explorers, client stubs, and contract tests from it. We do not publish an OpenAPI document yet; this HTML doc is the source of truth until we add one.

For long pages, a table of contents with in-page anchors (like the sidebar here) is the usual pattern—same idea as MDN, Stripe, or GitHub’s REST docs.

Route anchors: each HTTP route has a stable fragment #route-{METHOD}-v1-… (see the management routes table and ingest sections below). The JavaScript SDK reference links those HTTP: lines here when you regenerate it with npm run docs:sdk.

Base URL

On this deployment, the HTTP API lives at https://www.batchpipe.com. Paths below are rooted at that origin (set BASE_URL in the server environment so it matches what you use in clients).

Versioning (/v1)

All documented paths use the /v1/ prefix. That is a common convention for public HTTP APIs: it namespaces the contract so you can ship /v2/ later without colliding with marketing pages or legacy paths. It is not strictly required for a private service, but it keeps ingest, health, and management under one clear API surface.

Management API

These routes return JSON and use the same active workspace API key as ingestion: Authorization: Bearer … on every request. They reuse the same validation rules as the dashboard (Zod schemas), but unlike HTML form posts they never use cookies or redirects.

Security: a key that can create pipes, destinations, and sibling API keys is much more powerful than ingest-only. Treat it like a root credential for that workspace, rotate on leak, and prefer separate keys per environment when you can.

Website routes vs API: the dashboard uses session auth and POST to paths like /pipes/create. Management endpoints below are different URLs and verbs (REST-style) but call the same underlying services.

Routes

Each row is a deep link: fragment #route-{METHOD}-v1-… — uppercase HTTP verb, path with / turned into -, and :pipe_id style parameters as pipe_id (no colon). Example: GET /v1/pipes/:pipe_id → #route-GET-v1-pipes-pipe_id. Click a path to jump here; copy from the address bar to share.

Validation errors

Failed body validation returns 400 with error: "validation_error", a message, and an errors object keyed by dot-joined Zod paths (values are human-readable strings). Full examples, redaction rules, Postgres config, and automation guidance: Management API — contract & automation. Machine-readable bundle: OpenAPI YAML.

GET /v1/health

Liveness-style check. No authentication.

Response 200

{
  "status": "ok",
  "timestamp": "2026-04-12T12:00:00.000Z"
}

POST /v1/ingest/:pipe_id

Send one or more JSON records into an active pipe. Replace :pipe_id with the pipe’s UUID (primary key), shown in the dashboard.

Headers

• Content-Type: application/json (required)
• Authorization: Bearer <api_key> when the pipe requires an API key (default)
• Origin for browser CORS: required for CORS-only pipes and recommended for cross-origin API-key ingest when the pipe uses origin checks or open CORS reflection

Authentication

Request body

• Either a single JSON object, or a JSON array of objects.
• Primitives, arrays of non-objects, or empty arrays are rejected.
• Each object is one record. The server may add fields when pipe enrichment is enabled (ingestion timestamp and/or client IP using configured field names).

Limits

If the pipe has a pipe_limit row, the number of records in a single request cannot exceed pl_ingest_max_records_per_request. Otherwise the server returns 413 with error batch_too_large.

Success 202 Accepted

Records are accepted into the buffer (NATS JetStream). Delivery to your destinations happens asynchronously.

{
  "accepted": true,
  "pipe_id": "…uuid…",
  "pipe_name": "my_pipe",
  "records_count": 1,
  "request_id": "…uuid…",
  "message": "Records accepted for processing"
}

Example (curl)

curl -X POST "https://YOUR_HOST/v1/ingest/PIPE_UUID" \
  -H "Authorization: Bearer bp_v1_…" \
  -H "Content-Type: application/json" \
  -d '{"event":"signup","user_id":"123"}'

GET /v1/ingest/:pipe_id

Does not ingest data. Returns JSON explaining that ingestion requires POST with a JSON body (useful when someone opens the URL in a browser).

Statuses: 200 (hint JSON), 400 invalid UUID, 404 unknown or inactive pipe, 500 server error.

OPTIONS /v1/ingest/:pipe_id

CORS preflight. The Origin header must be present. When any browser origin is enabled, a standard http(s) origin succeeds without an allowlist entry; otherwise the origin must match an allowed origin for the pipe. On success the response has no body (204) and echoes Origin in Access-Control-Allow-Origin when allowed. Allowed Access-Control-Allow-Headers include Content-Type and, when the pipe requires an API key, Authorization.

If the origin is missing or not allowed: 400 or 403 with an empty body.

Ingestion API errors (JSON)

Ingest responses use error (machine-readable code) and message (human-readable). Some responses include extra fields as noted.

Related

Domain vocabulary (pipe, record, API key, CORS) is in the glossary. The JavaScript SDK at https://www.batchpipe.com/sdk/batchpipe-sdk.mjs wraps these HTTP endpoints.