API integration
The operator CLI uses the server's HTTP API. Integrations receive the same authorization, revision checks, execution policy enforcement, and retained evidence as interactive users.
For downloadable specifications, discovery, and compatibility rules, see Contracts and compatibility.
Connect and authenticate
Use HTTPS and trust the server's certificate. POST /v1/login accepts a username/password and returns a token and expiry. Authenticated requests use Authorization: Bearer TOKEN; POST /v1/logout revokes the session. Deliver credentials through your automation environment rather than committing them in scripts.
The running server exposes its generated OpenAPI document at /openapi.json. Use that document for exact schemas and response fields for the deployed platform version. The website's rendering fixtures are not an API contract.
Main endpoints
| Method and path | Purpose |
|---|---|
GET /health | Health and server version |
POST /v1/deployments | Deploy a Definition using an expected revision and idempotency key |
GET /v1/pyplines | List installed Pyplines |
GET /v1/pyplines/{environment}/{name} | Inspect an installed revision |
GET /v1/pyplines/{environment}/{name}/history | List revisions |
POST /v1/runs | Start a Run with revision, inputs, and idempotency key |
GET /v1/runs | List Runs |
GET /v1/runs/{id} | Inspect state and available execution evidence |
GET /v1/runner-pools | List runner pools (administrator) |
POST /v1/runner-pools | Create a pool with a name field (administrator) |
GET /v1/runs/{id}/history | Read Run events |
GET /v1/runs/{id}/attempts | Read execution attempts |
GET /v1/runs/{id}/logs/{step} | Read retained non-private logs |
POST /v1/runs/{id}/approve | Approve prepared work |
POST /v1/runs/{id}/retry | Retry a settled blocked step |
POST /v1/runs/{id}/skip | Skip with policy permission and a reason |
POST /v1/runs/{id}/cancel | Request cancellation |
Integrate external triggers
Pyplines has no built-in scheduler or webhook receiver. An external scheduler or incident system can authenticate, start a Run, and observe its ID. Persist the Run ID and request key before retrying an uncertain response. A new key can create new work; a polling timeout does not cancel existing work.
Decide explicitly how your integration handles awaiting_approval, blocked, uncertain, and cancelling. Do not equate request acceptance with successful completion. See Run states.
The Python distribution pyplines[client] provides the API client used by the operator CLI. Choose it from the supported tooling release. The SDK reference primarily covers authoring Actions; Action handlers are not required for API integration.