REST API
Send events directly to SignalVault. No SDK required — use any HTTP client in any language.
Base URL
https://api.signalvault.io
Authentication
All API requests require a Bearer token:
Authorization: Bearer sk_live_your_api_key
POST /v1/events
Ingest an event into SignalVault.
Event types
There are two kinds of events: ones you submit, and ones SignalVault generates internally.
| Type | Submitted by | Description |
|---|---|---|
| ai.request | You | Send before calling your AI provider. SignalVault evaluates rules and returns a decision. |
| ai.response | You | Send after your AI provider responds. SignalVault runs post-flight rules and records cost. |
| ai.error | You | Send if your AI provider call fails (timeout, rate limit, etc.). Logged for observability. |
| agent.tool_call | You | Optional. Send to audit individual tool calls made by an AI agent. |
| policy.violation | SignalVault | Automatically created when a guardrail rule fires. Cannot be submitted directly. |
| budget.exceeded | SignalVault | Automatically created when a cost or token budget is exceeded. Cannot be submitted directly. |
Submitting a policy.violation or budget.exceeded event directly will return a 422 error.
These are generated by SignalVault automatically — you never need to send them yourself.
Request body fields
| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | See event types above |
| request_id | string | For ai.* | Correlates request/response/error events |
| event_id | string | No | Idempotency key — safe to retry with the same value |
| environment | string | No | development, staging, production (default: production) |
| provider | string | No | AI provider: openai, anthropic, mistral, etc. |
| model | string | No | Model name, e.g. gpt-4o |
| metadata | object | No | Arbitrary key/value pairs (user_id, session_id, etc.) |
| payload | object | No | Event-specific data (see below) |
ai.request payload
{"messages": [{"role": "user", "content": "Hello"}], "monitor_mode": false}
ai.response payload
{"output": "Hi there!", "usage": {"prompt_tokens": 10, "completion_tokens": 8}, "cost_usd": 0.0018}
Responses
The response shape depends on the event type:
| Event type | Response |
|---|---|
| ai.request | Decision + violations + redactions. Use decision to decide whether to proceed with the AI call. |
| ai.response | {"event_id": "...", "status": "recorded", "violations": []} — any post-flight violations are included. |
| ai.error, agent.tool_call | {"event_id": "..."} — acknowledgement only. |
{"event_id": "...", "decision": "allow", "violations": [], "redactions": []}
HTTP Status Codes
| Code | Meaning |
|---|---|
| 200 | Success |
| 401 | Invalid or missing API key |
| 422 | Invalid request body, or system-generated event type submitted directly |
| 429 | Rate limited |