# Overwing

> Guardrails-as-a-service for LLM output. POST text plus a rule set slug, get a typed
> pass / fail / review verdict per rule and in aggregate, with calibrated confidence,
> usually in under 500 ms. Verdicts come from TypeSafe's Jev System One model.

Agents and automated clients are first-class users here. There is no CAPTCHA, no
browser-only step, and every operation below works with plain HTTPS + JSON.

## Quickstart (one call to sign up, one call to evaluate)

    curl -X POST https://overwing.ai/api/v1/signup \
      -H "Content-Type: application/json" \
      -d '{"email":"you@example.com","password":"at-least-12-chars","org_name":"Acme"}'
    # -> { "api_key": "ow_live_...", "daily_limit": 250, ... }   (key is shown once)

    curl -X POST https://overwing.ai/api/v1/evaluate \
      -H "Authorization: Bearer ow_live_..." \
      -H "Content-Type: application/json" \
      -d '{"input":"<the LLM output to check>","rule_set":"content-safety"}'
    # -> { "id":"eval_...", "verdict":"pass|fail|review", "aggregate_score":0.93,
    #      "confidence":0.88, "latency_ms":187, "results":[ {rule, type, answer,
    #      probability, confidence, verdict}, ... ] }

If /api/v1/signup returns 503, programmatic signup is disabled on this deployment;
sign up at https://overwing.ai/login and create a key on the API keys page instead.

## MCP server (for Claude, Cursor, and any MCP client)

    npx -y overwing-mcp        # env: OVERWING_API_KEY=ow_live_...

Tools: evaluate, list_rule_sets, get_rule_set, create_rule_set, get_evaluation,
list_evaluations, get_usage, whoami, list_plans. Resource overwing://guide returns
this document. Package: https://www.npmjs.com/package/overwing-mcp

## Batches and retries

    POST /api/v1/evaluate/batch
    {"rule_set":"content-safety","items":[{"id":"m1","input":"..."},{"id":"m2","input":"..."}]}
    # -> {"summary":{"total":2,"pass":1,"fail":1,"review":0,"errors":0},
    #     "results":[{"id":"m1","index":0,"evaluation":{...},"error":null}, ...]}

Up to 50 items per call; each item counts as one evaluation. Send an
Idempotency-Key header (any string up to 255 chars) on evaluate or batch calls
and a retry within 24 hours returns the stored result instead of running and
charging again. Human-readable reference: https://overwing.ai/docs

## Authentication

Every endpoint except /api/v1/health, /api/v1/openapi.json and /api/v1/signup
requires `Authorization: Bearer ow_live_<32 hex>`. Keys can be minted and revoked
with POST/DELETE /api/v1/api-keys, so rotate them from code.

## How to read a verdict

- fail: at least one rule's fail condition matched. Block or redact.
- review: no rule failed, but at least one rule's confidence fell below its
  review threshold. Route to a human or a slower model.
- pass: everything else.
- aggregate_score is 0..1 (pass=1, review=0.5, fail=0 per rule, weighted).
- confidence is the minimum across rules. Use it as a second gate if you like.

## Rule sets

- content-safety (prebuilt, always available): toxicity, pii_detected, self_harm,
  sexual_content, severity.
- Create your own: POST /api/v1/rule-sets with name, slug and 1..25 rules. Three
  question types: choice (pick one option), score (position on an ordered scale),
  noul (yes/no). Each rule has a fail_condition, an optional review_condition
  ({"confidenceBelow": 0.8}) and a weight. GET /api/v1/rule-sets/content-safety
  is a complete worked example to copy from.

## Limits and headers

- Each evaluate response carries X-RateLimit-Limit, X-RateLimit-Remaining and
  X-RateLimit-Reset (unix seconds, resets at 00:00 UTC). A 429 includes Retry-After.
- Each plan also has a per-minute burst ceiling (free 30, starter 120, growth 300,
  scale 600). Responses carry X-Burst-Limit / X-Burst-Remaining / X-Burst-Reset;
  a burst 429 includes Retry-After in seconds. Spread calls or upgrade.
- input is capped at 100,000 characters; metadata at 8 KB.
- Free self-serve accounts get 250 evaluations per day. Paid plans raise it; the
  limit is per organization, not per key, so add keys freely.

## Plans and paying (agents can do this without a browser)

    GET  /api/v1/plans                       # public: ids, prices, daily limits
    GET  /api/v1/billing                     # your plan, limit, status
    POST /api/v1/billing/subscribe           # {"plan":"growth","payment_method":"pm_..."}
    POST /api/v1/billing/checkout            # {"plan":"growth"} -> hosted URL for a person
    POST /api/v1/billing/portal              # -> Stripe portal URL (cards, invoices)
    DELETE /api/v1/billing                   # cancel at period end

- Free: 250 evaluations/day. Starter $29: 5,000. Growth $99: 25,000. Scale $299: 100,000.
- subscribe needs a Stripe payment method id (pm_...) the first time. Get one from
  Stripe.js, a Stripe test token in test mode, or an agent payment provider that
  issues Stripe payment methods. Switching plans later needs only {"plan": ...}.
- The new limit applies the moment the subscription is active. If the bank wants
  an extra confirmation you get 202 with a payment_url to complete.

## Webhooks

PUT /api/v1/webhook {"url": "https://..."} returns an HMAC-SHA256 secret once.
Every fail or review evaluation is POSTed as an evaluation.completed event with
header X-Overwing-Signature: t=<unix seconds>,v1=<hex hmac of "<t>.<body>">.
Verify with a constant-time compare and reject if t is more than 5 minutes old.

## Endpoints

- POST   /api/v1/evaluate                 POST /api/v1/evaluate/batch   (both accept Idempotency-Key)
- GET    /api/v1/evaluations?limit&cursor&verdict&rule_set
- GET    /api/v1/evaluations/{id}
- GET    /api/v1/rule-sets            POST /api/v1/rule-sets
- GET    /api/v1/rule-sets/{slug}     PATCH /api/v1/rule-sets/{slug}   DELETE /api/v1/rule-sets/{slug}
- GET    /api/v1/usage?days
- GET    /api/v1/me
- GET    /api/v1/api-keys             POST /api/v1/api-keys            DELETE /api/v1/api-keys/{id}
- GET    /api/v1/webhook              PUT /api/v1/webhook              DELETE /api/v1/webhook
- GET    /api/v1/audit-log?limit&before   (keys, webhooks, rule sets, billing, rejected-key attempts)
- POST   /api/v1/signup
- GET    /api/v1/plans                POST /api/v1/billing/subscribe   POST /api/v1/billing/checkout
- GET    /api/v1/billing              POST /api/v1/billing/portal      DELETE /api/v1/billing
- GET    /api/v1/health
- GET    /api/v1/openapi.json  (full OpenAPI 3.1 schema)

## Deleting data

    DELETE /api/v1/evaluations/{id}                    # one record
    DELETE /api/v1/evaluations  {"confirm":"delete","before":"2026-01-01T00:00:00Z"}
    DELETE /api/v1/org          {"confirm":"<exact org name>"}   # everything, cancels billing

Health: GET /api/v1/health (liveness) or /api/v1/health?deep=1 (database round trip).

## Legal

Terms of service: https://overwing.ai/terms  ·  Privacy: https://overwing.ai/privacy  ·  Refunds: https://overwing.ai/refunds
Using the API means accepting the terms. Submitted text is processed by TypeSafe;
do not send data you are not permitted to share with that provider.

## Errors

Every non-2xx response is {"error": "<human readable message>"}. Validation errors
name the offending field, e.g. "rules[2]: fail_condition.failOn references unknown
option 'x'". Retry 429 after Retry-After and 502 with backoff; do not retry 4xx.