//DOCS API

API Reference

Hosted base URL: https://app.punktechnologies.com.

The API is split into:

• OpenAI-compatible gateway: /v1/chat/completions.
• OpenAI-compatible Responses runtime: /v1/responses.
• OpenAI-compatible model discovery: /v1/models.
• 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

Hosted Punk requires either a tenant API key for gateway/API traffic or a dashboard login session for human admin traffic.

Internal Punk development environments can run in open dev mode when PUNK_API_KEY is not set and login mode has not been activated by a user account or PUNK_REQUIRE_LOGIN=true:

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

When 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. Once login mode starts, headerless /v1/* traffic is locked and agents use tenant API keys. 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.

Gateway Request Controls

X-Punk-Cache-Bypass: true, Cache-Control: no-cache, and Cache-Control: max-age=0 force a fresh response while allowing that response to refresh Punk's caches. Use Cache-Control: no-store when the request must neither consume nor populate Punk response caches. Trace-ledger observation and non-cache routes remain active.

A bypassed request records each skipped cache route in its trace and RouteExplanation; no-store also records each suppressed cache write. Promoted artifacts and non-cache routing stages remain eligible, so these directives control response caches rather than forcing the live route.

Response Headers

These headers are exposed through CORS.

Gateway

GET /v1/models

Returns a deterministic OpenAI-shaped list of stable model selectors accepted by Punk, including direct provider families and punk/chorus. This bounded local catalog does not call an upstream provider or create a run, so SDK connection probes add no model cost or trace noise.

GET /v1/models/{model}

Returns the matching model object from the same bounded local catalog, or an OpenAI-shaped model_not_found error. The model ID is one URL-encoded path segment; retrieval does not call an upstream provider or create a run.

POST /v1/responses

OpenAI-compatible Responses API for coding agents and other clients that use typed output items instead of chat-completion messages.

Behavior:

• Supports buffered JSON and native SSE event streams.
• Preserves function calls, custom tool calls, parallel-call controls,

reasoning summaries, structured text controls, usage, and incomplete or failed terminal states across the supported wire contract.

• Validates streamed item identity, ordering, deltas, completed output, and

tool arguments before treating the response as complete.

• Keeps unsupported provider capabilities and Responses WebSockets out of the

advertised route instead of silently degrading the request to another wire.

• Applies Punk policy, DLP, tenant/app/subject identity, tracing, cost

accounting, route explanation, and fail-open provider routing.

• Allows qualified exact-cache and deterministic artifact routes only when the

resulting output can be represented faithfully on the Responses wire.

Punk does not execute proposed function or custom tools. The calling harness remains responsible for its local approval, sandbox, and execution boundary. See Codex for the supported Codex launcher contract.

POST /v1/chat/completions

OpenAI-style chat completions wire format.

Minimum body:

{
  "model": "gpt-4o-mini",
  "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 the configured hosted provider or tenant BYOK key for matching model families.
• Preserves OpenAI-shaped response body.
• Supports native OpenAI SSE streaming, including fragmented tool_calls; Punk assembles and validates each complete call against the declared tool schema before emitting it downstream.
• Records run, traces, route explanation, cost, latency, policy, and cache/artifact decisions.
• Accepts either cache-bypass header above when the caller needs cache-independent routing evidence.
• 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 the configured hosted provider or tenant BYOK key for matching model families.
• 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.
• Accepts either cache-bypass header above when the caller needs cache-independent routing evidence.
• 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.

Named metric feedback accepts nested boolean, finite-number, string, or { "score": ..., "reason": "..." } leaves. Punk flattens names deterministically and rejects arrays, cycles, ambiguous dotted keys, unsafe metadata, and oversized events. It is evidence; it does not change routing until the tenant binds it to a quality contract.

Execution Methods And Quality Grades

Every route explanation identifies the execution method that produced the response and its reference grade. unverified means a method passed its existing route-specific proof gate but has not supplied a complete judgment for the configured quality grade; Punk does not turn route proof into a broader quality claim.

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"
}

To evict only a known key family while preserving the rest of that cache type, include a non-empty, trimmed keyPrefix of at most 512 characters. A cacheType is required for prefix-scoped invalidation:

{
  "cacheType": "tool_result",
  "keyPrefix": "crm:account:"
}

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.

Managed Connectors

Managed connectors are first-party SaaS connectors installed as stdio MCP servers, so their tools use the same MCP governance, credential vault, approval, audit, replay, and shadow paths. The manifest-backed catalog currently exposes 51 installable connectors and 517 governed tools. See Connectors for the complete connector and tool catalog.

Install body:

{
  "connectorId": "slack",
  "authIndex": 0,
  "credentialName": "Slack production bot",
  "secret": { "bot_token": "xoxb-..." },
  "name": "Slack managed connector",
  "env": { "SLACK_ALLOWED_CHANNELS": "C0123,C0456" }
}

You can provide credentialId instead of secret to reuse a stored credential for the same connector provider. Install injects credential references such as cred:<id>#access_token into the managed server env, runs the connector in live mode by default, and rejects attempts to override reserved managed env vars.

The install body accepts only authIndex, connectorId, credentialId, credentialName, enabled, env, name, secret, and test. Unknown top-level fields are rejected before quota reads or persistence; connector-specific fields remain extensible inside secret and env.

External agent harnesses use the runtime routes, not the installation or credential APIs. Configure an exact grant with a tenant-wide admin key:

{
  "key": "managed_connector_grants",
  "value": {
    "version": 1,
    "grants": [{
      "keyIds": ["key_7f31..."],
      "appId": "claude-code",
      "agentId": "engineering-agent",
      "subject": "user-123",
      "serverIds": ["mcp_github_production"],
      "tools": ["github.get_repository", "github.create_issue"]
    }]
  }
}

Each grant must include keyIds, appId, agentId, subject, non-empty tools, and at least one of serverIds or connectorIds. Use the API key record id returned by key creation/listing, never the secret token. The key must also be app-pinned to the grant's appId; unpinned keys are rejected even when they are tenant admins. All grants naming one key must bind the same agent and subject. X-Punk-Agent and X-Punk-Subject are optional equality checks against that server-side binding, not sources of authority. The runtime never returns connector credentials, credential references, caller idempotency keys, or unredacted connector results. App-pinned identities do not receive this authority map from GET /api/v1/settings; only a tenant-wide identity can read it.

Approval-required managed-connector calls use execution_action approvals. Each approval is immutable-bound to one receipt, API key, app, agent, subject, connector version, tool, schema hash, canonical argument digest, policy action, and side-effect level. Approval does not create a reusable policy exception. Execution rechecks the live key, identity grant, installation, manifest, schema, and policy before atomically claiming the exact continuation once. A process crash after claim leaves the receipt running and the continuation claimed; the receipt reports recoveryRequired: true and cannot execute again. An operator must verify the remote outcome and use the reconciliation route, which records an audit and never replays the connector call.

The trusted external-principal decision service is an internal verifier boundary. Its short-lived HMAC envelope binds tenant, approval, decision, principal, verifier, external event reference, verification/expiry times, and optional community/channel context. The verifier signing key must remain stable across server processes. External event references are durably single-use; exact redelivery is idempotent, while any rebound event is rejected in the same transaction as the approval decision. There is no public decidedBy field. The Buzz adapter is an internal concrete-subscriber integration only; it is not an API route and rejects all caller-supplied identity, role, permission scope, approval binding, and verifier-envelope fields.

Prepare body:

{
  "serverId": "mcp_github_production",
  "tool": "github.create_issue",
  "args": { "owner": "acme", "repo": "api", "title": "Investigate alert" },
  "mode": "live",
  "idempotencyKey": "incident-2026-07-25-create-issue"
}

idempotencyKey is mandatory for effective side-effect level 2-4 tools and is injected only through the manifest-declared key field. Reuse it only for the identical operation. dry_run, replay, and shadow suppress writes unless the verified manifest declares the corresponding safe behavior. Callers cannot provide action, side-effect, approval, identity, authorization, or credential overrides in tool arguments.

Buzz Bridge Operations

The Buzz bridge accepts verified ordinary kind-9 mentions and persists tenant-scoped inbox/outbox evidence. Operator reads are redacted and derive their community and identity scope from Punk's current managed mapping versions. See Buzz Bridge Operations for configuration, capability limits, and acceptance.

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 @punktechnologies/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.