Agent API

Bearer PAT for MCP, epure-cli, and automation — agent shortcuts plus full /api/v1 when scopes allow.

A PAT (epure_pat_…) authorizes /api/v1/* subject to token scopes and workspace RBAC. /api/v1/agent/* adds shortcut routes (queue, context). Human UI uses session cookies; ingest uses the DSN.

Setup (MCP config, CLI install, env vars): MCP and epure-cli.

OpenAPI (repo): agent.openapi.yaml

How do I authenticate?

Create a personal access token in the dashboard: Settings → Agent tokens (/settings/agent). Admin or Owner required.

Authorization: Bearer epure_pat_…

Scope	Allows
`read:agent`	Required — all GET `/api/v1/*`
`write:triage`	Issue/alert mutations (resolve, snooze, merge, bulk, …)
`write:admin`	Projects, DSN, webhooks, alert rules, members, agent tokens

Rate limits (per instance): about 120 reads and 20 writes per minute per client IP and token prefix.

Not a DSN

PATs never work on /envelope/ or /store/. DSN keys never work as Bearer tokens on /api/v1/*.

Create a token (session)

Create agent token

command

curl -sS -b cookies.txt -X POST \
"http://localhost:8080/api/v1/agent-tokens" \
-H "Content-Type: application/json" \
-d '{"label":"automation","scopes":["read:agent","write:triage","write:admin"]}'

Expected

HTTP/1.1 201 Created

{ "token": { "id": "…", "token": "epure_pat_…", "token_prefix": "…", "scopes": ["read:agent","write:triage","write:admin"] } }

Copy token immediately. List: GET /api/v1/agent-tokens. Revoke: POST /api/v1/agent-tokens/{id}/revoke.

Agent shortcut routes

Base: {EPURE_PUBLIC_URL}/api/v1/agent

Method	Path	Job
`GET`	`/whoami`	Token identity and scopes
`GET`	`/queue`	Prioritized issues (`project_id`, `environment`, `q`, `window`, `limit`)
`GET`	`/issues/{id}`	Issue summary
`GET`	`/issues/{id}/context`	Fix-ready JSON or Markdown (`format=markdown`, optional `event`)
`PATCH`	`/issues/{id}`	Triage — needs `write:triage`
`POST`	`/issues/{id}/snooze`	Snooze — needs `write:triage`
`GET`	`/alerts`	Alert rows (`view`, `project_id`, `limit`)

Other dashboard routes (issues list, projects, webhooks, …) use the same Bearer token on /api/v1/… paths — see OpenAPI description or MCP resource epure://api/catalog.

Example: whoami

Agent whoami

Replace TOKEN with your epure_pat_ secret.

command

curl -sS \
"http://localhost:8080/api/v1/agent/whoami" \
-H "Authorization: Bearer TOKEN"

Example: fix context as Markdown

curl -sS \
  "http://localhost:8080/api/v1/agent/issues/ISSUE_UUID/context?format=markdown" \
  -H "Authorization: Bearer TOKEN"

Same sanitized shape as the dashboard ⌘⇧C export: Issues.

Errors

Status	Meaning
401	Missing or revoked token
403	Missing scope or RBAC denied
429	Rate limit

Authentication · Errors

FAQ

How do I wire MCP or epure-cli?

See MCP and epure-cli for stdio MCP config, build steps, and CLI commands.

Can Members create tokens?

No. Agent token CRUD requires Admin or Owner: Settings.

Should I put a PAT in my app server?

No. PATs are for operators and agents. Application ingest uses the DSN only.