Public API

File work into Peractor from CI, a form, Zapier, or your own backend — with an organization key.

The public API lets anything that can send an HTTP request 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 (admins only), create a key. The secret starts with prc_ and is shown once: Peractor stores only a hash, so a lost key is replaced rather than recovered. Deleting a key revokes it immediately.

A key belongs to your organization and is normally bound to a project, so requests need no ids. A key created outside a project is organization-wide, and its tasks land unbound.

Authenticate

Send the key either way on every call:

Authorization: Bearer prc_your_key
x-peractor-key: prc_your_key

Check a key, discover workflows

GET /api/v1/me is the "test the connection" call. A 200 proves the key works and shows which organization and project its tasks will land in:

curl https://peractor.com/api/v1/me \
  -H "Authorization: Bearer prc_your_key"

{ "org": { "id": "…", "name": "Acme" },
  "project": { "id": "…", "name": "web-app" },
  "key": { "name": "CI pipeline", "prefix": "prc_ab", "access": "full" } }

GET /api/v1/workflows lists the workflow ids a registered task can run — the values workflowRef accepts — in the same order the app's own pickers show them. One row carries "default": true.

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	Meaning
`title`	Required.
`description`	Context the agent reads before working.
`workflowRef`	Which workflow to run. Falls back to the key's default, then the project's. An id that does not exist is refused with `400`, and no task is created.
`priority`	Rank in your priority list, 1 being highest.
`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 }

When nothing starts, started is false, runId is absent, and reason says why: no_workflow (the project has no runnable workflow) or quota_exhausted (the monthly quota is spent — the task is still registered and waits in the backlog). The concurrency cap is not a failure: past it the run queues with started: true and starts by itself.

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 state. prUrl and previewUrl fill in once a pull request or preview exists. Ids from another organization return 404.

Activity — figures already counted

GET /api/v1/activity?from=&to= answers what the project's runs and backlog did over a window: finished, succeeded, and failed runs with a per-day series, tasks created and closed by origin, and per-member closes.

Every figure is counted by Peractor, so whatever writes your weekly summary — usually an agent — never has to tally records itself. Closed work counts tasks, not runs, so retries do not inflate it, and quiet days appear as zeroes so charts line up. Dates are ISO; omitted bounds mean the last seven days; a window spans at most 366 days.

GET /api/v1/activity/runs returns the rows behind those figures — quote the totals, name the rows. Only settled runs appear here.

Every run carries a read-only key. Inside a run, PERACTOR_API_KEY and PERACTOR_API_URL hold a token scoped to the run's own project that can call only the read endpoints. So a workflow step can ask what the project has been doing and write a report, but a prompt that went wrong cannot start work. The token dies with the run and never appears in your key list.

Scope and limits

API keys work only under /api/v1/*. They cannot call the session API or manage other keys.
Keys you create are full access. Read-only exists today only as the automatic per-run token above.
Outbound callbacks on completion are not available yet; poll the run endpoint for now.

Want a person driving Peractor from a chat window rather than a system filing work? That is Peractor in your chat apps.