Public API

The public API lets anything that can send an HTTP request — CI, a support form, Zapier, n8n, your own backend — file work into Peractor and have it run immediately. No extension, no browser session; just an organization API key.

Create a key

In Settings → API keys (editor or dashboard; admins only), create a key. The secret — it starts with prc_ — is shown once: Peractor stores only a hash, so a lost key is replaced, not recovered. Deleting a key revokes it immediately. A key belongs to your organization and is bound to a project, so requests need no ids.

Authenticate

Send the key either way on every call:

Authorization: Bearer prc_your_key
x-peractor-key: prc_your_key

Register a task and run it

POST /api/v1/tasks creates a task in the key's project and starts a run from the workflow's first phase. Only title is required:

curl -X POST https://peractor.com/api/v1/tasks \
  -H "Authorization: Bearer prc_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix the login bug",
    "description": "Users cannot sign in after the last deploy",
    "labels": ["bug"],
    "url": "https://example.com/ticket/42"
  }'

Field
`title`	Required. The task title.
`description`	Context the agent reads before working.
`workflowRef`	Workflow to run. Falls back to the key's default, then the project's default.
`priority`	Rank in your priority list (1 = highest).
`labels`	Labels, visible on the task and usable by routing.
`url`	A backlink shown on the task.

The response is 202:

{ "taskId": "…", "runId": "…", "status": "backlog", "started": true }

started is false only when the project has no runnable workflow. Plan limits apply exactly as everywhere else: past the concurrency cap the run queues and starts by itself; with the monthly quota spent, the task is still registered — it just waits in the backlog.

Poll a run

curl https://peractor.com/api/v1/runs/<runId> \
  -H "Authorization: Bearer prc_your_key"

{ "runId": "…", "taskId": "…", "status": "running", "phase": "implement",
  "title": "Fix the login bug", "prUrl": "https://github.com/…/pull/12",
  "previewUrl": null, "createdAt": "2026-07-25T10:12:00.000Z" }

status is the run lifecycle (see the states); prUrl and previewUrl fill in once a pull request or preview exists. Ids from another organization return 404.

Scope and limits

API keys work only under /api/v1/* — they can't call the session API or manage other keys.
Outbound callbacks/webhooks on completion and scoped (read-only) keys aren't available yet; poll the run endpoint for now.