Shield Rest APIs

Interactive reference for the Highflame Shield REST API. Shield provides real-time AI guardrails — tiered threat detection plus Cedar policy evaluation, at sub-10ms latency.

All SDKs (Python, TypeScript, Rust) are thin clients over these endpoints.

Base URL

Environment
URL

Production

https://shield.api.highflame.ai

Self-hosted

Your deployment URL

Authentication

All requests require a Bearer token in the Authorization header. Service keys (hf_sk_...) are exchanged for short-lived JWTs via your token endpoint — the SDKs handle this automatically.

Header
Description

Authorization

Bearer <jwt>

X-Account-ID

Account identifier (multi-tenant)

X-Project-ID

Project identifier (multi-tenant)

SDK Parity

REST endpoint
Python SDK
TypeScript SDK
Rust SDK
Notes

POST /v1/guard

client.guard.evaluate()

client.guard.evaluate()

client.guard().evaluate()

Full request/response surface

POST /v1/guard/stream

client.guard.stream()

client.guard.stream()

client.guard().stream()

SSE stream support

POST /v1/detect

client.detect.run()

client.detect.run()

client.detect().run()

Detection only

GET /v1/detectors

client.detectors.list()

client.detectors.list()

client.detectors().list()

Detector metadata and health

GET /v1/debug/policies

client.debug.policies()

client.debug.policies()

client.debug().policies()

Loaded Cedar policy metadata

GET /v1/health

Not currently surfaced

Not currently surfaced

Not currently surfaced

Call the REST endpoint directly when you need service health details

Endpoints

POST /v1/guard

Full guard evaluation — runs the tiered detection pipeline (fast → standard → slow), then Cedar policy evaluation. Returns a structured allow/deny decision.

Required fields: content, content_type, action

All request fields:

Field
Type
Required
Description

content

string

yes

Text to evaluate (min 1 char)

content_type

string

yes

"prompt" | "response" | "tool_call" | "file"

action

string

yes

Cedar action: "process_prompt", "call_tool", "read_file", "write_file", "connect_server"

mode

string

no

"enforce" (default), "monitor", or "alert"

session_id

string

no

Session ID for cross-turn state tracking

detectors

string[]

no

Run only specific detectors. Empty = all enabled.

contexts

string[]

no

Reference material for context-aware detection (e.g., original prompt + RAG chunks for hallucination)

metadata

object

no

Caller-provided metadata passed through to detectors

tool

ToolContext

no

Tool call context: { name, is_builtin, arguments, server_id, description }

model

ModelContext

no

LLM context: { provider, model, temperature, tokens_used, max_tokens }

file

FileContext

no

File context: { path, operation, size, mime_type, sensitivity_level, mip_label_id }

mcp

MCPContext

no

MCP context: { server_name, server_url, transport, verified, capabilities }

explain

boolean

no

Include policy explanation, root causes, projected context, and tier info

debug

boolean

no

Include per-detector results, raw context, and Cedar evaluation inputs. Implies explain: true.

optimize

boolean

no

Only run detectors referenced by active Cedar policies. Returns optimization field.

dryrun

boolean

no

With optimize: true, return the detector plan without executing.

early_exit

boolean

no

Stop after the first tier that produces a deny decision (default: true)

Example response:

POST /v1/guard/stream

Same as /v1/guard but streams detector results and the final decision as Server-Sent Events.

Example event stream:

POST /v1/detect

Detection only — runs detectors without Cedar policy evaluation. Useful for observability and monitoring.

Required fields:

  • content

  • content_type

Example response:

GET /v1/detectors

List all available detectors with their status and tier information.

Example response:

GET /v1/health

Service health check.

Example response:

GET /v1/debug/policies

Returns metadata for the Cedar policies currently loaded into Shield for a product namespace.

Optional query parameter:

  • productguardrails

Example response:

Last updated