Audit events

Audit events record every action processed by Arbitex Gateway — completions, blocked requests, authentication events, and policy violations. All events are append-only and immutable; the API is read-only.

Events are enriched with GeoIP metadata, Credential Intelligence (CredInt) fields from the 5-tier DLP pipeline (Tier 4: CredInt), and OCSF class tags. HMAC chain fields used for internal integrity verification are excluded from the customer-facing response.

Base URL: https://api.arbitex.ai

Authentication: Authorization: Bearer <jwt> or Authorization: Bearer arb_live_<api-key>. Results are automatically scoped to the caller’s organisation — cross-tenant access is not possible.

GET /v1/audit/events

Returns org-scoped audit events ordered newest-first (created_at DESC, id DESC).

Query parameters

Parameter	Type	Default	Description
`cursor`	string	—	Opaque pagination cursor from a previous response’s `next_cursor`.
`limit`	integer	`50`	Maximum events per page. Range: 1–500.
`action`	string	—	Exact-match filter on the `action` field (e.g. `chat.completion`, `prompt_blocked`).
`user_id`	string	—	Filter by user UUID. Pass the literal `me` to filter by the authenticated user.
`model_id`	string	—	Filter by model identifier (e.g. `gpt-4o`).
`provider`	string	—	Filter by provider name (e.g. `openai`, `anthropic`).
`source`	string	—	Filter by event origin: `saas` \| `outpost`.
`outpost_id`	UUID	—	Filter by Hybrid Outpost UUID. Only relevant when `source=outpost`.
`credint_hit`	boolean	—	Filter by CredInt (Tier 4) match status: `true` returns only credential-intelligence detections; `false` returns events with no CredInt hit.
`created_after`	ISO 8601	—	Inclusive lower bound on `created_at`.
`created_before`	ISO 8601	—	Inclusive upper bound on `created_at`.
`ocsf_class`	string	—	Filter by OCSF class tag. One of: `api_activity` \| `security_finding` \| `authentication` \| `account_change`.

Cursor-based pagination

Results use opaque cursor pagination. The cursor encodes the last returned event’s position:

base64url(json({"t": "<created_at ISO 8601>", "i": "<event UUID>"}))

Pass next_cursor from a response as cursor on the next request. The underlying index on (tenant_id, created_at) keeps deep pagination O(1). When has_more is false, you have reached the last page.

Request example

curl -s "https://api.arbitex.ai/v1/audit/events?limit=10&action=prompt_blocked&created_after=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Response example (200 OK)

{
  "events": [
    {
      "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
      "action": "prompt_blocked",
      "user_id": "11111111-2222-3333-4444-555555555555",
      "org_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
      "model_id": "gpt-4o",
      "provider": "openai",
      "source": "saas",
      "outpost_id": null,
      "created_at": "2026-03-12T14:32:10Z",
      "src_country_code": "US",
      "src_city": "San Francisco",
      "src_isp": "Cloudflare Inc",
      "credint_hit": false,
      "credint_confidence": null,
      "frequency_bucket": null,
      "ocsf_class_uid": 6003,
      "ocsf_class": "api_activity"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0wMy0xMlQxNDozMjoxMCIsImkiOiJhMWIyYzNkNC1lNWY2LTc4OTAtYWJjZC1lZjEyMzQ1Njc4OTAifQ",
  "has_more": true
}

Response fields

Envelope

Field	Type	Description
`events`	object[]	List of enriched audit event objects. See Event fields below.
`next_cursor`	string \| null	Cursor for the next page; `null` on the last page.
`has_more`	boolean	`true` when additional pages are available.

Event fields

Field	Type	Nullable	Description
`id`	UUID	no	Unique audit log entry identifier.
`action`	string	no	Action identifier (e.g. `chat.completion`, `auth.login_success`, `prompt_blocked`).
`user_id`	UUID	yes	Acting user UUID; `null` for system events.
`org_id`	UUID	yes	Organisation UUID matching the caller’s tenant.
`model_id`	string	yes	Model involved in the action (e.g. `gpt-4o`).
`provider`	string	yes	Provider name (e.g. `openai`).
`source`	string	yes	Event origin: `saas` \| `outpost` \| `null`.
`outpost_id`	UUID	yes	Hybrid Outpost UUID when `source=outpost`; `null` otherwise.
`created_at`	ISO 8601	no	Timestamp of the event.
`src_country_code`	string	yes	ISO 3166-1 alpha-2 country code (GeoIP enrichment).
`src_city`	string	yes	City name from GeoIP enrichment.
`src_isp`	string	yes	Internet service provider from GeoIP enrichment.
`credint_hit`	boolean	yes	`true` if the 5-tier DLP pipeline Tier 4 (CredInt) detected a credential corpus match.
`credint_confidence`	float	yes	NLI confidence score [0, 1] for the CredInt detection; `null` when `credint_hit` is `false`.
`frequency_bucket`	string	yes	Credential hit severity tier assigned by CredInt; `null` when no hit.
`ocsf_class_uid`	integer	yes	OCSF class numeric identifier.
`ocsf_class`	string	yes	OCSF class label string. See OCSF classes below.

OCSF classes

Audit events are normalized to OCSF (Open Cybersecurity Schema Framework) classes where applicable.

`ocsf_class`	`ocsf_class_uid`	Description
`api_activity`	6003	LLM API requests and completions
`security_finding`	2001	DLP or policy violations detected by the 5-tier DLP pipeline
`authentication`	3002	Login and authentication events
`account_change`	3001	User account modifications

Error responses

Status	Body	Description
`400`	`{"detail": "Invalid cursor: ..."}`	Cursor cannot be decoded.
`400`	`{"detail": "Invalid user_id: '...'. Expected a UUID or 'me'."}`	`user_id` is not a valid UUID or the literal `me`.
`403`	`{"detail": "Caller has no organisation — cannot access audit events."}`	Authenticated user has no associated organisation (tenant).

Usage examples

Paginate through all events

# First page
curl -s "https://api.arbitex.ai/v1/audit/events?limit=100" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '{count: (.events | length), cursor: .next_cursor, has_more: .has_more}'

# Subsequent pages — pass next_cursor from the previous response
curl -s "https://api.arbitex.ai/v1/audit/events?limit=100&cursor=$NEXT_CURSOR" \
  -H "Authorization: Bearer $TOKEN"

Filter by CredInt detections (Tier 4)

curl -s "https://api.arbitex.ai/v1/audit/events?credint_hit=true&limit=50" \
  -H "Authorization: Bearer $TOKEN" \
  | jq '.events[] | {action, credint_confidence, frequency_bucket}'

Filter to the authenticated user’s own events

curl -s "https://api.arbitex.ai/v1/audit/events?user_id=me&created_after=2026-03-01T00:00:00Z" \
  -H "Authorization: Bearer $TOKEN"

Collect security findings (Python)

import httpx

resp = httpx.get(
    "https://api.arbitex.ai/v1/audit/events",
    headers={"Authorization": "Bearer <token>"},
    params={"ocsf_class": "security_finding", "limit": 100},
)
data = resp.json()
for event in data["events"]:
    print(f"{event['created_at']}  {event['action']}  model={event['model_id']}")