Zipline - API Reference

Authentication

All API requests require a bearer token passed in the Authorization header. Tokens are scoped to a workspace and can be restricted to specific resources or operations.

Generate a token from Settings → API tokens in the Zipline dashboard, or via the Create token endpoint.

Request header

Authorization: Bearer zpl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

curl example

curl https://api.zipline.run/v2/pipelines \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Token format: zpl_live_ prefix for production, zpl_test_ for sandbox. Test tokens hit a sandboxed environment and never touch real connectors.

Overview

Errors

Zipline uses conventional HTTP status codes. Error responses always include a JSON body with code, message, and an optional details array.

Error response shape

{
  "error": {
    "code":    "pipeline_not_found",
    "message": "No pipeline with id 'abc123' exists in this workspace.",
    "details": []
  }
}

Status	Code	Meaning
`400`	invalid_request	Missing or malformed parameters
`401`	unauthorized	Missing or invalid API token
`403`	forbidden	Token lacks permission for this resource
`404`	not_found	Resource does not exist
`409`	conflict	Resource already exists or state conflict
`422`	unprocessable	Valid JSON but failed business validation
`429`	rate_limited	Too many requests - check `Retry-After` header
`500`	internal_error	Something went wrong on our end

Overview

Rate limits

Limits are per token, per minute. Rate limit headers are included on every response.

Endpoint class	Limit	Headers
Read (GET)	120 req/min	X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset
Write (POST/PUT/DELETE)	30 req/min	Same + Retry-After on 429
SSE streams	10 concurrent	-

Overview

Official SDKs

Use an SDK to skip manual HTTP and get typed responses, automatic retries, and pagination helpers.

Full parity with the REST API. Uses generics for typed response parsing.

go get github.com/zipline/zipline-go

TypeScript

Works in Node.js and Deno. Tree-shakeable, zero runtime dependencies.

npm install @zipline/sdk

Python

Async-first with httpx. Includes Pydantic models for all response types.

pip install zipline-sdk

Pipelines

GET /v2/pipelines List all pipelines

Returns a paginated list of all pipelines in the workspace, ordered by creation time (newest first).

Query parameters

Name	Type	Required	Description
limit	integer	optional	Max results per page. Default 20, max 100.
cursor	string	optional	Pagination cursor from previous response's `next_cursor`.
status	string	optional	Filter by status: `running \| paused \| errored \| all`

curl

curl https://api.zipline.run/v2/pipelines?limit=10 \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Response - 200 OK

json

{
  "data": [
    {
      "id":         "pip_abc123",
      "name":       "orders-to-kafka",
      "status":     "running",
      "lag_ms":     420,
      "events_s":   18420,
      "created_at": "2026-04-01T12:00:00Z"
    }
  ],
  "next_cursor": "eyJpZCI6...",
  "total": 3
}

GET /v2/pipelines/{id} Get pipeline

Returns full details for a single pipeline including connector status, current lag, and health metrics.

Path parameters

Name	Type	Required	Description
id	string	required	Pipeline ID (e.g. `pip_abc123`)

curl

curl https://api.zipline.run/v2/pipelines/pip_abc123 \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Response - 200 OK

json

{
  "id":         "pip_abc123",
  "name":       "orders-to-kafka",
  "status":     "running",
  "lag_ms":     420,
  "events_s":   18420,
  "error_rate": 0.0,
  "connectors": [
    { "name": "orders-db",  "type": "source/postgres", "status": "ok" },
    { "name": "kafka-out", "type": "sink/kafka",     "status": "ok" }
  ],
  "created_at": "2026-04-01T12:00:00Z",
  "updated_at": "2026-04-17T09:31:00Z"
}

POST /v2/pipelines Create pipeline

Creates and immediately deploys a new pipeline. On first deploy, Zipline performs an initial snapshot before switching to streaming mode. Returns the pipeline object once streaming is active.

Request body

Field	Type	Required	Description
name	string	required	Human-readable pipeline name. Must be unique within the workspace.
config	string	required	Base64-encoded `zipline.yaml` config file.
env	object	optional	Key-value environment variables injected at runtime (for secrets). Values are encrypted at rest.
min_workers	integer	optional	Minimum worker count. Default: 2.
max_workers	integer	optional	Maximum worker count for autoscaling. Default: 16.

curl

curl -X POST https://api.zipline.run/v2/pipelines \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":   "orders-to-kafka",
    "config": "'"$(base64 zipline.yaml)"'",
    "env": {
      "POSTGRES_DSN":  "'"$POSTGRES_DSN"'",
      "KAFKA_BROKERS": "'"$KAFKA_BROKERS"'"
    },
    "min_workers": 4,
    "max_workers": 16
  }'

Response - 201 Created

json

{
  "id":     "pip_xyz789",
  "name":   "orders-to-kafka",
  "status": "snapshotting",
  "created_at": "2026-04-20T10:00:00Z"
}

PUT /v2/pipelines/{id} Update pipeline

Updates the pipeline config and performs a rolling restart with zero downtime. Only changed connectors are restarted. Partial updates are supported - omit fields to keep their current values.

Request body

Field	Type	Required	Description
config	string	optional	Updated base64-encoded config. Only changed connectors are restarted.
env	object	optional	Updated environment variables. Merged with existing; set a key to `null` to remove it.
min_workers	integer	optional	New minimum worker count.
max_workers	integer	optional	New maximum worker count.

curl

curl -X PUT https://api.zipline.run/v2/pipelines/pip_abc123 \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "max_workers": 32 }'

POST /v2/pipelines/{id}/pause Pause pipeline

Suspends the pipeline without losing the replication position. Useful for maintenance windows. The pipeline can be resumed from exactly where it stopped.

curl

curl -X POST https://api.zipline.run/v2/pipelines/pip_abc123/pause \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Response - 200 OK

json

{ "id": "pip_abc123", "status": "paused" }

POST /v2/pipelines/{id}/resume Resume pipeline

Resumes a paused pipeline from its last committed position. No events are lost during the pause window - Zipline replays buffered WAL entries automatically.

curl

curl -X POST https://api.zipline.run/v2/pipelines/pip_abc123/resume \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

POST /v2/pipelines/{id}/replay Replay events

Re-emits historical events from a given point in time or LSN to one or more sinks. The current live stream is not interrupted - replay runs as a parallel ephemeral stream.

Request body

Field	Type	Required	Description
from_ts	string (ISO 8601)	optional	Replay from this timestamp. Mutually exclusive with `from_lsn`.
from_lsn	string	optional	Replay from this WAL LSN (e.g. `0/1A2B3C4D`). Mutually exclusive with `from_ts`.
sink	string	optional	Connector name to replay to. Defaults to all sinks in the pipeline.
tables	string[]	optional	Limit replay to specific tables (e.g. `["orders.line_items"]`).

curl

curl -X POST https://api.zipline.run/v2/pipelines/pip_abc123/replay \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "from_ts": "2026-04-01T00:00:00Z",
    "tables": ["orders.line_items"]
  }'

Response - 202 Accepted

json

{
  "replay_id": "rpl_def456",
  "status":    "running",
  "from_ts":   "2026-04-01T00:00:00Z",
  "estimated_events": 4200000
}

DELETE /v2/pipelines/{id} Delete pipeline

Stops the pipeline and permanently deletes it, including its replication slot and publication on the source database. This action is irreversible.

Query parameters

Name	Type	Required	Description
confirm	string	required	Must equal the pipeline `name` to prevent accidental deletion.

curl

curl -X DELETE \
  "https://api.zipline.run/v2/pipelines/pip_abc123?confirm=orders-to-kafka" \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Response - 204 No Content

Connectors

GET /v2/pipelines/{id}/connectors List connectors

Returns all source and sink connectors attached to a pipeline with their current status and per-connector metrics.

curl

curl https://api.zipline.run/v2/pipelines/pip_abc123/connectors \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Response - 200 OK

json

{
  "data": [
    {
      "name":      "orders-db",
      "type":      "source/postgres",
      "status":    "ok",
      "lag_ms":    420,
      "events_s":  18420,
      "lsn":       "0/1A2B3C4D"
    },
    {
      "name":      "kafka-out",
      "type":      "sink/kafka",
      "status":    "ok",
      "events_s":  18418,
      "error_rate": 0.0
    }
  ]
}

GET /v2/pipelines/{id}/connectors/{name} Get connector

Returns details and current runtime state for a single connector by name.

curl

curl https://api.zipline.run/v2/pipelines/pip_abc123/connectors/orders-db \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

GET /v2/pipelines/{id}/connectors/{name}/metrics Connector metrics

Returns time-series metrics for a connector: lag, throughput, error rate, and write latency. Data is available at 1-minute resolution for the last 30 days.

Query parameters

Name	Type	Required	Description
from	string (ISO 8601)	optional	Start of time window. Default: 1 hour ago.
to	string (ISO 8601)	optional	End of time window. Default: now.
resolution	string	optional	`1m \| 5m \| 1h`. Default: `1m`.

curl

curl "https://api.zipline.run/v2/pipelines/pip_abc123/connectors/orders-db/metrics?resolution=5m" \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Events

GET /v2/pipelines/{id}/events List recent events

Returns the most recent events processed by a pipeline. Useful for debugging and auditing. Events are retained for 7 days.

Query parameters

Name	Type	Required	Description
limit	integer	optional	Max events to return. Default 50, max 500.
table	string	optional	Filter by table (e.g. `orders.line_items`).
op	string	optional	Filter by operation: `insert \| update \| delete`

curl

curl "https://api.zipline.run/v2/pipelines/pip_abc123/events?table=orders.line_items&op=insert" \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

GET /v2/pipelines/{id}/events/stream Stream events (SSE)

Opens a Server-Sent Events stream and pushes events in real time as they are processed. The connection stays open until the client closes it. Ideal for live dashboards and debugging.

curl - live stream

curl -N https://api.zipline.run/v2/pipelines/pip_abc123/events/stream \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN" \
  -H "Accept: text/event-stream"

data: {"op":"insert","table":"orders.line_items","lsn":"0/1A2B3C50","ts_ms":1713456789123,"after":{"id":1001,"qty":3}}
data: {"op":"update","table":"orders.orders","lsn":"0/1A2B3C51","ts_ms":1713456789456,"before":{"status":"pending"},"after":{"status":"shipped"}}

API Tokens

POST /v2/tokens Create token

Creates a new API token. The token value is only returned once - store it securely. Tokens can be scoped to specific pipelines and operations.

Request body

Field	Type	Required	Description
name	string	required	Human-readable label (e.g. "CI deploy token").
scopes	string[]	optional	Permission scopes: `pipelines:read \| pipelines:write \| metrics:read`. Default: all.
expires_at	string (ISO 8601)	optional	Token expiry. Omit for non-expiring tokens.
pipeline_ids	string[]	optional	Restrict token to specific pipeline IDs. Omit to allow all pipelines.

curl

curl -X POST https://api.zipline.run/v2/tokens \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name":       "CI deploy",
    "scopes":     ["pipelines:write"],
    "expires_at": "2027-01-01T00:00:00Z"
  }'

Response - 201 Created

json

{
  "id":         "tok_ghi012",
  "name":       "CI deploy",
  "token":      "zpl_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxx",
  "scopes":     ["pipelines:write"],
  "expires_at": "2027-01-01T00:00:00Z",
  "created_at": "2026-04-20T10:00:00Z"
}

DELETE /v2/tokens/{id} Revoke token

Immediately revokes an API token. Any in-flight requests using this token will be rejected. This action is irreversible.

curl

curl -X DELETE https://api.zipline.run/v2/tokens/tok_ghi012 \
  -H "Authorization: Bearer $ZIPLINE_API_TOKEN"

Response - 204 No Content

Start building

Install the SDK and ship your first integration in minutes.

Read the docs Talk to us

Platform

Evaluate

Move data

Power applications

Build

Reference

Follow

API Reference

Authentication

Start building