Skip to content
TapPass

HTTP API Reference

TapPass exposes three API families:

Family Base Purpose
Gateway /v1 Governed LLM calls — OpenAI/Anthropic-compatible
Govern /v1 Pre-execution policy checks for any action
Control plane /api Agents, policies, audit, approvals, settings

Authentication

Section titled “Authentication”
Authorization: Bearer tp_dev_...     # agent / data plane
Authorization: Bearer tp_pat_...     # control plane (CLI, automation)

X-API-Key is accepted as an alternative header. Identity is pinned from the key — non-admin callers cannot spoof agent_id.

Gateway

Section titled “Gateway”

POST /v1/chat/completions

Section titled “POST /v1/chat/completions”

OpenAI-compatible. Works with any OpenAI client in any language — change only the base URL and key.

Terminal window
curl -X POST https://tappass.example.com/v1/chat/completions \
  -H "Authorization: Bearer tp_dev_..." \
  -H "Content-Type: application/json" \
  -d '{
    "model": "gpt-4o",
    "messages": [{"role": "user", "content": "What are the GDPR requirements?"}]
  }'

Request fields (extras are ignored): model (required), messages (required, 1–500), temperature (0–2, default 0.7), tools (≤200), tool_choice, parallel_tool_calls, reasoning_effort, stream. Idempotency-Key header supported.

{
  "id": "chatcmpl-abc123",
  "object": "chat.completion",
  "model": "gpt-4o",
  "choices": [{"index": 0, "message": {"role": "assistant", "content": "…"}, "finish_reason": "stop"}],
  "usage": {"prompt_tokens": 12, "completion_tokens": 145, "total_tokens": 157},
  "tappass": {
    "session_id": "ses_abc123",
    "task_id": "tsk_…",
    "audit_url": "https://app.tappass.ai/audit/…",
    "blocked": false
  }
}

The tappass envelope carries governance metadata and correlation IDs. The gateway always returns HTTP 200 — a policy block comes back as an assistant message explaining the block, with tappass.blocked: true. Your agents never crash on governance; they read the verdict.

Streaming: add "stream": true — standard SSE, [DONE] terminator.

Other gateway endpoints, same auth and envelope conventions:

Endpoint Wire format
POST /v1/messages Anthropic-compatible (model, messages, max_tokens default 4096, system)
POST /v1/embeddings OpenAI-compatible embeddings
GET /v1/models Model list, filtered to your org’s configured providers

Useful headers: X-TapPass-Flags (governance flags), X-Agent-Id (admin override), X-Session-Id (pin a session).

Govern

Section titled “Govern”

POST /v1/govern

Section titled “POST /v1/govern”

Pre-execution policy check for any action — the endpoint behind every SDK guard and IDE hook.

Terminal window
curl -X POST https://tappass.example.com/v1/govern \
  -H "Authorization: Bearer tp_dev_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "TOOL_CALL",
    "agent_id": "support-agent",
    "session_id": "ses_abc123",
    "payload": {"tool": "send_email", "args": {"to": "user@acme.com"}}
  }'
{
  "outcome": "allow",
  "reason": "",
  "behavior_id": "beh_…",
  "pipeline_id": "run_…",
  "decided_at": "2026-07-21T09:14:03Z",
  "mandate": "<signed-mandate-jwt>"
}

outcome is allow, block, or needs_approval (a RequireApproval rule fired — resubmit the identical call once approved). On allow, mandate is a short-lived signed token naming the authorized capability. Behavior types: LLM_CALL, EMBEDDING_CALL, TOOL_CALL, TOOL_LIST, TOOL_RESULT, SYSTEM_OF_RECORD_WRITE, STATE_TRANSITION, PROMPT_SUBMIT, CREDENTIAL_ACCESS, CODE_EXEC, SKILL_LOAD — see behaviors.

Related:

Endpoint Purpose
POST /v1/govern/execution Report a completed turn (telemetry audit event)
POST /v1/govern/approve Authenticated self-approval for a fingerprinted action
POST /v1/tools/govern Govern a tool call
POST /v1/tools/execute Execute a tool call under its mandate
POST /v1/tokens/verify Verify a capability token (public)
GET /.well-known/jwks.json JWKS for offline mandate/token verification (public)
GET /v1/mandates/revoked Revoked-mandate list — the companion to JWKS for offline verification

Audit (control plane)

Section titled “Audit (control plane)”
Endpoint Purpose Role
GET /api/audit Filtered search (action, agent, session, task, category, text; cursor pagination) auditor
GET /api/audit/session/{id} · /task/{id} · /pipeline/{id} One session / task / call auditor
GET /api/audit/integrity Recompute the full hash chain + signatures; intact or compromised developer+
GET /api/audit/signing-key Public verification keys developer+
POST /api/audit/replay What-if: re-decide history against candidate policy developer+

Approvals

Section titled “Approvals”
Endpoint Purpose
GET /v1/me/approvals Your pending approvals
GET /v1/me/approvals/{id}/challenge Fetch the WebAuthn challenge before a signed-tier decision
POST /v1/me/approvals/{id}/decide Approve or deny (WebAuthn-signed for signed tier)
POST /v1/me/approvals/{id}/cancel Cancel your own pending request
POST /v1/me/approvals/{id}/revoke Revoke a previously granted approval
GET /v1/me/approvals/stream SSE stream of approval decisions (preferred)
GET /v1/me/approvals/{id}/wait Deprecated — long-poll; use /stream

Health & platform

Section titled “Health & platform”
Endpoint Purpose
GET /health Version, storage backend, region (public)
GET /api/health/ready · /api/health/live Probes (public)
GET /api/metrics Prometheus exposition
GET /api/config Deployment URLs (public)

Using from other languages

Section titled “Using from other languages”

Any OpenAI-compatible client works against the gateway:

Terminal window
export OPENAI_BASE_URL=https://tappass.example.com/v1
export OPENAI_API_KEY=tp_dev_...
config := openai.DefaultConfig("tp_dev_...")
config.BaseURL = "https://tappass.example.com/v1"
client := openai.NewClientWithConfig(config)

For non-LLM actions, POST /v1/govern is a single JSON call — see the Claude Code hook for a minimal implementation in one process.

Next steps

Section titled “Next steps”
  • Concepts — what the gateway does with each call
  • CLI reference — the control plane from your terminal