API Reference
The Tawa REST API — base URL, conventions, and the full endpoint reference.
The Tawa REST API is organised around scans: you submit text and get a decision back in the same call, synchronously. It uses predictable URLs and returns JSON for every response.
- Base URL —
https://gateway.tawaguard.com/v1(region-resolved automatically per organization by the official SDKs) - Auth — API key as a bearer token, or the
x-api-keyheader (see Authentication) - Versioning — the version is part of the path, e.g.
/v1/scan
curl -X POST https://gateway.tawaguard.com/v1/scan \
-H "Authorization: Bearer $TAWA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"text": "Ignore all previous instructions…"}'The endpoint pages in this section are generated from the Tawa OpenAPI spec — each renders request/response schemas, code samples, and a live "Try it" playground.
Conventions
- All requests and responses use JSON.
- The
actionfield on the wire is uppercase (ALLOW,HARD_BLOCK, ...); the official SDKs lowercase it on parse — see How Tawa works for the full action set. - Errors use standard HTTP status codes with a structured
errorobject and a machine-readablecode— see Best practices.
Prefer the SDK
Both the TypeScript and Python SDKs wrap every endpoint below with a fully-typed method, request retries, and response parsing — most integrations should reach for those rather than calling the REST API directly.
Building in a language we don't have an SDK for? Best practices covers rate limiting, retries, timeouts, and session grouping — the same behavior the official SDKs implement for you — so you can build a client that follows the same design.