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.

Request body fields

ai.request payload

{"messages": [{"role": "user", "content": "Hello"}]}

ai.response payload

{"output": "Hi there!", "usage": {"prompt_tokens": 10, "completion_tokens": 8}, "cost_usd": 0.0018}

An ai.response must carry the request_id of an ai.request you already sent, or it is rejected with 404. Its environment, provider and model are inherited from that request, so you do not need to repeat them.

cost_usd is optional: when you leave it out, SignalVault computes a cost from usage and the model name. Usage may use either OpenAI's prompt_tokens and completion_tokens or Anthropic's input_tokens and output_tokens; both are read for costing and for the daily token budget. Anthropic's prompt cache counts, cache_read_input_tokens and cache_creation_input_tokens, are priced at Anthropic's cache prices. Cache writes are priced at the 5-minute rate unless cache_creation says how many went to the 1-hour cache.

A model SignalVault has no list price for records no cost, rather than a guess: the request shows that the cost is not available, and the Costs page says how many responses its totals exclude. Send cost_usd yourself for an exact figure — always worth doing if you have committed-use pricing, or route through Azure, Bedrock or Vertex, where your rate differs from list price anyway.

agent.tool_call payload

Audit a tool call your agent made. tool_name and duration_ms are required; a payload missing either returns 422 with {"error": {"type": "invalid_payload"}}. Set request_id to tie the call to its parent ai.request, or leave it out for a call with no single parent turn.

{"type": "agent.tool_call", "request_id": "...", "payload": {"tool_name": "fetch_weather", "tool_input": {"city": "Stockholm"}, "tool_output": {"temp_c": 7}, "duration_ms": 142}}

metadata example

Use metadata to attach arbitrary key/value pairs — user IDs, session IDs, feature flags — that appear in the dashboard and in the JSON export:

{"type": "ai.request", "metadata": {"user_id": "u_abc123", "session_id": "sess_xyz", "feature": "chat-v2"}, "payload": {"messages": [{"role": "user", "content": "..."}]}}

Put prompts in the keys SignalVault reads

Responses

The response shape depends on the event type:

{"event_id": "...", "decision": "redact", "violations": [...], "redactions": [{"type": "contains_pii", "count": 2}]}

HTTP Status Codes

Telling the 429s apart

The trial limit returns an object; the rate limits return a bare string, and a request recorded over the rule-check limit adds recorded: true. Check that error is an object before reading error.type:

// Trial limit — HTTP 429
{"error": {"type": "trial_limit_exceeded", "code": "trial_limit_exceeded",
           "message": "Your SignalVault trial has ended. Choose a plan to continue: ...",
           "upgrade_url": "https://signalvault.io/account/billing"}}

// Over the rule-check limit — HTTP 429, with a Retry-After header in seconds.
// The ai.request is recorded, unchecked; do not send it again.
{"error": "rate_limited", "reason": "pre_flight_rate_limited", "recorded": true,
 "event_id": "...", "decision": "unchecked"}

// Over an event ceiling — HTTP 429, with a Retry-After header in seconds.
// Nothing was stored; send the same event again after the delay.
{"error": "rate_limited"}

A lapsed subscription returns 402, not 429, and its body is flat: {"error": "subscription_inactive", "message": "…"}.

Rate limits

Over the rule-check limit, an ai.request is recorded with the decision unchecked and the reason pre_flight_rate_limited: no rule runs, and only its metadata is stored, never the prompt, since nothing could be redacted from it. The answer is a 429 with recorded: true. Don't send that request again; if you forward it to the provider anyway, send its ai.response as usual, and it is linked to the recorded request. Add "fail_mode": "open" or "closed" to the request's payload and the record also says whether the request was forwarded unchecked.

When a limit is exceeded, SignalVault returns 429 with a Retry-After header in seconds, and retrying after that delay is the right response, except for a request already recorded unchecked. The trial-limit 429 carries no Retry-After, because waiting will not clear it — retrying that one is pointless until the app is subscribed.