API Overview

REST API mental model for Sector8 evaluate-before-dispatch decisions and supporting telemetry.

Base URL

https://sdkapi.sector8.ai

Public examples use the production host. Use the endpoint and credentials issued to your environment.

Authentication

All requests require two headers:

x-api-key: YOUR_API_KEY
x-client-id: YOUR_CLIENT_ID

Use the runtime credentials issued to your environment. Do not commit real keys to source control.

Decision contract

POST /api/v1/evaluate is the primary enforcement API. Call it before your runtime dispatches a proposed tool or agent action, then honor the returned decision.

decision	Runtime behavior
ALLOW	May dispatch the proposed action
DENY	Must block the proposed action
Missing / unknown / error / timeout	Fail closed; do not dispatch

Human hold. On the MCP connector path, a borderline action can be held for a human before dispatch. Unresolved holds fail closed. POST /api/v1/evaluate is strictly synchronous and always returns ALLOW or DENY; if that path would need to wait, it returns DENY with REVIEW_REQUIRED_FAIL_CLOSED.

Sector8 returns the verdict. Your application owns enforcing it at the dispatch boundary for actions routed through evaluate.

Coverage applies to proposed actions your runtime routes through this API. Unconnected tools and bypassed dispatch paths are not automatically covered.

Policy model

Sector8 uses versioned policy sets, bound per tenant. The active tenant binding determines which policy version evaluate applies for routed actions in that environment. Baseline safety checks remain active alongside tenant-bound policy.

Agent-scoped policy can add narrower controls for a specific agent or action. Operators can bind, suspend, resume, and review policy state through the control plane; evaluate is the runtime path that returns the enforceable decision.

Decision artifacts commonly include:

Field	Description
decision	ALLOW or DENY
reason_code	Opaque machine-readable reason for support/display — branch on decision
evidence_hash	Fingerprint of the decision evidence for correlation and integrity checks
has_forensic_payload	Indicates whether additional forensic detail is attached
decision_trace_id	Unique audit identifier for this evaluated action
policy_version_id	Non-empty policy identifier (binding hash or runtime version label)

See Evaluate for request and response examples.

Endpoints

Method	Endpoint	Description
GET	/api/health	Gate health and capability state
POST	/api/v1/evaluate	Evaluate a proposed action before dispatch
POST	/api/v1/telemetry	Ingest a completed LLM interaction for analysis

Telemetry records what happened. It is not a substitute for evaluate-before-dispatch.

Reason codes

reason_code is an opaque support/evidence field. Honor decision for dispatch. Do not write exhaustive if reason_code == ... handling — the set is not a closed public enum and the same unsafe action may be blocked by different layers.

Illustrative values you may see:

Code	Trigger
ALLOW_PASS	Proposed action passed policy and admission checks
PRE_FILTER_BLOCK	Blocked by an early pre-filter (common for known-unsafe shell/path patterns)
REVIEW_REQUIRED_FAIL_CLOSED	REST evaluate would have needed to wait; it denied instead
MCP_SHELL_INJECTION_BLOCKED	Shell injection detected in command
SENSITIVE_PATH_BLOCKED	Access to a sensitive file path
MCP_OBFUSCATED_*_BLOCKED	Obfuscated payload decoded and blocked (e.g. MCP_OBFUSCATED_SHELL_INJECTION_BLOCKED)
PARAM_INJECTION_DETECTED	Prompt or parameter injection in arguments
SEMANTIC_THREAT_DETECTED	Semantic similarity to known attack pattern
PRIVATE_IP_BLOCKED	SSRF - target resolves to private IP space
EXTERNAL_DOMAIN_BLOCKED	Domain not on the allowed list
BOLA_VIOLATION	Caller does not own the target object
BFLA_VIOLATION	Caller role is not authorized for this tool
GDPR_DATA_MINIMISATION_VIOLATION	PII detected - data minimisation policy
HIPAA_MINIMUM_NECESSARY_VIOLATION	PHI detected - minimum necessary standard
RATE_LIMIT_EXCEEDED	Call rate exceeded for this session
TOOL_NOT_REGISTERED	Tool has not been registered with the gate
LOCKDOWN_RESTRICTED	Tool is disabled by lockdown capability gate
CAPABILITY_MISSING	Required capability is not available
GUARD_INTERNAL_ERROR	Evaluation failed; treat as fail-closed on the routed path

Exact reason_code and policy_version_id values depend on your active policy, environment, and evaluation path.

Client timeout

For POST /api/v1/evaluate, set an HTTP client timeout of at least 10 seconds (10s recommended default). Fail closed on timeout. Aggressive 1–2s timeouts will block legitimate ALLOW traffic.

Rate limits

The shipped app and MCP server enforce per-session, per-tool rate limiting via an in-memory sliding window. The current injected runtime limit is 8 requests per 10 seconds per session and tool combination. The limiter implementation’s class default is 25 requests per 10 seconds. Requests over the limit return RATE_LIMIT_EXCEEDED.

Contact support to adjust limits for your deployment.