API reference

The Poyesis REST API — authentication, resources, and example requests.

The Poyesis REST API lets you automate everything the dashboard and CLI can do. The base URL is:

Text
https://api.poyesis.dev/v1

Authentication#

All requests require a bearer token in the Authorization header.

Shell
curl https://api.poyesis.dev/v1/projects \
  -H "Authorization: Bearer $POYESIS_TOKEN"

Create tokens under Settings → API tokens. Tokens are scoped to a project and can be restricted to read-only access.

Trigger a run#

Shell
curl -X POST https://api.poyesis.dev/v1/runs \
  -H "Authorization: Bearer $POYESIS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "project": "api", "ref": "main" }'

A successful request returns the created run:

201 Created
{
  "id": "run_6a40514c",
  "project": "api",
  "ref": "main",
  "state": "queued",
  "created_at": "2026-06-28T22:40:11Z"
}

Core resources#

ResourceEndpointDescription
Projects/v1/projectsWorkspaces grouping repos & runs
Runs/v1/runsPipeline executions
Deploys/v1/deploysEnvironment deployments
Integrations/v1/integrationsConnected third-party services

Pagination#

List endpoints are cursor-paginated. Pass ?limit= and follow next:

Shell
curl "https://api.poyesis.dev/v1/runs?limit=20&cursor=eyJpZCI6..." \
  -H "Authorization: Bearer $POYESIS_TOKEN"

Rate limits#

The API allows 600 requests per minute per token. Exceeding it returns 429 Too Many Requests with a Retry-After header — back off and retry.

Webhooks#

Subscribe to events to receive a signed POST when something happens:

deploy.succeeded payload
{
  "event": "deploy.succeeded",
  "deploy": { "id": "dep_91f2", "env": "production" },
  "run": { "id": "run_6a40514c", "commit": "188900a" }
}

Verify the X-Poyesis-Signature header against your endpoint's signing secret before trusting a payload.