API reference

Using the API

Authentication, errors, pagination, and your first request.

The REST API is how systems outside Perstack read and drive what is running inside it. Most REST resources are available under the versioned public API; interactive checkout, portal, and OAuth flows use their dedicated session endpoints.

REST requests go to https://api.perstack.ai and normally begin /api/v1. OAuth endpoints use /api/oauth and the interactive checkout and portal flows use their documented session routes.

Authenticating

Most REST requests carry an API key as a bearer token:

curl https://api.perstack.ai/api/v1/agent-runs \
  -H "Authorization: Bearer $PERSTACK_API_KEY"

A key is scoped to the operations you granted it when it was issued, and it never exceeds what its issuer can do — see API keys. A request beyond that scope is refused the same way an agent's would be. Checkout, portal, and OAuth operations use an interactive session flow instead of a bearer key.

Errors

REST JSON errors use the following shape:

{
  "error": {
    "code": "not_found",
    "message": "Project Environment not found"
  }
}

code is stable and safe to branch on; message is written for a person reading a log and may change. REST responses also carry an x-request-id header, which is what to quote when asking about a specific failure. OAuth redirects and interactive session responses follow their flow-specific contracts.

The codes are bad_request, unauthorized, payment_required, forbidden, not_found, conflict, data_loss_required, data_migration_required, deploy_in_progress, misdirected_request, validation_failed, too_many_requests, internal_server_error, and service_unavailable.

Treat the list as open. New codes are additive, so match the ones you handle and fall back to the status code for the rest.

Pagination

List endpoints take limit and cursor. limit defaults to 20 and caps at 100. cursor is opaque: omit it for the first page, then pass back what the previous page returned.

curl "https://api.perstack.ai/api/v1/agent-runs?limit=50" \
  -H "Authorization: Bearer $PERSTACK_API_KEY"

The response carries the requested resources alongside a pagination object holding the next cursor. When there is no next cursor, you have read the last page.

Where ordering is supported, sort selects the field and order is asc or desc.

Changing things

Reads are GET. Creates are POST on the collection. Updates are PATCH on the item — there is no PUT. Deletes are DELETE on the item.

Operations that must not run twice, such as deploying a definition, require an Idempotency-Key header. Retrying with the same key and the same body replays the original outcome rather than performing the work again, which makes a network timeout safe to retry.

Where to start