Stihia API (0.1.0)

Performs real-time threat detection for AI systems on the submitted messages.

Use this endpoint when you want a request-scoped threat verdict for an agent turn, workflow step, or model interaction.

One request can include multiple messages and still produces one operation.

Getting started:

1. Create your Stihia account

Sign up at app.stihia.ai using email or social login. The SDK connects to this cloud-hosted platform by default.

2. Set up your organization

Create a new organization — this is the workspace for your projects and team. Then configure email alerts at Your Profile → Organization → Notification Settings to get notified when Stihia detects a threat.

3. Create an API key

Go to Your Profile → Organization → API Keys and click Create API Key. Copy the generated key (starts with sk_). Treat it like a password — never commit it to version control.

4. Run your first threat detection

curl -X POST https://api.stihia.ai/v1/sense \
  -H "Authorization: Bearer $STIHIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "project_key": "my-first-project",
    "user_key": "user-1",
    "process_key": "quickstart",
    "thread_key": "thread-1",
    "run_key": "run-1",
    "sensor": "default",
    "messages": [{"role": "user", "content": "Hello, world!"}]
  }'

5. View your traces

Every sense call is recorded as a trace. Open the Stihia Console Threads page to see a real-time timeline of all detections and drill into individual traces.

6. Need custom sensors?

Default sensors cover general threats. For specialized detection — industry-specific compliance, custom threat categories, or fine-tuned sensitivity — contact support@stihia.ai.

Trace Hierarchy: Each POST /v1/sense call creates one operation inside this hierarchy: project_key → user_key → process_key → thread_key → run_key → operation.

• project_key: the AI product or system being protected
• user_key: the end user behind the interaction
• process_key: the agent, workflow, or app component handling the work
• thread_key: the shared conversation or session context
• run_key: one turn, invocation, or execution inside that thread

Example: a support copilot in my-app serves user customer-42 through the my-ai-agent workflow. All messages in conversation conversation-abc123 share the same thread_key. If the user sends a new message, that new turn should get a new run_key, while project_key, user_key, process_key, and thread_key stay the same. Within one run_key, there can be many operations covering different steps of the process_key's workflow.

The organization is inferred from your API key, so you only send the client-defined keys. Outside chat systems, treat thread_key as the parent workflow or session and run_key as one execution or request inside it.

Sensor Configuration: The sensor field accepts three formats:

1. Type name (string): "default-input" - use a built-in preset
2. Type with overrides (object): {"type": "...", "timeout_ms": 5000} - customize a preset
3. Full config (object): {"key": "...", "classifiers": [...]} - define the full pipeline

Available Types:

• default: Standard threat detection (prompt injection + PII)
• default-input: Input-focused threat detection (prompt injection + PII)
• default-output: Output-focused threat detection (PII + destructive patterns)
• default-input-think: Input detection with reasoning (safeguard + prompt injection + PII)
• coding: Code safety detection (safeguard + PII + destructive patterns)
• empty: No-op passthrough sensor (no classifiers)

Built-in presets cover basic threat-detection scenarios. We offer more powerful and specialized sensors to our business users. If you need better sensors, contact support@stihia.ai.

What you get back:

• One operation record with trace metadata and timing
• The resolved sensor configuration used for the request
• An aggregated threat verdict plus classifier-level signals

How it works:

1. Submit trace keys, messages, and a sensor configuration
2. Classifiers analyze the messages using the sensor's execution mode
3. Signals are aggregated using the specified strategy
4. Returns severity, categories, confidence, and supporting signals