---
title: "Ingest Audit Event"
method: POST
path: "/v1/audit/events"
tags: ["audit"]
---

# Ingest Audit Event

`POST /v1/audit/events`

## Request

- Base URL: `https://api.usekeel.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.usekeel.io/v1/audit/events`
- Auth: none declared

Append a hosted-MCP tool-call event to the org's audit trail.

Idempotent on event_id (retries from the mcp-server's forward path
must not error); returns 202 either way. Only a request whose INSERT
actually inserted mirrors the row to PostHog (``RETURNING``), so a replay
emits nothing; the mirror can never change the response.

## Headers

- `Authorization` string, nullable
- `X-Org-Id` string, nullable

## Request body

- AuditEventIngestRequest: One hosted-MCP tool-call audit event (services/mcp-server/src/audit.py). Identity is NEVER taken from the body: the mcp-server forwards each event with the CALLING principal's own Bearer, and actor/org are derived from that token here — a caller can only ever append to its own org's audit trail.
  - `event_id` string, required
  - `action` string, required
  - `decision` 'ALLOW' | 'DENY', required
  - `tool_name` string, required
  - `client_name` string, nullable
  - `client_version` string, nullable
  - `duration_ms` integer, nullable
  - `error_code` string, nullable
  - `args_hash` string, nullable
  - `ts` number, nullable
  - `target_type` 'mcp_tool' | 'mcp_session'
  - `outcome` OutcomeRef: The object(s) one hosted-MCP tool call produced or touched (Q-1617). A closed set of platform ids, booleans and two closed Keel vocabularies (rule codes, served help-doc names), nothing else: `extra="forbid"` rejects any other key — so an argument KEY (`source`, `name`, `description`) can never ride in — and the id pattern rejects any VALUE that is not an id, so an argument value under an id key is refused too. Written into `metadata_json.outcome`; it is what lets an audit row be joined to `strategy.commits` / `strategy.backtest_runs` by id instead of by timestamp adjacency.
    - `strategy_id` string, nullable
    - `commit_id` string, nullable
    - `backtest_run_id` string, nullable
    - `dry_run` boolean, nullable
    - `is_error` boolean, nullable
    - `validation_ok` boolean, nullable
    - `issue_codes` string[], nullable
    - `doc_ref` string, nullable
  - `tool_class` 'orientation' | 'discovery' | 'build' | 'run' | 'inspect' | 'share' | 'live', nullable
  - `method` string, nullable
  - `fault` 'platform' | 'agent' | 'user_input' | 'designed', nullable

## Response `202`

Successful Response

- unknown

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/usekeel/apis/keel-api.md) · [All operations](https://skmtc.dev/usekeel/apis/keel-api/llms.txt) · [OpenAPI document](https://skmtc.dev/usekeel/apis/keel-api/revisions/3191ca10b0ab?raw)