API documentation

Authentication

Three credentials, three jobs. Never confuse them:

Missing or unknown key: 401. Valid but inactive key (email not confirmed): 403 with a message saying exactly that.

Credits & billing

1 credit scans up to 1,000 characters, rounded up, minimum 1 per request; a 20,000-character document bills 20. Every response reports billed and carries an X-Credits-Remaining header. Credits never expire; packs are one-time purchases from the dashboard.

Errors

Scan text for prompt injection, jailbreaks, and agent manipulation before your model reads it.

Request body

Response

{ "allowed": false, "verdict": "block", "score": 100,
  "reason": "Blocked an attempt to extract the system's own prompt.",
  "rule": "system_prompt_extraction", "chunks": 1, "billed": 1 }

Judge one OS-level action before executing it. Deterministic, milliseconds, 1 credit.

Request body

Response

{ "allowed": false, "verdict": "block",
  "reason": "Shell execution is permanently disabled.", "billed": 1 }

Validate a model's proposed output against your ground-truth state using preset rules. Catches the confident answer that contradicts the data it claims to come from. 1 credit.

Request body

Example

curl -X POST https://api.sovereign-shield.net/check-output \
  -H "Authorization: Bearer ss_YOUR_KEY" -H "Content-Type: application/json" \
  -d '{"proposal": {"refund": 9500}, "state": {"order_total": 120},
       "rules": [{"rule": "range", "args": ["refund"], "kwargs": {"min_val": 0, "max_val": 120}}]}'

{ "valid": false, "errors": [...], "feedback_vector": "..." }  # feed it into the next prompt

Evaluate a named tool call against your server-side policy: the same judgment the gateway applies automatically, exposed as a call for agents you wire yourself. Bills 1 credit plus 1 per string parameter scanned.

Request body

Decision order

deny list → default-deny allowlist → parameter conditions (max/min/allowlist/denylist; a missing, non-numeric, or non-finite value is a violation) → CoreSafety primitives → parameter injection scan → approval gate → allow.

Response verdicts

"verdict": "allow" | "block" | "needs_approval"   # needs_approval includes approval_token

The enforcing gateway. Point your SDK's base URL at us; requests are scanned on the way in (tool results treated as untrusted, plus a whole-conversation split-payload check), forwarded to your provider, and tool calls your policy denies are removed from the response before your framework can dispatch them. Streaming is real: text streams live; tool-call deltas are held, judged complete, and re-emitted only if allowed.

Headers

What comes back

# a denied tool call is gone from choices[].message.tool_calls, and:
"shield": { "allowed": ["get_weather"],
  "blocked": [{ "name": "transfer_funds", "reason": "denied: ..." }] }

# an input blocked before forwarding returns a refusal completion with
# finish_reason "content_filter" and shield.input_blocked; the credit is refunded.

Read, replace, or granularly edit your key's policy. Auth: X-Manage-Key, or your dashboard session. Every write is validated first; a malformed policy is rejected with the full list of problems.

Policy shape

{ "default": "deny",                       # deny = allowlist mode (recommended)
  "allow": ["get_weather"],
  "deny": ["drop_database"],
  "require_approval": ["send_email"],
  "conditions": { "transfer_funds": [{ "param": "amount", "max": 1000 },
                                     { "param": "to", "allowlist": ["acct_A"] }] },
  "scan_params": { "*": true },            # injection-scan string params
  "primitive": { "run_shell": "SHELL_EXEC" } # map to hard OS-level blocks }

PATCH ops

{"op": "allow" | "deny" | "require_approval" | "unallow" | "undeny" |
       "unrequire_approval", "action": "name"}
{"op": "add_condition", "action": "name", "condition": {...}}
{"op": "clear_conditions", "action": "name"}
{"op": "set_default", "value": "allow" | "deny"}

Your key's needs-approval queue. Auth: X-Manage-Key or dashboard session; strictly scoped to your own key (another key's tokens are invisible and unactionable). GET accepts ?status=pending|approved|denied|used. An approved token is redeemable via /guard/check exactly once.

Mint (or rotate) your management token. Auth: dashboard session; requires a verified account. Shown once; the previous token stops working immediately. The dashboard's "Generate management token" button calls exactly this.

Command line client

Everything on this page is available as a zero-dependency CLI. Install it, log in once, and the endpoints become commands.

pip install sovereignshield
ss login --api-key ss_... --manage-token ssm_...

Credentials live in ~/.sovereignshield/config.json (owner-read only), and the environment variables SOVEREIGNSHIELD_API_KEY / SOVEREIGNSHIELD_MANAGE_TOKEN override it for CI.

/billing/packs is public and lists sizes, prices, and per-credit rates. /billing/checkout (session or Bearer key) 303-redirects to Stripe checkout for that pack; the webhook credits your key the moment payment confirms, idempotently.

Unauthenticated liveness check; also reports whether the consensus panel is configured.

{ "status": "ok", "consensus_configured": true }