Skip to main content
POST https://api.prompt-wall.com/v1/events This endpoint is observe-only — there is no enforcement, no mutation, no upstream call. Use it when PromptWall did not run the LLM.

​
Request

​
Required headers

HeaderValue
X-API-KeyYour PromptWall API key (pw_…)
Content-Typeapplication/json
Authorization: Bearer pw_… is also accepted.

​
Body — single event

{
  "request_id":      "abc-123",         // required, ≤ 64 chars, idempotency key
  "mode":            "ingest",          // ingest | proxy | sdk | vendor
  "started_at":      "2026-04-26T10:00:00Z",
  "finished_at":     "2026-04-26T10:00:01Z",
  "provider":        "openai",
  "model":           "gpt-4o-mini",
  "use_case":        "customer_support",
  "team_id":         "support-eu",
  "integration_id":  "sdk:my-app@1.0",
  "end_user_id":     "user-pseudonym",
  "session_id":      "conversation-id",
  "prompt_tokens":   42,
  "completion_tokens": 110,
  "total_tokens":    152,
  "cost_usd":        0.0008,
  "latency_ms":      820,
  "status":          "ok",                  // ok | error | blocked | rewritten | regenerated
  "final_decision":  "pass",                // optional outcome
  "risk_score":      0.05
}

​
Body — batch (up to 500 events)

{
  "events": [
    { "request_id": "abc-1", … },
    { "request_id": "abc-2", … }
  ]
}

​
Field reference

FieldRequiredNotes
request_idyes1–64 chars. Primary key. Re-submitting is idempotent.
modenoingest (default) · proxy · sdk · vendor
started_atnoISO-8601 or epoch seconds. Defaults to “now”.
finished_atnoUsed to compute latency when latency_ms is omitted.
providernoopenai · anthropic · azure · google · …
modelnoFree-form. Useful for cost rollups.
use_case, team_id, integration_id, end_user_id, session_idnoDashboard dimensions.
prompt_tokens, completion_tokens, total_tokensnoTokens. total_tokens is computed if you only send the splits.
cost_usdnoNumeric. If omitted PromptWall doesn’t estimate.
latency_msnoInteger ms. Computed from timestamps if omitted.
statusnook · error · blocked · rewritten · regenerated
final_decisionnoOutcome label for the trace.
risk_scoreno0.0 – 1.0.
policy_hitsnoArray — what policies fired in your own pipeline.

​
Response

​
Single event accepted

{
  "ok":       true,
  "accepted": 1,
  "skipped":  0,
  "rejected": [],
  "total":    1
}

​
Batch with mixed outcomes

{
  "ok":       false,
  "accepted": 498,
  "skipped":  1,
  "rejected": [
    {"index": 12, "request_id": "bad",
     "error": "request_id required (1..64 chars)"}
  ],
  "total":    500
}
HTTP status:
StatusWhen
200All events accepted (or all skipped as duplicates)
207Mixed — some accepted, some rejected
400Whole batch rejected (e.g. all events failed validation)
401Missing / invalid PromptWall API key

​
Idempotency

request_id is the primary key in the canonical traces table. Submitting the same request_id twice never creates two rows — the second call returns skipped: true. This makes batch retries safe.