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: Versioned snapshot

delete`/v1/admin/account`

Self-terminate account; revoke all keys (TOS §7.1)

account

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: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

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

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
429: Rate limit exceeded
500: Internal error

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
429: Rate limit exceeded
500: Internal error

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

Parameters

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

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 audit log

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
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`

File a dispute (TOS §7.3)

account

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

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

get`/v1/dispute/list`

List the authenticated tenant's own disputes

account

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: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

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
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

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
429: Rate limit exceeded
500: Internal error

get`/v1/engines`

Full canonical list of available engines

verification

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: OK
400: Bad request
401: Missing or invalid API key
429: Rate limit exceeded
500: Internal error

get`/v1/explain/{verdict_id}`

Fetch a causal chain for a verdict

verification

Parameters

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

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: OK
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`

Liveness probe (process responding)

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: OK
400: Bad request
500: Internal error

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
500: Internal error
502: Memory backend did not confirm the requested project scope
503: Memory or scan backend 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 unavailable pending tenant-state isolation

scan

Unavailable: the server keeps this operation switched off and refuses every call.

Fail-closed until authenticated per-tenant state isolation and cross-tenant tests are complete. The request body is not parsed or dispatched if the request reaches the disabled handler. Transport, authentication, eligibility, and rate-limit middleware can reject it first.

Responses

400: Client protocol negotiation rejected the request before authentication
401: Missing or invalid API key
403: Authenticated request refused by scope, eligibility, or browser CSRF controls
408: Request timed out before the disabled handler completed
429: Rate limit exceeded
500: Transport or middleware failure
503: Structured observation is disabled. Authentication eligibility middleware can also fail closed with 503 before the handler is reached.

get`/v1/public/channel-matrix`

Signed channel-matrix envelope (Constitution §12)

verification

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: OK
400: Bad request
500: Internal error

get`/v1/public/firewall-attestation`

Signed firewall-attestation envelope (Constitution §11)

verification

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: OK
400: Bad request
500: Internal error

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
500: Internal error

post`/v1/scan`

Analyze a prompt with one engine or the full registry

scan

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: OK
Illustrative response
{ "confidence": 0.99, "action": "BLOCK", "flags": ["PROMPT_INJECTION"], "latency_ms": 1.25 }
400: Bad request
401: Missing or invalid API key
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
429: Rate limit exceeded
500: Internal error

post`/v1/scan/target`

Analyze exactly one declared user or assistant target

scan

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: OK
400: Bad request
401: Missing or invalid API key
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. Self-hosted deployments decide availability at their own edge.

Responses

200: OK
400: Bad request
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.

Closed on hosted Spectorn: the RU and Global edges answer 426 before the request reaches the server. Self-hosted deployments decide availability at their own edge.

Responses

200: OK
400: Bad request
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.

Closed on hosted Spectorn: the RU and Global edges answer 426 before the request reaches the server. Self-hosted deployments decide availability at their own edge.

Responses

200: OK
400: Bad request
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

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

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}

Parameters

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}

Parameters

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

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`