API reference

Surface overview for pipedai-api. Full canonical reference lives in the API repo's API.md.

Production base URL: https://api-beta.pipedai.app. All endpoints live under /api/v1/.

Source of truth

This page summarizes the PipedAI API surface for context. The canonical reference — request bodies, response shapes, status codes, audit actions — lives in API.md on Marolence/pipedai-api. Treat that file as authoritative when integrating.

Authentication

PipedAI issues its own JWT cookies via /api/v1/auth/*. Three auth substrates:

Cookie JWT for browsers (the dashboard) — set by login / register, auto-sent on subsequent calls
pwk_ Bearer for external systems / webhooks / scripts; mint via POST /environments/:envId/api-keys with prefix: "pwk"
wkt_ Bearer for workers polling for assigned runs; issued by /workers/register in exchange for a wrk_ registration token

Common headers

Authorization: Bearer pwk_…       # external clients
Cookie: auth_token=…              # dashboard browser sessions
Origin: https://your.app          # required for credentialed CORS

Endpoint surface (high level)

Auth

POST   /api/v1/auth/register           # email + password → 201 + cookie
POST   /api/v1/auth/login              # email + password → 200 + cookie
POST   /api/v1/auth/logout             # 204, clears cookie
GET    /api/v1/auth/me                 # 200 with user, 401 otherwise

Workspaces and Environments

POST   /api/v1/workspaces
GET    /api/v1/workspaces
POST   /api/v1/workspaces/:wsId/environments
GET    /api/v1/workspaces/:wsId/environments
PATCH  /api/v1/environments/:id
DELETE /api/v1/environments/:id

Members + API keys + Audit log

GET    /api/v1/environments/:envId/members           # viewer+
POST   /api/v1/environments/:envId/members           # admin+
PATCH  /api/v1/environments/:envId/members/:userId   # admin+
DELETE /api/v1/environments/:envId/members/:userId   # admin+

GET    /api/v1/environments/:envId/api-keys          # viewer+
POST   /api/v1/environments/:envId/api-keys          # admin+ — { name, prefix }
DELETE /api/v1/environments/:envId/api-keys/:keyId   # admin+

GET    /api/v1/environments/:envId/audit-log         # admin+; ?action, ?actions, ?targetId, ?cursor

GET    /api/v1/users/lookup?email=…                  # auth required; for member-invite flow

Triggers and runs

GET    /api/v1/environments/:envId/triggers          # viewer+; ?cursor, ?limit, ?workerId
POST   /api/v1/environments/:envId/triggers          # admin+ on env
GET    /api/v1/triggers/:id
PATCH  /api/v1/triggers/:id                          # admin+ on env
DELETE /api/v1/triggers/:id                          # admin+; soft delete
POST   /api/v1/triggers/:id/rotate-mcp-token         # admin+ on env
POST   /api/v1/triggers/:id/run                      # operator+ JWT or pwk_

GET    /api/v1/triggers/:id/runs                     # viewer+; ?status, ?from, ?to, ?cursor
GET    /api/v1/environments/:envId/runs              # viewer+; cross-trigger; ?workerId, ?status, ?from, ?to

Workers

POST   /api/v1/workers/register                          # public; consumes wrk_ for wkt_
GET    /api/v1/environments/:envId/workers               # viewer+; ?status=online|offline
GET    /api/v1/workers/:id/poll                          # wkt_; returns assigned runs
POST   /api/v1/workers/:id/runs/:runId/{claim,start,heartbeat,complete}    # wkt_

Dashboard overview

GET    /api/v1/environments/:envId/dashboard/overview    # viewer+
                                                         # → onlineWorkers, todaysRuns,
                                                         # successRatePct, monthTokenSpendUsd

Error shapes

4xx and 5xx responses return JSON { error: string }. Zod validation failures include { error, details: { fieldErrors, formErrors } }. Common codes:

400  validation / missing required field
401  auth missing or invalid
403  authenticated but lacks role for the resource
404  resource not found OR no visibility (we don't 403-leak existence)
409  state-machine rejection (e.g. last-owner removal, soft-delete with active children)