# Docs

- [Introduction](/docs): Tawa Guard inspects prompts for injection and other attacks before they reach your LLM. Pick TypeScript, Python, or the raw API.
- [Connect AI tools](/docs/connect-ai-tools): Connect Claude, ChatGPT, Cursor and other MCP clients to your Tawa Guard account with OAuth, and see what they can read.
- [EU AI Act evidence](/docs/eu-ai-act-evidence): Generate a pack of what Tawa Guard recorded for one app over one period, set beside seven articles of the EU AI Act, and check that its files are unchanged.
- TypeScript: @tawaguard/sdk — getting started, guides, integrations, and cookbook recipes for TypeScript/JavaScript.
  - [TypeScript](/docs/typescript): Scan prompts, RAG content, and agent tool traffic from TypeScript/JavaScript.
  - Getting Started
    - [Quickstart](/docs/typescript/getting-started/quickstart): Scan your first prompt with the TypeScript SDK in a couple of minutes.
    - [Installation](/docs/typescript/getting-started/installation): Install the Tawa TypeScript SDK and construct the client.
  - Guides
    - [Authentication](/docs/typescript/guides/authentication): How the TypeScript client authenticates, and how key verification works.
    - [Identifiers](/docs/typescript/guides/identifiers): Attach a customer/user identifier to a scan to track decisions per user.
    - [Policy rules](/docs/typescript/guides/policy-rules): Add per-request rules that contribute directives to a scan's verdict, on top of built-in detection.
    - [Enforcing a policy](/docs/typescript/guides/enforcing-policy): Policy directives are signals — here's how to actually act on them.
    - [The review flag](/docs/typescript/guides/review-flag): Scans return ALLOW or BLOCK. A needsReview flag marks the uncertain ones, for tuning and for routing to a second model.
    - [Errors & retries](/docs/typescript/guides/error-handling): How the TypeScript SDK surfaces failures, and its automatic retry behavior for transient errors.
    - [Live event stream](/docs/typescript/guides/live-events): Subscribe to a real-time stream of every scan in an agent turn.
  - Integrations
    - [Integrations](/docs/typescript/integrations): Framework-native ways to wire Tawa into an existing TypeScript AI stack.
    - [Vercel AI SDK](/docs/typescript/integrations/vercel-ai-sdk): Wrap a model once — every generateText/streamText call is scanned before it reaches the provider.
  - Cookbook
    - [Cookbook](/docs/typescript/cookbook): Complete, working recipes for common integration patterns.
    - [Raw OpenAI (no framework)](/docs/typescript/cookbook/raw-openai): Screen a prompt before an OpenAI call, without the Vercel AI SDK.
    - [Raw Claude (no framework)](/docs/typescript/cookbook/raw-claude): Screen a prompt before a Claude call, without the Vercel AI SDK.
    - [RAG protection](/docs/typescript/cookbook/rag-protection): Scan retrieved documents before they're stitched into a prompt you send to your LLM.
    - [Agent protection](/docs/typescript/cookbook/agent-protection): Scan a proposed tool call before executing it, and its output before it re-enters the agent loop.
    - [Next.js Route Handler](/docs/typescript/cookbook/nextjs-route-handler): Wire a scan into an App Router API route before forwarding to your model.
  - SDK Reference
    - [TypeScript](/docs/typescript/sdk): The Tawa TypeScript SDK — a fully-typed client for scanning prompts, RAG content, and agent tool traffic.
    - [Configuration](/docs/typescript/sdk/client): Construct the Tawa client and understand region resolution and custom base URLs.
    - [Scanning](/docs/typescript/sdk/scanning): Every scan method on the Tawa client — analyze, RAG protection, and agent protection.
- Python: tawaguard-sdk — getting started, guides, integrations, and cookbook recipes for Python.
  - [Python](/docs/python): Scan prompts, RAG content, and agent tool traffic from Python.
  - Getting Started
    - [Quickstart](/docs/python/getting-started/quickstart): Scan your first prompt with the Python SDK in a couple of minutes.
    - [Installation](/docs/python/getting-started/installation): Install the Tawa Python SDK and construct the client.
  - Guides
    - [Authentication](/docs/python/guides/authentication): How the Python client authenticates, and how key verification works.
    - [Identifiers](/docs/python/guides/identifiers): Attach a customer/user identifier to a scan to track decisions per user.
    - [Policy rules](/docs/python/guides/policy-rules): Add per-request rules that contribute directives to a scan's verdict, on top of built-in detection.
    - [Enforcing a policy](/docs/python/guides/enforcing-policy): Policy directives are signals — here's how to actually act on them.
    - [The review flag](/docs/python/guides/review-flag): Scans return ALLOW or BLOCK. A needs_review flag marks the uncertain ones, for tuning and for routing to a second model.
    - [Errors & retries](/docs/python/guides/error-handling): How the Python SDK surfaces failures, and how to tune its retry and timeout behavior.
  - Integrations
    - [Integrations](/docs/python/integrations): Framework-native ways to wire Tawa into an existing Python AI stack.
    - [OpenAI Agents SDK](/docs/python/integrations/openai-agents-sdk): Input, output and function-tool guardrails using the Agents SDK's own hooks.
  - Cookbook
    - [Cookbook](/docs/python/cookbook): Complete, working recipes for common integration patterns.
    - [Raw OpenAI (no framework)](/docs/python/cookbook/raw-openai): Screen a prompt before an OpenAI call, without the OpenAI Agents SDK.
    - [Raw Claude (no framework)](/docs/python/cookbook/raw-claude): Screen a prompt before a Claude call, without a framework.
    - [RAG protection](/docs/python/cookbook/rag-protection): Scan retrieved documents before they're stitched into a prompt you send to your LLM.
    - [Agent protection](/docs/python/cookbook/agent-protection): Scan a proposed tool call before executing it, and its output before it re-enters the agent loop.
    - [FastAPI](/docs/python/cookbook/fastapi): Wire a scan into a FastAPI endpoint with the async client.
  - SDK Reference
    - [Python](/docs/python/sdk): The Tawa Python SDK — sync and async clients for scanning prompts, RAG content, and agent tool traffic.
    - [Configuration](/docs/python/sdk/client): Construct the sync or async Python client, and understand when each verifies its API key.
    - [Scanning](/docs/python/sdk/scanning): Every scan method on the Python client — analyze, RAG protection, and agent protection.
- Claude Code: tawa-claude-proxy — a local relay that scans every Claude Code request before it reaches api.anthropic.com.
  - [Claude Code](/docs/claude-code): Protect a Claude Code session without changing any code — point it at a local relay instead of api.anthropic.com.
  - [Quickstart](/docs/claude-code/quickstart): Build tawa-claude-proxy from source and protect a real Claude Code session in a few minutes.
  - [Docker](/docs/claude-code/docker): Run tawa-claude-proxy as a local container — no Rust toolchain on the host, and an easy way to keep it always-on.
  - [VPS deployment](/docs/claude-code/vps-deployment): Run tawa-claude-proxy on a server for a team or CI runners, instead of one developer's laptop.
  - [Configuration](/docs/claude-code/configuration): Every environment variable tawa-claude-proxy reads, how blocking is decided, and what SDK-level options aren't wired up here yet.
- Codex: tawa-codex-proxy — a local relay that scans every Codex CLI request before it reaches the OpenAI Responses API.
  - [Codex](/docs/codex): Protect a Codex CLI session without changing any code — point it at a local relay instead of the OpenAI Responses API.
  - [Quickstart](/docs/codex/quickstart): Build tawa-codex-proxy from source and protect a real Codex CLI session in a few minutes.
  - [Docker](/docs/codex/docker): Run tawa-codex-proxy as a local container — no Rust toolchain on the host, and an easy way to keep it always-on.
  - [VPS deployment](/docs/codex/vps-deployment): Run tawa-codex-proxy on a server for a team or CI runners, instead of one developer's laptop.
  - [Configuration](/docs/codex/configuration): Every environment variable tawa-codex-proxy reads, how blocking is decided, and what SDK-level options aren't wired up here yet.
- API Reference: The raw REST API — auth, conventions, rate limits/retries, and the full endpoint reference. Language-agnostic.
  - [API Reference](/docs/api): The Tawa REST API — base URL, conventions, and the full endpoint reference.
  - [How Tawa works](/docs/api/concepts): The scan pipeline and the decision model.
  - [Authentication](/docs/api/authentication): How Tawa authenticates API requests with API keys.
  - [Policy rules](/docs/api/policy-rules): The rule schema evaluated on every scan, and the directives it can contribute to a verdict.
  - [Language support](/docs/api/languages): Which languages Tawa identifies and scans, and how everything else is handled.
  - [Best practices](/docs/api/best-practices): Rate limits, retries, timeouts, and session grouping — for building your own client against the raw API.
  - Analytics
    - [Prometheus scrape endpoint](/docs/api/analytics/analyticsMetrics): The org's current billing period as Prometheus text-exposition format — the native scrape target for Grafana's Prometheus data source and Datadog's OpenMetrics/Prometheus check. Always the current billing period; the only query parameter is `include_preview`.
    - [Aggregate metrics for a period](/docs/api/analytics/analyticsSummary): Call volume, decisions, latency, credits, and an organization-wide billing snapshot for the calling app. Defaults to the org's current billing period when `start`/`end` are omitted. Requires an analytics API key — a regular scan key is rejected.
    - [Bucketed metrics for charting](/docs/api/analytics/analyticsTimeseries): Call volume, decisions, credits, and latency bucketed by hour or day, zero-filled so every interval has a point — for a Grafana JSON-API panel or a Datadog custom HTTP check. Bounded to 90 days and 1000 buckets per request.
  - [Analytics API](/docs/api/analytics): Pull aggregate spend, call volume, and decision metrics into Grafana, Datadog, or another BI tool.
  - Agent
    - [Scan a proposed tool call](/docs/api/agent/scanToolCall): Inspect a proposed tool call before execution.
    - [Scan a tool's output](/docs/api/agent/scanToolOutput): Inspect a tool's returned output before it re-enters the agent loop.
  - Events
    - [Subscribe to a session's live event stream](/docs/api/events/subscribeEvents): Server-Sent Events. Every scan (`/scan`, `/rag/*`, `/agent/*`) that carries the same `session_id` publishes a compact decision summary here the moment it's made (no scanned text, tool arguments, or redacted content ever appears on this stream, only the decision itself). This is what the SDK's `subscribe()` connects to.

Three event shapes appear as `data:` frames, distinguished by `stage`:

- A decision (`stage`: `prompt`, `rag`, `tool`, or `response`):
  `action`, `risk` (0-100), `latency` (ms), the policy directives
  that fired, a `job_id`, and a `pii` summary when any was found.
  `action` is the engine's label (lowercase, so `review` appears
  here). `needs_review` (boolean) and `enforced_action` (`allow` or
  `block`, the action the gateway enforced after applying your
  app's `reviewCollapse` setting) are added from the `review_flag`
  release onward.
  `tool`/`rag` stages also carry `phase` (`call`/`output` or
  `chunk`/`context`) and, for `tool`, the tool name.

- `{"stage": "audit", "id": "<job_id>"}`: sent once that job's
  decision has been durably persisted, always after that job's
  decision event.

- `{"stage": "_meta", "dropped": <n>}`: this connection fell behind
  and missed `n` events; never sent silently.


The connection is long-lived: it stays open with periodic keep-alive comments until the caller disconnects. Capped at 40 concurrent connections per organization.
  - Keys
    - [Verify an API key](/docs/api/keys/verifyKey): Validate an API key and return its metadata.
  - Knowledge
    - [List knowledge buckets](/docs/api/knowledge/listKnowledgeBuckets): Lists the knowledge buckets of the app the API key belongs to, with the number of documents currently served from each. The key must be tied to an app; the app is taken from the key, never from the request.
    - [Read a served document](/docs/api/knowledge/readKnowledgeDocument): Returns the served text of one document, in parts of up to 60,000 characters. While `next_offset` is not null, call again with `offset=next_offset` to read the next part.
    - [Search served knowledge](/docs/api/knowledge/searchKnowledge): Searches the documents currently served from the app's buckets. Combines keyword and semantic ranking and returns at most one hit per document. When semantic search is unavailable the response has `mode: "keyword"` and a `note` saying so. Documents in review or still being scanned are not searched; the previously served version keeps answering until the new one is released.
  - Rag
    - [Scan a single retrieved chunk](/docs/api/rag/scanRagChunk): Scan one retrieved document chunk before it enters the assembled context.
    - [Scan the fully assembled prompt](/docs/api/rag/scanRagContext): Scan the fully assembled prompt (system + retrieved chunks + user turn), immediately before the LLM call.
    - [Scan an entire retrieved set](/docs/api/rag/scanRagRetrieval): Scan a whole retrieved set in one call — a per-chunk verdict plus an aggregate.
  - Scan
    - [Scan a plain prompt](/docs/api/scan/scan): The general-purpose entry point. Scans text with provenance `user_prompt` — before it reaches your LLM.
- [Changelog](/docs/changelog): Release notes for Tawa Guard, newest first.