//DOCS API

API Reference

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

The API is split into:

• OpenAI-compatible gateway: /v1/chat/completions.
• Anthropic-compatible gateway: /v1/messages.
• Anthropic-compatible token counting: /v1/messages/count_tokens.
• Chorus governed intelligence route: model: "punk/chorus" on supported gateway wires.
• Punk management/runtime API: /api/v1/*.
• Health check: /health.
• Static dashboard and docs: /, /docs.

Authentication

If PUNK_API_KEY is not set and login mode has not been activated by a user account or PUNK_REQUIRE_LOGIN=true, 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.

Dashboard login sessions can also authenticate /api/v1/* through the HttpOnly punk_session cookie. Gateway traffic under /v1/* stays API-key oriented. See Configuration for open dev, protected, and login mode details.

Identity Headers

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

Response Headers

These headers are exposed through CORS.

Gateway

POST /v1/chat/completions

OpenAI-style chat completions wire format.

Minimum body:

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

Behavior:

• Uses live OpenAI backend when OPENAI_API_KEY is set for OpenAI/default model ids.
• Uses OpenRouter, DeepSeek, or Moonshot/Kimi backends for their model id families when configured.
• Uses deterministic mock provider when no matching live provider is configured.
• Preserves OpenAI-shaped response body.
• Supports streaming through gateway clients.
• Records run, traces, route explanation, cost, latency, policy, and cache/artifact decisions.
• Set model: "punk/chorus" to activate Chorus while preserving the OpenAI-shaped response body.

POST /v1/messages

Anthropic-compatible Messages endpoint.

Minimum body:

{
  "model": "claude-3-5-sonnet-latest",
  "max_tokens": 256,
  "messages": [{ "role": "user", "content": "hello" }]
}

Behavior:

• Uses live Anthropic backend when ANTHROPIC_API_KEY is set for claude-* models.
• Uses the configured provider registry for Chorus final answers, including Anthropic, OpenAI, OpenRouter, DeepSeek, and Moonshot/Kimi when their keys are present.
• Uses deterministic mock provider when no matching live provider is configured.
• Requires model, non-empty messages, and positive max_tokens.
• Returns Anthropic-shaped responses and validation errors.
• Supports Anthropic streaming events, including structured tool_use blocks and input_json_delta chunks when the upstream provider emits them.
• Records the same runs, traces, route explanations, policy, cache, artifact, and cost data as the OpenAI-compatible gateway.
• Set model: "punk/chorus" to activate Chorus while preserving the Anthropic-shaped response body.

POST /v1/messages/count_tokens

Anthropic-compatible token count endpoint. This is useful for Anthropic SDKs and Claude Code clients that preflight prompt size before sending a message request.

Minimum body:

{
  "model": "claude-3-5-sonnet-latest",
  "messages": [{ "role": "user", "content": "hello" }]
}

Behavior:

• Accepts the same Anthropic-shaped system, messages, tools, tool_choice, and structured content blocks Punk understands for /v1/messages.
• Returns { "input_tokens": number }.
• Does not create a run, write trace events, charge usage, or route to a live provider.
• Applies the same /v1/* auth boundary as the gateway.

Chorus: model: "punk/chorus"

Chorus is Punk's governed intelligence route for harder work that benefits from routing, evidence, verification, cost controls, and receipts.

It is selected by model id, not by a separate endpoint:

The route records Chorus-specific trace events and receipts:

Retrieve receipts through /api/v1/receipts/:runId, /api/v1/runs/:runId/receipt, or /api/v1/runs/:runId/evidence-packet.

Chorus variants are selected with request fields, not separate model ids:

Core request controls:

Health

GET /health

Returns gateway health and current provider information.

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

GET /api/v1/readiness

Admin endpoint used by the dashboard's Production readiness panel. It summarizes whether the current deployment is ready to expose to real users.

Checks include:

• Dashboard/API auth.
• Credential vault encryption.
• Live model provider configuration.
• Provider failover posture.
• Background job draining.
• Private web fetch/webhook posture.
• Public marketing/app host split.
• Billing and quota enforcement.

Example response:

{
  "generatedAt": 1760000000000,
  "summary": { "ready": 6, "attention": 1, "info": 1, "publicReady": false },
  "items": [
    {
      "id": "providers",
      "label": "Live model providers",
      "status": "ready",
      "message": "Configured: OpenAI, Anthropic.",
      "action": null,
      "actionHref": "#/governance",
      "docsHref": "/docs/configuration"
    }
  ]
}

API Keys

Admin required.

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.

Auth Sessions And Users

Session login is for dashboard humans. User management is admin-only.

Organizations And Invites

Organizations are the tenant boundary for dashboard users. A session has one active organization; API keys remain tenant-scoped.

Billing And Usage

Settings

Known settings:

Savings And Opportunities

Runs

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

Artifacts

Replay body:

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

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

Approvals

Decision body:

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

Learning

Cache

Invalidate body:

{
  "cacheType": "som"
}

Omit cacheType to clear all cache types for the tenant.

Governance And Audit

Workflows And Credentials

Workflows are interpreted graphs. llm nodes loop back through the gateway; web_fetch nodes create compact page context; tool_call nodes use registered MCP servers. See Workflows for graph configuration, node config, scheduling, and template details.

Chat And Agents

Conversations are chat threads whose assistant replies are real gateway runs with route, cost, and savings recorded per message. Agents are cron-schedulable single-task runners built on the workflow engine. See Chat & Agents for full semantics.

MCP Servers

Registered MCP servers back workflow tool_call nodes. Registry mutations are admin-only. Tool execution is governed before connection.

Jobs

Web Context

Fetch body:

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

Response includes:

• som: structured page snapshot
• source: adapter name, builtin, or cache
• cached
• htmlBytes
• somBytes
• tokensSavedEstimate
• diff when a previous snapshot exists
• context: compact prompt-ready rendering

SDK Trace And Tool Cache

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

Errors

Errors are JSON objects with an error key. Provider-compatible validation errors use the corresponding OpenAI-style or Anthropic-style error shape.

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.