SchemaShield Documentation

Quickstart

1. Create a project and an API key from the dashboard (Start Free on the homepage).
2. Prepare a JSON Schema for your output. If you have Zod/TS/Pydantic, convert to JSON Schema first.
3. POST your prompt and schema to https://schemashield.ai/v1/shield.

curl -X POST https://schemashield.ai/v1/shield \
  -H "Authorization: Bearer ssk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "provider":"openai",
    "model":"gpt-4.1-mini",
    "prompt":"Extract a product {name, priceUSD:number}. Text: iPhone 15 costs $799.",
    "schema":{"type":"object","properties":{"name":{"type":"string"},"priceUSD":{"type":"number"}},"required":["name","priceUSD"],"additionalProperties":false}
  }'

Success: { ok:true, data }. Failure: { ok:false, error, diff } (non‑200).

CI Guard (GitHub Action)

# .github/workflows/shield.yml
name: SchemaShield CI
on: [pull_request]
jobs:
  shield:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: schemashield/schemashield-action@v1
        with:
          token: ${{ secrets.SS_TOKEN }}
          provider: openai
          model: gpt-4.1-mini
          schemas: ./schemas
          prompts: ./prompts
          seeds: 3
          mode: validate

The action computes cases by matching prompt files to schema files by base filename and calls /v1/ci/run. It fails the job if any case fails or diffs.

API Reference

POST /v1/shield

Body:

{
  "provider": "openai|anthropic",
  "model": "string",
  "prompt": "string",
  "schema": { /* JSON Schema */ },
  "temperature": 0.0,
  "max_retries": 1,
  "seed": 0,
  "persist": false,
  "mode": "validate|repair",
  "provider_secrets": { "openai": {"api_key": "..."} }
}

Headers returned: X-SS-Remaining-Validations, X-SS-Remaining-Repairs, X-SS-Latency-MS.

POST /v1/ci/run

{
  "provider_matrix": [{"provider":"openai","model":"gpt-4.1-mini"}],
  "seeds": [0,1,2],
  "cases": [{"name":"person","prompt":"...","schema":{...}}],
  "mode": "validate"
}

Returns 200 on pass, 409 with diff on failures.

Plans & Quotas

• Free: 1 project, 5k validations, 200 repairs, no CI, 1 seat.
• Pro: 10 projects, 50k validations, 3k repairs, CI 1 repo, 2 seats.
• Team: Unlimited projects, 250k validations, 15k repairs, CI 5 repos, 5 seats.
• Top‑ups: +100k validations ($5), +5k repairs ($5). Add‑on seats: +5 ($5/mo).

Troubleshooting

• 422 schema_mismatch: Check required fields, additionalProperties, enums/regex.
• 429 rate limit: Retry with backoff; contact support for higher limits.
• 402 quota_exceeded: Upgrade plan or purchase a top‑up.
• Provider errors: Ensure provider key is valid when using per‑request provider_secrets.

Support: support@schemashield.ai