Developer field guide

Spectorn API reference

Read the canonical OpenAPI contract for the Spectorn gateway. The page uses the live gateway specification when available and a versioned snapshot otherwise; account and API access remain release-gated.

Spectorn AI Security Gatewayv0.1.0-sprint14Open snapshot JSON

Operation index57

Base URL: https://api.global.spectorn.ai
Authentication: JWT Authorization: Bearer
Spec source: Live (gateway /openapi.json)

delete`/v1/admin/account`

`DELETE /v1/admin/account` — customer self-termination per TOS §7.1.

account

**Distinct from `/v1/admin/keys/:tenant_id`**: that endpoint requires Enterprise tier and acts on a different tenant (admin revoking a customer). This endpoint acts on the caller's OWN account and does NOT require Enterprise tier — any tier may terminate their own subscription. Effect: 1. ALL of the caller's API keys are revoked (soft delete, `active=false`) 2. Future auth attempts with these keys return 401 3. Usage log entry recorded for audit trail 4. Response includes pointers to data export (manual process Sprint 14; automated in Sprint 16) and refund timing per TOS §7.1 Idempotent: calling twice on already-terminated account returns 200 with `revoked_keys: 0` (no error — termination is the goal state).

Request examplecURL

curl -X DELETE \
  https://api.global.spectorn.ai/v1/admin/account \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Account terminated; all keys revoked; data export instructions returned
401: Missing or invalid API key

get`/v1/admin/detection-tuning`

Read the live global detection tuning baseline

account

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/admin/detection-tuning \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

put`/v1/admin/detection-tuning`

Set or clear the live global detection tuning baseline

account

Request examplecURL

curl -X PUT \
  https://api.global.spectorn.ai/v1/admin/detection-tuning \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/admin/detection-tuning/reload`

Reload the global detection tuning baseline from disk

account

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/admin/detection-tuning/reload \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/admin/eligibility/reviews`

List Global Free eligibility reviews for platform triage

eligibility

Parameters

Name	In	Type	Description
`status`	`query`	`string`
`limit`	`query`	`integer`

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/admin/eligibility/reviews \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
403: Required Guard or platform-admin scope is absent
429: Rate limit exceeded
500: Internal error
503: Eligibility classifier, policy, or durable review state is unavailable

post`/v1/admin/eligibility/reviews/{review_id}/decision`

Approve, deny, or revoke a Global Free eligibility review

eligibility

Parameters

Name	In	Type	Description
`review_id`Req	`path`	`string`

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/admin/eligibility/reviews/{review_id}/decision \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
403: Required Guard or platform-admin scope is absent
404: Eligibility review not found
409: Review is not required, in cooldown, or in a conflicting state
413: Request body exceeds 2 KiB
429: Rate limit exceeded
500: Internal error
503: Eligibility classifier, policy, or durable review state is unavailable

get`/v1/admin/keys`

List API keys

account

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/admin/keys \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/admin/keys`

Create an API key

account

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/admin/keys \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

delete`/v1/admin/keys/{tenant_id}`

Revoke all keys for a tenant

account

Request examplecURL

curl -X DELETE \
  https://api.global.spectorn.ai/v1/admin/keys/{tenant_id} \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/admin/tenants/{tenant_id}/model-routes`

Read a tenant's gateway model aliases

account

Parameters

Name	In	Type	Description
`tenant_id`Req	`path`	`string`	Target tenant id

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/admin/tenants/{tenant_id}/model-routes \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

put`/v1/admin/tenants/{tenant_id}/model-routes`

Replace a tenant's gateway model aliases

account

Parameters

Name	In	Type	Description
`tenant_id`Req	`path`	`string`	Target tenant id

Request examplecURL

curl -X PUT \
  https://api.global.spectorn.ai/v1/admin/tenants/{tenant_id}/model-routes \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

put`/v1/admin/tenants/{tenant_id}/policy`

Set or clear a tenant's policy (null body clears to default)

account

Parameters

Name	In	Type	Description
`tenant_id`Req	`path`	`string`	Target tenant id

Request examplecURL

curl -X PUT \
  https://api.global.spectorn.ai/v1/admin/tenants/{tenant_id}/policy \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/admin/tenants/{tenant_id}/scan-config`

Read a tenant's scan mode + policy

account

Parameters

Name	In	Type	Description
`tenant_id`Req	`path`	`string`	Target tenant id

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/admin/tenants/{tenant_id}/scan-config \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

put`/v1/admin/tenants/{tenant_id}/scan-mode`

Set a tenant's scan enforcement mode (enforce/shadow)

account

Parameters

Name	In	Type	Description
`tenant_id`Req	`path`	`string`	Target tenant id

Request examplecURL

curl -X PUT \
  https://api.global.spectorn.ai/v1/admin/tenants/{tenant_id}/scan-mode \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/admin/usage`

Return content-free daily usage across all active tenants

account

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/admin/usage \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/audit/verify`

Verify the global audit log (platform admin only)

verification

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/audit/verify \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
403: Platform admin required for global forensic verification
429: Rate limit exceeded
500: Internal error

post`/v1/billing/checkout`

Create a Stripe Checkout session

account

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/billing/checkout \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/billing/status`

Read the webhook-backed tenant billing entitlement

account

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/billing/status \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/chat/completions`

OpenAI-compatible stateless gateway proxy: scan, route, then forward to the model

gateway

Structured gateway failures use JSON. Provider-origin responses can use the provider's media type, but response bodies are not byte-for-byte passthrough: gateway scanning, masking, model-alias sanitation, billing, and hosted-provider controls may buffer, transform, terminate, withhold, or replace them. Legacy stream:true can return gateway-scanned text/event-stream data or be downgraded to buffered JSON; the default response documents non-enumerated provider statuses.

Parameters

Name	In	Type	Description
`X-Provider-Key`	`header`	`string`	BYOK upstream provider key when no provider is configured in the dashboard
`X-Provider`	`header`	`string`	Route to a configured provider without prefixing the model name
`X-Spectorn-Session`	`header`	`string`	Reserved for the project-scoped chat route. Any present value on this legacy stateless route is rejected with 409 memory_scope_required.
`X-Spectorn-Turn-Id`	`header`	`string`	Reserved for the project-scoped chat route. Any present value on this legacy stateless route is rejected with 409 memory_scope_required.

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/chat/completions \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: Gateway-processed upstream success. Non-streaming JSON may be sanitized, restored, or re-serialized; stream:true can return gateway-scanned SSE that may terminate with a gateway-generated error event; other provider media types can be returned on non-streaming paths.
400: The gateway rejected an invalid request, or the upstream provider returned 400. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
401: The gateway rejected authentication, or an authenticated forwarded request received upstream 401. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
402: Billing balance or output-token allowance requires payment, or the upstream provider returned 402. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
403: Authentication scope, eligibility, prompt policy, output policy, or billing policy refused the request, or the upstream provider returned 403. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
408: The gateway request timed out, or the upstream provider returned 408. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
409: Any present X-Spectorn-Session or X-Spectorn-Turn-Id value is rejected with memory_scope_required, or an authenticated forwarded request received upstream 409. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
413: HTTP body or prompt exceeded its bound, or the upstream provider returned 413. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
429: The gateway or upstream provider rate-limited the request. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
500: The gateway failed internally, or the upstream provider returned 500. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
502: Upstream resolution, transport, or response-size failure, or the upstream provider returned 502. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
503: Scan, billing, or eligibility dependency unavailable, or the upstream provider returned 503. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
504: The upstream provider returned 504 Gateway Timeout. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
default: A non-enumerated response status selected from the upstream provider. Its media type and JSON shape are provider-defined; gateway controls may transform, terminate, withhold, or replace the payload

get`/v1/dashboard-template`

Grafana dashboard template

verification

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/dashboard-template \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
500: Internal error

post`/v1/dispute/file`

POST /v1/dispute/file — file a customer dispute per Constitution §6 + TOS §7.3.

account

Authenticated: caller's `tenant_id` is extracted from API key and stamped onto the dispute record (cannot be spoofed; cross-tenant defence applies). Body (JSON): ```json { "subject": "string, one-line summary", "body": "string, full text (markdown OK)", "principle_reference": "string (optional, e.g. 'Принцип 6')" } ``` Response (HTTP 202 Accepted): ```json { "dispute_id": "D-<16-hex>", "status": "received", "received_at_utc": "...", "expected_response_within_business_days": 5, "note": "ops staff will respond out-of-band by email; check tenant email" } ``` Storage: append-only `data/disputes.jsonl`. Sprint 16 will add automated forwarding (Telegram/email webhooks) — until then ops manually monitors the file and responds out-of-band. Cost: 1 token (filed under filing_dispute usage label).

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/dispute/file \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

202: Dispute filed, in-memory ID assigned, ops staff notified out-of-band
400: Malformed request (empty subject/body or oversized)
401: Missing or invalid API key
500: Internal error (failed to persist dispute)

get`/v1/dispute/list`

GET /v1/dispute/list — list the authenticated tenant's OWN disputes.

account

Reads the append-only `data/disputes.jsonl` and returns only records whose `tenant_id` matches the caller (cross-tenant isolation enforced inside `list_by_tenant`). Complements `POST /v1/dispute/file` so a customer can replay the full dispute history they filed (Constitution §6 audit trail) — previously disputes could be written but never read back.

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/dispute/list \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: The caller's own disputes in append (chronological) order
401: Missing or invalid API key
500: Internal error (failed to read dispute log)

post`/v1/eligibility/reviews`

Submit a structured Global Free eligibility review

eligibility

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/eligibility/reviews \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
202: Eligibility review accepted
400: Bad request
401: Missing or invalid API key
403: Required Guard or platform-admin scope is absent
409: Review is not required, in cooldown, or in a conflicting state
413: Request body exceeds 2 KiB
429: Rate limit exceeded
500: Internal error
503: Eligibility classifier, policy, or durable review state is unavailable

get`/v1/eligibility/reviews/current`

Read the caller tenant's current Global Free eligibility review

eligibility

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/eligibility/reviews/current \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
403: Required Guard or platform-admin scope is absent
429: Rate limit exceeded
500: Internal error
503: Eligibility classifier, policy, or durable review state is unavailable

get`/v1/engines`

GET /v1/engines — return the canonical 101 engine names.

scan

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/engines \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Canonical engine inventory with explicit text-scan availability
401: Missing or invalid API key

get`/v1/explain/{verdict_id}`

Fetch a causal chain for a verdict

verification

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/explain/{verdict_id} \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: A vdt_ id: the stored verdict at the caller's disclosure level. Any other id: the memory subsystem's causal chain.
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/gateway/capabilities`

Return tenant gateway capabilities and available model aliases

gateway

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/gateway/capabilities \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/health`

verification

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/health \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Server is alive (process responding)

post`/v1/logout`

Logout the current browser session

account

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/logout \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
500: Internal error

delete`/v1/memory/all`

Delete all tenant memory

memory

Request examplecURL

curl -X DELETE \
  https://api.global.spectorn.ai/v1/memory/all \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/memory/export`

Export tenant memory

memory

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/memory/export \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/memory/projects/{project_id}/chat/completions`

OpenAI-compatible gateway proxy with exact project/session recall and store

gateway

Structured gateway failures use JSON. Scoped stream:true is always buffered and disclosed through X-Spectorn-Stream-Downgraded. The gateway reserves prepaid billing before walking the provider chain. A durable cross-process claim is acquired only after a sendable provider request has been built, then its owner begins execution immediately before the first provider dispatch. Thus a billing refusal or wholly unsendable provider chain creates no durable claim state. A configured fallback chain can contact multiple providers, so the guarantee is at-most-one dispatch chain, not provider exactly-once. CLAIMED leases may expire before dispatch; EXECUTING is never stolen, becomes durably UNCERTAIN after its deadline, and both UNCERTAIN and COMPLETED fail closed. Exact response bytes are not persisted for replay, so completed retries return memory_turn_replay_unavailable without a new provider call. Reusing the turn id with a different canonical request returns memory_turn_conflict. Provider-origin errors can use the provider's media type, while gateway controls may transform, withhold, or replace their payloads. Exact error responses allow gateway JSON and arbitrary upstream media; the default response documents non-enumerated provider statuses.

Parameters

Name	In	Type	Description
`project_id`Req	`path`	`string`
`X-Spectorn-Session`Req	`header`	`string`	Exact session boundary inside the path project
`X-Spectorn-Turn-Id`Req	`header`	`string`	Caller occurrence token for one logical turn. Reuse it only with the same canonical caller request; use a new value for every new turn. A durable cross-process claim permits at most one provider dispatch chain for the canonical project/session/turn/request identity. The winning fallback chain may contact multiple providers, so this is not provider exactly-once. Because exact response bytes are not durably replayed, a retry after dispatch began, became uncertain, or completed returns a typed 409 and never starts a fresh provider chain.
`X-Provider-Key`	`header`	`string`
`X-Provider`	`header`	`string`

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/memory/projects/{project_id}/chat/completions \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: Buffered upstream success accepted for exact recall/store semantics and committed as the durable completed turn. Matching retries are not replayed and do not launch a fresh provider chain. The JSON body may be sanitized, restored, or re-serialized, and the provider-declared media type can be retained.
400: Invalid project id or unrepresentable chat request (memory_user_turn_required or memory_request_not_storable), or the upstream provider returned 400. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
401: The gateway rejected authentication, or an authenticated forwarded request received upstream 401. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
402: Billing balance or output-token allowance requires payment, or the upstream provider returned 402. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
403: Authentication scope, eligibility, prompt policy, output policy, or billing policy refused the request, or the upstream provider returned 403. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
408: The scoped operation timed out, or the upstream provider returned 408. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
409: Missing or malformed exact session/turn scope (memory_scope_required or memory_turn_id_required); a conflicting request_ref (memory_turn_conflict); a live claim or execution (memory_turn_claimed or memory_turn_execution_in_progress); a stale execution with an unknowable provider outcome (memory_turn_outcome_uncertain); a completed turn whose exact response cannot be replayed (memory_turn_replay_unavailable); or the upstream provider returned 409. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
413: HTTP body, prompt, or prompt plus recalled memory exceeded its bound, or the upstream provider returned 413. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
423: Session memory operation blocked by runtime self-defense mode, or the upstream provider returned 423. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
429: The gateway or upstream provider rate-limited the request. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
500: The gateway failed internally, or the upstream provider returned 500. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
502: Memory backend, upstream resolution, transport, or response-size failure, or the upstream provider returned 502. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
503: Session memory, scan, billing, or eligibility dependency unavailable, or the upstream provider returned 503. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
504: The upstream provider returned 504 Gateway Timeout. Structured gateway failures use application/json; provider-origin media and JSON shapes are provider-defined, and transport fallbacks can use any media type. Gateway controls may transform, terminate, withhold, or replace the payload
default: A non-enumerated response status selected from the upstream provider. Its media type and JSON shape are provider-defined; gateway controls may transform, terminate, withhold, or replace the payload

post`/v1/memory/projects/{project_id}/export`

Export one explicit memory project

memory

Parameters

Name	In	Type	Description
`project_id`Req	`path`	`string`	Explicit project boundary. The legacy default project is available only through /v1/memory/store, /search, /stats, and /export.

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/memory/projects/{project_id}/export \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Project-scoped memory export
400: Invalid project identifier or scoped request arguments
401: Missing or invalid API key
403: Authenticated request refused by API-key scope, eligibility, or browser CSRF controls
408: Request timed out before the scoped operation completed
413: Configured memory export bound exceeded
423: Runtime self-defense mode blocked the operation
429: Rate limit exceeded
500: Internal error
502: Memory backend did not confirm the requested project scope
503: Memory or scan backend unavailable
504: Memory backend timed out

get`/v1/memory/projects/{project_id}/search`

Search one explicit memory project

memory

Parameters

Name	In	Type	Description
`project_id`Req	`path`	`string`	Explicit project boundary. The legacy default project is available only through /v1/memory/store, /search, /stats, and /export.
`q`Req	`query`	`string`
`limit`	`query`	`integer`
`mode`	`query`	`string`

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/memory/projects/{project_id}/search \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Project-scoped facts
400: Invalid project identifier or scoped request arguments
401: Missing or invalid API key
403: Authenticated request refused by API-key scope or eligibility controls, or protection policy blocked the search query
408: Request timed out before the scoped operation completed
413: A stored fact identity, stored fact payload, or aggregate search scope exceeds the bounded search limit
423: Runtime self-defense mode blocked the operation
429: Rate limit exceeded
500: Internal error
502: Memory backend did not confirm the requested project scope
503: Memory or scan backend unavailable
504: Memory backend timed out

get`/v1/memory/projects/{project_id}/stats`

Summarize one explicit memory project

memory

Parameters

Name	In	Type	Description
`project_id`Req	`path`	`string`	Explicit project boundary. The legacy default project is available only through /v1/memory/store, /search, /stats, and /export.

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/memory/projects/{project_id}/stats \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Project-scoped memory statistics
400: Invalid project identifier or scoped request arguments
401: Missing or invalid API key
403: Authenticated request refused by API-key scope, eligibility, or browser CSRF controls
408: Request timed out before the scoped operation completed
413: A stored stats domain, aggregate domain scope, or domain count exceeds the bounded statistics limit
423: Runtime self-defense mode blocked the operation
429: Rate limit exceeded or another bounded memory response is active for this tenant
500: Internal error
502: Memory backend did not confirm the requested project scope
503: Memory backend or bounded memory-response capacity unavailable
504: Memory backend timed out

post`/v1/memory/projects/{project_id}/store`

Store a fact in one explicit memory project

memory

Parameters

Name	In	Type	Description
`project_id`Req	`path`	`string`	Explicit project boundary. The legacy default project is available only through /v1/memory/store, /search, /stats, and /export.

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/memory/projects/{project_id}/store \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: Exact project-scoped fact replayed without mutation
201: Project-scoped fact stored
400: Invalid project identifier or scoped request arguments
401: Missing or invalid API key
403: Authenticated request refused by API-key scope, eligibility, or browser CSRF controls, or protection policy blocked caller content
408: Request timed out before the scoped operation completed
409: Exact fact identity conflicts with a different live fact, or the project is not writable
413: Configured memory store size bound exceeded
423: Runtime self-defense mode blocked the operation
429: Rate limit exceeded
500: Internal error
502: Memory backend did not confirm the requested project scope
503: Memory or scan backend unavailable
504: Memory backend timed out

get`/v1/memory/search`

Search tenant memory

memory

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/memory/search \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/memory/store`

Store a tenant memory fact

memory

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/memory/store \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/metrics`

Prometheus metrics

verification

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/metrics \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
500: Internal error

get`/v1/metrics/aggregate`

Privacy-safe aggregate Prometheus metrics

verification

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/metrics/aggregate \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
500: Internal error

get`/v1/model-routes`

Read the caller tenant's gateway model aliases

gateway

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/model-routes \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

put`/v1/model-routes`

Replace the caller tenant's gateway model aliases

gateway

Request examplecURL

curl -X PUT \
  https://api.global.spectorn.ai/v1/model-routes \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/models`

List customer-visible gateway model aliases

gateway

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/models \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/observe`

Structured observation: stateless engines shared, stateful engines owned by the tenant

scan

Runs one structured engine on one versioned typed observation. The engines GET /v1/engines lists as structured_observe_stateless_engines compute their answer from the observation alone. The engines it lists as structured_observe_tenant_engines keep history between calls in a registry owned by the authenticated tenant: tenant_id in the observation is replaced by the authenticated one, the history lives in the server process only (a restart, deployment or rollback starts it empty), and it is dropped when the tenant's data is erased. Engines listed in structured_observe_unavailable are not served. The result reports state_scope and carries no customer content.

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/observe \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: The engine's typed result (spectorn-typed-observation/v1) with state_scope (none or tenant_process_memory) and channel_disclosed
400: Malformed body, missing or unknown engine_name, or an observation the typed admission refused
401: Missing or invalid API key
403: Authenticated request refused by scope, eligibility, or browser CSRF controls
408: Request timed out
429: Rate limit exceeded
500: Transport, middleware or engine failure
503: The named engine is not served (privileged, or stateful observation is off on this server), every tenant registry slot is taken, the tenant's registry could not be built, the engine pool is saturated, or eligibility middleware failed closed.

get`/v1/public/channel-matrix`

GET /v1/public/channel-matrix — Constitution Принцип 12 verification.

constitution

Returns the full Spectorn model catalog with channel classes, upstream providers, license/agreement references, and availability status, wrapped in the review-13.06 honest envelope (`attestation::build_envelope`): ed25519-SIGNED when the operator configured `SPECTORN_ATTESTATION_SIGNING_KEY`, otherwise an integrity CHECKSUM labelled as exactly that (a bare hash proves nothing about tampering — the old envelope's "untampered in transit" claim was false and violated Принцип 4). Lookup order for the underlying matrix: 1. `data/channel_matrix.json` (relative to server working directory) 2. `EMBEDDED_CHANNEL_MATRIX` (compile-time default) **Unauthenticated** — this is a public attestation endpoint per Constitution §12 verification method. The same JSON is shown to auditors, customers, and search engines.

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/public/channel-matrix \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Channel-matrix envelope: ed25519-signed when the server has an attestation key, blake3 integrity-checksum otherwise
500: Internal error (malformed on-disk matrix)

get`/v1/public/firewall-attestation`

GET /v1/public/firewall-attestation — Constitution Принцип 11 verification.

constitution

Returns the latest output of `infra/scripts/verify_firewall.sh` wrapped in a signed envelope. Operators are expected to refresh the underlying `data/firewall_attestation.json` via a cron job (typical cadence: hourly). The handler does NOT shell out to the verifier itself — that would be a security risk (arbitrary script execution per request) and a performance hit. Instead the cron produces a fresh attestation file and this endpoint serves whatever is on disk. **Staleness handling**: the envelope includes both `data.last_run_utc` (from the verifier) and `served_at` (from this handler). Customers and auditors compute the delta and decide whether the attestation is fresh enough for their use. Default staleness threshold per Constitution §11 breach-protocol guidance: >= 24 hours or future timestamp = `unknown_state`. **404 vs 500**: if the file doesn't exist yet (cron hasn't run), return 503 with a body explaining why — this more truthful than a fabricated "pass" response that would be a Принцип 12 / Принцип 4 violation. **Unauthenticated** — public verification endpoint per Constitution §11.

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/public/firewall-attestation \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: Signed firewall-attestation envelope with freshness label
500: Internal error (malformed attestation file)
503: Attestation file not yet produced — the spectorn-firewall-attestation timer publishes it

get`/v1/public/models`

List the public gateway model catalog preview

gateway

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/public/models \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
429: Public model catalog is busy
500: Internal error

post`/v1/scan`

Analyze a prompt with one engine or the full registry

scan

Answers at the caller's disclosure level (schema spectorn.verdict_projection.v1): a key reads the policy decision, a risk band derived from it, coarse classes and findings; the engines' score, rules and offsets reach only a key with the diagnostics grant.

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/scan \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: Verdict at the caller's disclosure level
Illustrative response
{ "schema": "spectorn.verdict_projection.v1", "disclosure": "remediation", "verdict_id": "vdt_…", "decision": "block", "mode": "enforce", "enforced": true, "risk_band": "high", "classes": ["prompt_attack"], "findings": [ { "finding_id": "fnd_…", "category": "prompt_attack", "reason_code": "instruction_override", "suggested_action": "remove_embedded_instructions" } ], "detected": true, "would_block": true, "allowed": false, "latency_ms": 2 }
When the engines refuse to analyse a text, /v1/scan answers 403 with the code analysis_refused (reason match_budget_exceeded, evaluation_status refused_excess_evidence) instead of a verdict: the text was not checked. Treat that answer as a block, never as an allow, and do not retry the same text. The proxy refuses such a text with a 403 that carries the same code and does not forward it.
400: Bad request
401: Missing or invalid API key
403: Analysis refused: the engines found more matches than they bound, so the text was not checked. Treat this answer as a block, never as an allow, and do not retry the same text.
429: Rate limit exceeded
500: Internal error

post`/v1/scan/artifact`

Scan a model artifact byte stream

scan

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/scan/artifact \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
403: Analysis refused: the engines found more matches than they bound, so the text was not checked. Treat this answer as a block, never as an allow, and do not retry the same text.
429: Rate limit exceeded
500: Internal error

post`/v1/scan/target`

Analyze exactly one declared user or assistant target

scan

Validates the complete role context, scans only the declared final target, and returns a contract/role attestation. Request content is not retained when X-Spectorn-No-Retention: true is supplied.

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/scan/target \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: Target scan verdict with context attestation
400: Bad request
401: Missing or invalid API key
403: Analysis refused: the engines found more matches than they bound, so the text was not checked. Treat this answer as a block, never as an allow, and do not retry the same text.
429: Rate limit exceeded
500: Internal error

get`/v1/security/self-defense`

Return runtime self-defense mode and recent security events

security

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/security/self-defense \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/security/self-defense/recover`

Recover runtime self-defense mode after operator review

security

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/security/self-defense/recover \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": "example input"}'

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/signup`

Request a signup magic link

account

Unavailable on hosted Spectorn: the RU and Global edges answer 426 and the request never reaches the server.

Closed on hosted Spectorn: the RU and Global edges answer 426 before the request reaches the server. A self-hosted server serves it only when SPECTORN_REGISTRATION_ENABLED is true, SPECTORN_LEGAL_PUBLICATION_STATUS is published and SPECTORN_API_SIGNUP_ENABLED is true; otherwise it answers 403.

Responses

200: OK
400: Bad request
403: API signup is closed on this server: registration, legal publication or SPECTORN_API_SIGNUP_ENABLED is off
426: Hosted Spectorn edge refused the request before it reached the server
500: Internal error

get`/v1/signup/verify`

Render signup magic-link confirmation

account

Unavailable on hosted Spectorn: the RU and Global edges answer 426 and the request never reaches the server.

Parameters

Name	In	Type	Description
`token`Req	`query`	`string`	One-time signup magic-link token

Responses

200: OK
400: Bad request
403: API signup is closed on this server: registration, legal publication or SPECTORN_API_SIGNUP_ENABLED is off
426: Hosted Spectorn edge refused the request before it reached the server
500: Internal error

post`/v1/signup/verify`

Consume a signup magic-link token

account

Unavailable on hosted Spectorn: the RU and Global edges answer 426 and the request never reaches the server.

Parameters

Name	In	Type	Description
`token`Req	`query`	`string`	One-time signup magic-link token

Responses

200: OK
400: Bad request
403: API signup is closed on this server: registration, legal publication or SPECTORN_API_SIGNUP_ENABLED is off
426: Hosted Spectorn edge refused the request before it reached the server
500: Internal error

get`/v1/usage`

Return current tenant usage summary

account

Request examplecURL

curl -X GET \
  https://api.global.spectorn.ai/v1/usage \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

post`/v1/webhooks/stripe`

Receive Stripe webhook events

billing

Parameters

Name	In	Type	Description
`Stripe-Signature`Req	`header`	`string`	Stripe webhook signature header

Request examplecURL

curl -X POST \
  https://api.global.spectorn.ai/v1/webhooks/stripe \
  -H "Authorization: Bearer $SPECTORN_API_KEY" \
  -H "Content-Type: application/json"

Responses

200: OK
400: Bad request
500: Internal error

Description

Spectorn — AI security verdict service (Track 1) + hybrid LLM gateway (Tracks 2/3/4 launching Sprint 15-17). Constitution v0.2 (12 falsifiable principles, two non-amendable). Per Constitution Принцип 12, every response includes a `channel_disclosed` field; responses can be independently verified using the open-source `spct-verify-channel` CLI. See SPECTORN_CONSTITUTION_DRAFT.md and SPECTORN_TOS_DRAFT.md в the source repository.

delete/v1/admin/account

Responses

get/v1/admin/detection-tuning

Responses

put/v1/admin/detection-tuning

Responses

post/v1/admin/detection-tuning/reload

Responses

get/v1/admin/eligibility/reviews

Parameters

Responses

post/v1/admin/eligibility/reviews/{review_id}/decision

Parameters

Responses

get/v1/admin/keys

Responses

post/v1/admin/keys

Responses

delete/v1/admin/keys/{tenant_id}

Responses

get/v1/admin/tenants/{tenant_id}/model-routes

Parameters

Responses

put/v1/admin/tenants/{tenant_id}/model-routes

Parameters

Responses

put/v1/admin/tenants/{tenant_id}/policy

Parameters

Responses

get/v1/admin/tenants/{tenant_id}/scan-config

Parameters

Responses

put/v1/admin/tenants/{tenant_id}/scan-mode

Parameters

Responses

get/v1/admin/usage

Responses

get/v1/audit/verify

Responses

post/v1/billing/checkout

Responses

get/v1/billing/status

Responses

post/v1/chat/completions

Parameters

Responses

get/v1/dashboard-template

Responses

post/v1/dispute/file

Responses

get/v1/dispute/list

Responses

post/v1/eligibility/reviews

Responses

get/v1/eligibility/reviews/current

Responses

get/v1/engines

Responses

get/v1/explain/{verdict_id}

Responses

get/v1/gateway/capabilities

Responses

get/v1/health

Responses

post/v1/logout

Responses

delete/v1/memory/all

Responses

post/v1/memory/export

Responses

post/v1/memory/projects/{project_id}/chat/completions

Parameters

Responses

post/v1/memory/projects/{project_id}/export

Parameters

Responses

get/v1/memory/projects/{project_id}/search

Parameters

Responses

get/v1/memory/projects/{project_id}/stats

delete`/v1/admin/account`

get`/v1/admin/detection-tuning`

put`/v1/admin/detection-tuning`

post`/v1/admin/detection-tuning/reload`

get`/v1/admin/eligibility/reviews`

post`/v1/admin/eligibility/reviews/{review_id}/decision`

get`/v1/admin/keys`

post`/v1/admin/keys`

delete`/v1/admin/keys/{tenant_id}`

get`/v1/admin/tenants/{tenant_id}/model-routes`

put`/v1/admin/tenants/{tenant_id}/model-routes`

put`/v1/admin/tenants/{tenant_id}/policy`

get`/v1/admin/tenants/{tenant_id}/scan-config`

put`/v1/admin/tenants/{tenant_id}/scan-mode`

get`/v1/admin/usage`

get`/v1/audit/verify`

post`/v1/billing/checkout`

get`/v1/billing/status`

post`/v1/chat/completions`

get`/v1/dashboard-template`

post`/v1/dispute/file`

get`/v1/dispute/list`

post`/v1/eligibility/reviews`

get`/v1/eligibility/reviews/current`

get`/v1/engines`

get`/v1/explain/{verdict_id}`

get`/v1/gateway/capabilities`

get`/v1/health`

post`/v1/logout`

delete`/v1/memory/all`

post`/v1/memory/export`

post`/v1/memory/projects/{project_id}/chat/completions`

post`/v1/memory/projects/{project_id}/export`

get`/v1/memory/projects/{project_id}/search`

get`/v1/memory/projects/{project_id}/stats`

post`/v1/memory/projects/{project_id}/store`

get`/v1/memory/search`

post`/v1/memory/store`

get`/v1/metrics`

get`/v1/metrics/aggregate`

get`/v1/model-routes`

put`/v1/model-routes`

get`/v1/models`

post`/v1/observe`

get`/v1/public/channel-matrix`

get`/v1/public/firewall-attestation`

get`/v1/public/models`

post`/v1/scan`

post`/v1/scan/artifact`

post`/v1/scan/target`

get`/v1/security/self-defense`

post`/v1/security/self-defense/recover`

post`/v1/signup`

get`/v1/signup/verify`

post`/v1/signup/verify`

get`/v1/usage`

post`/v1/webhooks/stripe`