{"openapi":"3.1.0","info":{"title":"uEngage Audit API","version":"0.1.0","description":"Append-only event log for tenant actions. Producers POST batches of audit events as Bearer JWTs (OAuth2 client_credentials); valid events land on the Kafka audit topic and (downstream) in DynamoDB.","license":{"name":"Proprietary"}},"servers":[{"url":"https://api.platform.uengage.io","description":"Production"}],"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"OAuth2 Bearer JWT, RS256-signed by the auth service. Verify against the JWKS at `/auth/business/jwks.json`. Service-to-service callers mint via `POST /auth/business/oauth/token` with `grant_type=client_credentials`."}},"schemas":{"AuditEvent":{"type":"object","properties":{"event_id":{"type":"string","pattern":"^[0-9A-HJKMNP-TV-Z]{26}$"},"event_type":{"type":"string","pattern":"^[a-z][a-z0-9_]*\\.[a-z][a-z0-9_]*$"},"occurred_at":{"type":"string","format":"date-time"},"tenant":{"type":"object","properties":{"id":{"type":"string","minLength":1},"parent_id":{"type":"string","nullable":true}},"required":["id","parent_id"]},"actor":{"type":"object","properties":{"type":{"type":"string","enum":["user","service","system"]},"id":{"type":"string","minLength":1},"via":{"type":"string","minLength":1}},"required":["type","id","via"]},"resource":{"type":"object","properties":{"type":{"type":"string","minLength":1},"id":{"type":"string","minLength":1}},"required":["type","id"]},"changes":{"type":"object","additionalProperties":{"type":"object","properties":{"before":{"nullable":true},"after":{"nullable":true}}}},"request_id":{"type":"string"}},"required":["event_id","event_type","occurred_at","tenant","actor","resource","changes"]},"AuditBatchResponse":{"type":"object","properties":{"accepted":{"type":"integer","minimum":0,"example":2},"rejected":{"type":"integer","minimum":0,"example":1}},"required":["accepted","rejected"]},"ApiError":{"type":"object","properties":{"error":{"type":"string"},"message":{"type":"string"},"issues":{"type":"array","items":{"nullable":true}}},"required":["error"],"description":"Standard error envelope. `error` is a stable machine-readable code; `message` is a human-readable hint; `issues` (when present) is a Zod validation issue list."},"AuditBatchRequest":{"type":"object","properties":{"events":{"type":"array","items":{"nullable":true},"maxItems":100,"description":"Array of audit events (0..100). Each entry SHOULD conform to the AuditEvent schema (see components.schemas.AuditEvent). Per-event validation: invalid events are silently dropped and counted in the response `rejected` field. Empty arrays succeed with `accepted: 0, rejected: 0`."}},"required":["events"]}},"parameters":{}},"paths":{"/v1/audit/events":{"post":{"tags":["audit"],"summary":"Submit audit events","description":"Append-only event log for tenant actions. Events are validated per-element; invalid events are dropped and counted, valid events are produced to Kafka. Always returns 202 on a syntactically-valid batch (even if every event was dropped).","security":[{"bearer":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditBatchRequest"}}}},"responses":{"202":{"description":"Batch processed (some events may have been dropped)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditBatchResponse"}}}},"400":{"description":"Body parse failed or events is not an array","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"401":{"description":"Auth presented but invalid","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}}}