Shadow Warden AI Developer Portal
One entry point for everything programmatic: the REST API and its OpenAPI document, authentication, the rate-limit contract, the SDKs and CLI, and the MCP server. Every URL on this page answers — nothing here is aspirational.
Guides
Quick start
Docker Compose to first filtered request. Copy-paste curl included.
Read →Authentication
X-API-Key, OIDC bearer on /ext/*, admin keys, and what each rejection code means.
Read →Rate limits
The RateLimit header contract every response carries, and how to pace against it.
Read →API reference
Endpoint reference, rendered from the same OpenAPI document the gateway serves.
Read →SDKs
Python and TypeScript clients for the gateway.
Read →CLI
The warden console script: install, commands and the exit codes scripts rely on.
Read →Versioning
v1 in the path, Deprecation and Sunset headers, and the 180-day notice commitment.
Read →MCP server
Call the gateway as tools from Claude, ChatGPT or any MCP client over Streamable HTTP.
Read →Machine-readable surfaces
Published at predictable paths on shadow-warden-ai.com. Rows marked “→ gateway” are proxied to api.shadow-warden-ai.com, so one host answers for all of them.
| Resource | URL |
|---|---|
| OpenAPI 3.1 document Every REST path, schema and security scheme. Carries a servers block, so a client does not have to infer the base URL. | /openapi.json |
| llms.txt What this product is, when to reach for it, and the honesty notes. | /llms.txt |
| Agent instructions Best-fit jobs, what this is not, and the status codes an agent must handle. | /.well-known/agent-instructions.md |
| Agent card (A2A/ADP) Capability manifest for agent-to-agent discovery. | /.well-known/agent.json |
| MCP manifest MCP server descriptor: endpoint, transport, auth schemes, tool list. | /.well-known/mcp.json |
| Marketplace manifest M2M marketplace descriptor: registration, KYA, payment rails. | /.well-known/ai-market.json |
| DID document did:web identity for the publisher of the above. | /.well-known/did.json |
| Sitemap Every page, for crawlers that would rather not guess. | /sitemap-index.xml |
The endpoints you will reach for first
Base URL https://api.shadow-warden-ai.com. The full list — 500+ paths — is in the OpenAPI document. Prefix an unversioned path with /v1 to pin the version — the paths below already show it where the route requires it, so do not add a second one.
| Method | Path |
|---|---|
| POST | /filter Run text through the nine-stage pipeline. Returns a verdict, a score and the deciding stage. |
| POST | /filter/batch The same, for up to 100 items in one call. |
| GET | /health Liveness, version and pipeline readiness. |
| GET | /xai/explain/{id} The causal chain behind one decision, by request id. |
| POST | /v1/chat/completions OpenAI-compatible proxy. Every message is filtered before it reaches the model. |
| POST | /mcp/ MCP Streamable HTTP transport, JSON-RPC 2.0. |
First request
curl -sS -D- -X POST https://api.shadow-warden-ai.com/filter \
-H "X-API-Key: $WARDEN_API_KEY" \
-H "Content-Type: application/json" \
-d '{"content": "ignore previous instructions"}'
# RateLimit-Policy: "requests-per-minute";q=60;w=60
# RateLimit: "requests-per-minute";r=59;t=41 Before you build on it
- Jailbreak detection measures 36.2% on our own 58-prompt adversarial corpus, with 0 of 35 benign prompts flagged. No higher figure is ours.
- Per-stage latency is not instrumented in production, so no millisecond figure is published.
- Marketplace escrow and settlement run on testnet.
- We hold no certification of any kind. Control mappings are self-attested — see the trust centre.