Punk Docs

API Reference

Base URL in local dev: http://localhost:4100.

The API is split into:

OpenAI-compatible gateway: /v1/*.
Punk management/runtime API: /api/v1/*.
Health check: /health.
Static dashboard: /.

Authentication

If PUNK_API_KEY is not set, Punk runs in open dev mode:

Headerless protected requests are allowed.
The default tenant is used.
Requests are treated as admin.
Private web fetches are allowed for local demos.

If PUNK_API_KEY is set:

Protected /v1/ and /api/ routes require Authorization: Bearer <token>.
The bootstrap token is admin for the default tenant.
Tenant API keys created through /api/v1/keys are hashed at rest.

Identity Headers

Header	Purpose
`X-Punk-App`	Logical app id. Optional but recommended.
`X-Punk-Agent`	Agent id/name for trust and audit.
`X-Punk-Subject`	Pseudonymous user/subject; also a cache-key safety dimension.

If an API key is pinned to an app, the pinned app overrides X-Punk-App.

Response Headers

Header	Meaning
`x-punk-run-id`	Run id for trace lookup, feedback, and replay bundle export.
`x-punk-route`	Selected route such as `live`, `exact_cache`, `artifact`, or `blocked`.

These headers are exposed through CORS.

Gateway

`POST /v1/chat/completions`

OpenAI-compatible chat completions.

Minimum body:

{
  "model": "gpt-4o",
  "messages": [{ "role": "user", "content": "hello" }]
}

Behavior:

Uses live OpenAI-compatible provider when OPENAI_API_KEY is set.
Uses deterministic mock provider otherwise.
Preserves OpenAI-shaped response body.
Supports streaming through gateway clients.
Records run, traces, route explanation, cost, latency, policy, and cache/artifact decisions.

Health

`GET /health`

Returns gateway health and current provider information.

{
  "ok": true,
  "version": "0.1.0",
  "provider": "mock",
  "plasmate": false
}

API Keys

Admin required.

Method	Path	Purpose
`POST`	`/api/v1/keys`	Create a tenant API key; token returned once.
`GET`	`/api/v1/keys`	List tenant API keys.
`POST`	`/api/v1/keys/:id/revoke`	Revoke a key.

Create key body:

{
  "name": "staging observe",
  "mode": "observe",
  "appId": "support-agent",
  "admin": false
}

Modes:

observe: record what Punk would have done, but return live response and do not block.
optimize: allow caches, artifacts, and policy enforcement.

Settings

Method	Path	Purpose
`GET`	`/api/v1/settings`	List tenant settings; secrets are redacted as `[set]`.
`PUT`	`/api/v1/settings`	Update one setting; admin required.

Known settings:

Key	Value
`retention_days`	Positive number.
`redaction`	Boolean.
`webhook_url`	Public HTTP(S) URL or null.
`webhook_secret`	String or null; never echoed back.
`approval_exception_ttl_hours`	Positive number.
`canary_enabled`	Boolean.

Runs

Method	Path	Purpose
`GET`	`/api/v1/runs`	List runs. Query: `limit`, `offset`, `route`, `status`.
`GET`	`/api/v1/runs/:id`	Get run, trace events, and side effects.
`GET`	`/api/v1/runs/:id/integrity`	Verify trace integrity hash chain.
`GET`	`/api/v1/runs/:id/replay-bundle`	Export replay evidence for a run.
`POST`	`/api/v1/runs/:id/feedback`	Submit rating/correction.

Feedback body:

{
  "type": "rating",
  "rating": -1,
  "correction": "The correct classification is billing."
}

Negative feedback on artifact-served runs creates a failed live evaluation for that artifact.

Patterns

Method	Path	Purpose
`GET`	`/api/v1/patterns`	List discovered patterns.
`GET`	`/api/v1/patterns/:id`	Pattern detail with artifacts and example runs.
`POST`	`/api/v1/patterns/:id/synthesize`	Synthesize candidate artifact; admin required.
`POST`	`/api/v1/patterns/:id/ignore`	Mark pattern negative and cache that decision; admin required.

Artifacts

Method	Path	Purpose
`GET`	`/api/v1/artifacts`	List artifacts.
`GET`	`/api/v1/artifacts/:id`	Artifact detail, evaluations, and pattern.
`POST`	`/api/v1/artifacts/:id/promote`	Promote artifact; admin required.
`POST`	`/api/v1/artifacts/:id/rollback`	Retire artifact; admin required.
`POST`	`/api/v1/artifacts/:id/quarantine`	Quarantine artifact; admin required.
`POST`	`/api/v1/artifacts/:id/replay`	Re-run replay suite; admin required.

Replay body:

{
  "runIds": ["run_..."]
}

If runIds is omitted, Punk uses artifact provenance and holdout runs.

Approvals

Method	Path	Purpose
`GET`	`/api/v1/approvals`	List approvals. Query: `status`.
`POST`	`/api/v1/approvals/:id/approve`	Approve; admin required.
`POST`	`/api/v1/approvals/:id/reject`	Reject; admin required.

Decision body:

{
  "reason": "Approved for this deployment window."
}

Learning

Method	Path	Purpose
`GET`	`/api/v1/learning/report`	Last learning report and history.
`POST`	`/api/v1/learning/tick`	Run learning loop now; admin required.

Cache

Method	Path	Purpose
`GET`	`/api/v1/cache/stats`	Cache hit/miss stats.
`POST`	`/api/v1/cache/invalidate`	Invalidate cache entries; admin required.

Invalidate body:

{
  "cacheType": "som"
}

Omit cacheType to clear all cache types for the tenant.

Governance And Audit

Method	Path	Purpose
`GET`	`/api/v1/audit`	List audit events. Query: `limit`, `decision`.
`GET`	`/api/v1/agents`	List agents and trust state.
`GET`	`/api/v1/policies`	List loaded policies.

Jobs

Method	Path	Purpose
`GET`	`/api/v1/jobs`	List jobs and stats. Query: `status`, `limit`.

Semantic Web

Method	Path	Purpose
`GET`	`/api/v1/web/snapshots`	List stored SOM snapshots.
`POST`	`/api/v1/web/fetch`	Fetch a URL and compile/retrieve SOM.

Fetch body:

{
  "url": "https://example.com",
  "bypassCache": false
}

Response includes:

som
source: plasmate, builtin, or cache
cached
htmlBytes
somBytes
tokensSavedEstimate
diff when a previous snapshot exists
context: compact prompt-ready rendering

SDK Trace And Tool Cache

Method	Path	Purpose
`POST`	`/api/v1/trace`	Append an SDK trace event to a run.
`POST`	`/api/v1/tool-cache/check`	Check read-only tool-result cache.
`POST`	`/api/v1/tool-cache/store`	Store read-only tool result.

Most users should call these through @punk/sdk instead of raw HTTP.

Errors

Errors are JSON objects with an error key. Provider-compatible chat validation errors use OpenAI-style error objects.

Common statuses:

400: invalid request body or unsupported setting.
401: missing or invalid bearer token.
403: policy block, private URL blocked, or admin key required.
404: tenant-scoped record not found.
429: rate limit exceeded; retry-after header included.
502: upstream web fetch failure.

//DOCS API