# Gated API Specification (v1)
> Publicly readable REST API specification for developers and AI coding assistants.
> Trust Manifest: https://getgated.ai/.well-known/ai-trust.json | LLM Guide: https://getgated.ai/llms.txt

Base URL: `https://getgated.ai`
Authentication: `Authorization: Bearer <M6L_GATE_KEY>`

## Zero-Trust Data Contract
- Gated inspects **only** the untrusted end-user input string (`input`), an opaque visitor identifier (`user`), `app_id`, and character counts.
- Customer applications **never** transmit their system prompt, OpenAI/Anthropic/Supabase keys, database rows, or payment details to Gated.
- Raw `input` text is evaluated in volatile memory (<1ms) and discarded immediately (0-second disk retention).

## POST /v1/check
Synchronous pre-LLM request check.

### Request Body
```json
{
  "app_id": "app_15ad7beb3e6593de",
  "user": "usr_123_or_ip",
  "input": "User prompt text...",
  "input_chars": 19,
  "messages": 3,
  "context_chars": 1420,
  "feature": "chat",
  "anonymous": false
}
```

### Response (200 OK)
```json
{
  "allow": false,
  "verdict": "block",
  "reason": "off_topic",
  "category": "off_topic",
  "message": "Sorry, I can't help with that request.",
  "retry_after_s": null,
  "check_id": "chk_01J...",
  "estimated_tokens": 520,
  "processing_us": 42
}
```

## POST /v1/usage
Optional post-LLM token reconciliation.

### Request Body
```json
{
  "check_id": "chk_01J...",
  "model": "gpt-4o-mini",
  "input_tokens": 310,
  "output_tokens": 185
}
```

## GET /v1/analytics/summary
Returns real-time total checks, allowed, flagged, blocked, breakdown by category, and estimated USD saved.

## GET /v1/analytics/export (Business $49/mo Plan Exclusive)
Included with the **Business ($49/mo)** plan (returns HTTP 403 pro_plan_required on Starter or Builder plans). Returns up-to-the-second interception events and `abusive_users_rollup` grouped by pseudonymous user reference (`customer_user_ref` / `user_hash`) so your backend can join abusive activity against your local `users` table without ever sending PII to Gated.
- **Polling Cooldown (5 Minutes / 300 Seconds):** Enforces a 300-second minimum interval between fetch calls per API key (`min_poll_interval_seconds: 300`, `Cache-Control: private, max-age=300`). Calling again within 300 seconds returns `HTTP 429 Too Many Requests` with `Retry-After`. Always cache the response in your backend or database for 5 minutes.