API Reference

The Conduit REST API ingests events and manages pipelines. All endpoints are versioned under /v1 and return JSON. Requests and responses use UTF-8; timestamps are RFC 3339 in UTC.

Base URL and authentication

Send every request to the production host over HTTPS:

bash

https://api.conduit.dev

Authenticate with a live API key in the Authorization header using the Bearer scheme. Keys begin with ck_live_ and carry the permissions of the workspace that issued them.

bash

Authorization: Bearer ck_live_8Hx2Qm4Rt9Vn0Lb

A missing or invalid key returns 401 Unauthorized. Requests that exceed the workspace rate limit return 429 Too Many Requests with a Retry-After header.

Create an event

POST /v1/events

Ingest a single event into a pipeline. The call returns once the API has durably accepted the event for processing. Supply an idempotency_key to make retries safe: a repeated key within 24 hours returns the original result instead of creating a duplicate.

Request parameters

Field	Type	Required	Description
`pipeline_id`	string	required	Target pipeline that receives the event, for example `pl_8f3a`.
`event_type`	string	required	Dot-namespaced event name, for example `order.created`.
`payload`	object	required	Arbitrary JSON body for the event. Maximum encoded size is 256 KB.
`idempotency_key`	string	optional	Client-supplied dedup token. Repeated keys within 24h return the first result.

Response fields

Field	Type	Description
`event_id`	string	Server-assigned identifier for the stored event.
`pipeline_id`	string	Pipeline the event was routed to. Echoes the request.
`event_type`	string	Event name as submitted. Echoes the request.
`status`	string	Acceptance state. `accepted` means queued for the sink.
`received_at`	string	RFC 3339 timestamp when the API accepted the event.

Example request

The same call in three clients. Selecting a language here switches every example on the page.

bash

curl https://api.conduit.dev/v1/events \
  -H "Authorization: Bearer ck_live_8Hx2Qm4Rt9Vn0Lb" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline_id": "pl_8f3a",
    "event_type": "order.created",
    "payload": { "orderId": "ord_1042", "amount": 4999, "currency": "usd" },
    "idempotency_key": "evt-key-3f9c2a"
  }'

javascript

import { Conduit } from "@conduit/cli";

const conduit = new Conduit({ token: process.env.CONDUIT_TOKEN });

const result = await conduit.emit({
  pipelineId: "pl_8f3a",
  eventType: "order.created",
  payload: { orderId: "ord_1042", amount: 4999, currency: "usd" },
  idempotencyKey: "evt-key-3f9c2a"
});

console.log(result.eventId); // evt_5b1c9d

python

import os
from conduit import Conduit

conduit = Conduit(token=os.environ["CONDUIT_TOKEN"])

result = conduit.emit(
    pipeline_id="pl_8f3a",
    event_type="order.created",
    payload={"orderId": "ord_1042", "amount": 4999, "currency": "usd"},
    idempotency_key="evt-key-3f9c2a",
)

print(result.event_id)  # evt_5b1c9d

Example response

A 200 OK response echoes pipeline_id and event_type and adds the server-assigned fields:

json

{
  "event_id": "evt_5b1c9d",
  "pipeline_id": "pl_8f3a",
  "event_type": "order.created",
  "status": "accepted",
  "received_at": "2026-06-21T14:09:33Z"
}

Retrieve a pipeline

GET /v1/pipelines/{id}

Fetch a single pipeline by id, including its resolved name and batch settings and its current run state.

Path parameters

Field	Type	Required	Description
`id`	string	required	Pipeline identifier from the create call, for example `pl_8f3a`.

Response fields

Field	Type	Description
`id`	string	Pipeline identifier.
`name`	string	Human-readable label set in the config.
`status`	string	One of `active`, `paused`, or `draining`.
`batch_size`	int	Events buffered before a flush to the sink.
`created_at`	string	RFC 3339 creation timestamp.

Example request

bash

curl https://api.conduit.dev/v1/pipelines/pl_8f3a \
  -H "Authorization: Bearer ck_live_8Hx2Qm4Rt9Vn0Lb"

json

{
  "id": "pl_8f3a",
  "name": "orders-stream",
  "status": "active",
  "batch_size": 100,
  "created_at": "2026-06-18T09:12:04Z"
}

List events

GET /v1/events

Return events in reverse-chronological order. Results are cursor-paginated: pass the next_cursor from one response as the cursor of the next request until has_more is false.

Query parameters

Field	Type	Required	Description
`pipeline_id`	string	optional	Restrict results to one pipeline. Omit to list across the workspace.
`limit`	int	optional	Page size, 1–100. Defaults to `50`.
`cursor`	string	optional	Opaque pagination token from a prior `next_cursor`.

Response fields

Field	Type	Description
`data`	array	List of event objects, newest first.
`has_more`	boolean	`true` when more pages remain.
`next_cursor`	string	Token for the next page, or `null` on the last page.

Example request

bash

curl "https://api.conduit.dev/v1/events?pipeline_id=pl_8f3a&limit=2" \
  -H "Authorization: Bearer ck_live_8Hx2Qm4Rt9Vn0Lb"

json

{
  "data": [
    {
      "event_id": "evt_5b1c9d",
      "pipeline_id": "pl_8f3a",
      "event_type": "order.created",
      "received_at": "2026-06-21T14:09:33Z"
    }
  ],
  "has_more": true,
  "next_cursor": "ev_cursor_2a7f"
}

Delete a pipeline

DELETE /v1/pipelines/{id}

Permanently delete a pipeline. In-flight events already accepted are still flushed to the sink; no new events are accepted after deletion. This action cannot be undone.

Path parameters

Field	Type	Required	Description
`id`	string	required	Identifier of the pipeline to delete.

Response fields

Field	Type	Description
`id`	string	Identifier of the deleted pipeline.
`deleted`	boolean	Always `true` on success.

Example request

bash

curl -X DELETE https://api.conduit.dev/v1/pipelines/pl_8f3a \
  -H "Authorization: Bearer ck_live_8Hx2Qm4Rt9Vn0Lb"

json

{
  "id": "pl_8f3a",
  "deleted": true
}

Error responses

Errors use standard HTTP status codes and a JSON body with a stable error.code and a human-readable error.message. See Concepts for retry and dead-letter behavior.

json

{
  "error": {
    "code": "payload_too_large",
    "message": "payload exceeds the 256KB limit"
  }
}