# Audit

## List Audit Events

> List audit events with filters and pagination.\
> \
> Permissions: admin, owner

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AuditEventsListResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/src__routes__audit__AuditEventResponse"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["events","total","limit","offset","has_more"],"title":"AuditEventsListResponse"},"src__routes__audit__AuditEventResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"timestamp":{"type":"string","title":"Timestamp"},"service":{"type":"string","title":"Service"},"actor_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Entity Id"},"actor_credential_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Credential Id"},"action":{"type":"string","title":"Action"},"resource_type":{"type":"string","title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","default":false}},"type":"object","required":["id","workspace_id","timestamp","service","action","resource_type"],"title":"AuditEventResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/audit":{"get":{"tags":["Audit"],"summary":"List Audit Events","description":"List audit events with filters and pagination.\n\nPermissions: admin, owner","operationId":"list-audit-events","parameters":[{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by service name","title":"Service"},"description":"Filter by service name"},{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by action type","title":"Action"},"description":"Filter by action type"},{"name":"actor_entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by actor entity","title":"Actor Entity Id"},"description":"Filter by actor entity"},{"name":"resource_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Filter by resource type","title":"Resource Type"},"description":"Filter by resource type"},{"name":"resource_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by specific resource","title":"Resource Id"},"description":"Filter by specific resource"},{"name":"phi_only","in":"query","required":false,"schema":{"type":"boolean","description":"Only PHI access events","default":false,"title":"Phi Only"},"description":"Only PHI access events"},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Start of date range","title":"Date From"},"description":"Start of date range"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of date range","title":"Date To"},"description":"End of date range"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size","default":50,"title":"Limit"},"description":"Page size"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Page offset","default":0,"title":"Offset"},"description":"Page offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Get Phi Access Report

> PHI access report — who accessed what patient data, when, from where.\
> \
> Required for HIPAA breach investigation (§164.312(b)).\
> \
> Permissions: admin, owner

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AuditEventsListResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/src__routes__audit__AuditEventResponse"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["events","total","limit","offset","has_more"],"title":"AuditEventsListResponse"},"src__routes__audit__AuditEventResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"timestamp":{"type":"string","title":"Timestamp"},"service":{"type":"string","title":"Service"},"actor_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Entity Id"},"actor_credential_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Credential Id"},"action":{"type":"string","title":"Action"},"resource_type":{"type":"string","title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","default":false}},"type":"object","required":["id","workspace_id","timestamp","service","action","resource_type"],"title":"AuditEventResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/audit/phi-access":{"get":{"tags":["Audit"],"summary":"Get Phi Access Report","description":"PHI access report — who accessed what patient data, when, from where.\n\nRequired for HIPAA breach investigation (§164.312(b)).\n\nPermissions: admin, owner","operationId":"get-phi-access-report","parameters":[{"name":"entity_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by patient entity","title":"Entity Id"},"description":"Filter by patient entity"},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Start of date range","title":"Date From"},"description":"Start of date range"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of date range","title":"Date To"},"description":"End of date range"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size","default":50,"title":"Limit"},"description":"Page size"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Page offset","default":0,"title":"Offset"},"description":"Page offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventsListResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Get Entity Access Log

> Per-entity access history — all audit events for a specific resource.\
> \
> Permissions: admin, owner

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AuditEventsListResponse":{"properties":{"events":{"items":{"$ref":"#/components/schemas/src__routes__audit__AuditEventResponse"},"type":"array","title":"Events"},"total":{"type":"integer","title":"Total"},"limit":{"type":"integer","title":"Limit"},"offset":{"type":"integer","title":"Offset"},"has_more":{"type":"boolean","title":"Has More"}},"type":"object","required":["events","total","limit","offset","has_more"],"title":"AuditEventsListResponse"},"src__routes__audit__AuditEventResponse":{"properties":{"id":{"type":"string","title":"Id"},"workspace_id":{"type":"string","title":"Workspace Id"},"timestamp":{"type":"string","title":"Timestamp"},"service":{"type":"string","title":"Service"},"actor_entity_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Entity Id"},"actor_credential_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Actor Credential Id"},"action":{"type":"string","title":"Action"},"resource_type":{"type":"string","title":"Resource Type"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","default":false}},"type":"object","required":["id","workspace_id","timestamp","service","action","resource_type"],"title":"AuditEventResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/audit/entity/{entity_id}/access-log":{"get":{"tags":["Audit"],"summary":"Get Entity Access Log","description":"Per-entity access history — all audit events for a specific resource.\n\nPermissions: admin, owner","operationId":"get-entity-access-log","parameters":[{"name":"entity_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Entity Id"}},{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Start of date range","title":"Date From"},"description":"Start of date range"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of date range","title":"Date To"},"description":"End of date range"},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","maximum":100,"minimum":1,"description":"Page size","default":50,"title":"Limit"},"description":"Page size"},{"name":"offset","in":"query","required":false,"schema":{"type":"integer","minimum":0,"description":"Page offset","default":0,"title":"Offset"},"description":"Page offset"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditEventsListResponse"}}}},"404":{"description":"Entity not found"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Get Audit Summary

> Audit summary statistics for compliance dashboard.\
> \
> Permissions: admin, owner

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AuditSummaryResponse":{"properties":{"total_events":{"type":"integer","title":"Total Events"},"phi_access_events":{"type":"integer","title":"Phi Access Events"},"unique_actors":{"type":"integer","title":"Unique Actors"},"services_with_events":{"type":"integer","title":"Services With Events"}},"type":"object","required":["total_events","phi_access_events","unique_actors","services_with_events"],"title":"AuditSummaryResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/audit/summary":{"get":{"tags":["Audit"],"summary":"Get Audit Summary","description":"Audit summary statistics for compliance dashboard.\n\nPermissions: admin, owner","operationId":"get-audit-summary","parameters":[{"name":"date_from","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"Start of date range","title":"Date From"},"description":"Start of date range"},{"name":"date_to","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"description":"End of date range","title":"Date To"},"description":"End of date range"}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditSummaryResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## Create Audit Export

> Export audit events to S3 as NDJSON. Returns a presigned download URL.\
> \
> Permissions: admin, owner

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AuditExportRequest":{"properties":{"date_from":{"type":"string","format":"date-time","title":"Date From"},"date_to":{"type":"string","format":"date-time","title":"Date To"},"service":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Service"},"action":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Action"},"phi_only":{"type":"boolean","title":"Phi Only","default":false}},"type":"object","required":["date_from","date_to"],"title":"AuditExportRequest"},"AuditExportResponse":{"properties":{"export_id":{"type":"string","title":"Export Id"},"s3_key":{"type":"string","title":"S3 Key"},"row_count":{"type":"integer","title":"Row Count"},"download_url":{"type":"string","title":"Download Url"},"created_at":{"type":"string","title":"Created At"}},"type":"object","required":["export_id","s3_key","row_count","download_url","created_at"],"title":"AuditExportResponse"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}}},"paths":{"/v1/{workspace_id}/audit/export":{"post":{"tags":["Audit"],"summary":"Create Audit Export","description":"Export audit events to S3 as NDJSON. Returns a presigned download URL.\n\nPermissions: admin, owner","operationId":"create-audit-export","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditExportRequest"}}},"required":true},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditExportResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"},"503":{"description":"Audit export not configured"}}}}}}
```

## List Audit Exports

> List past audit exports with presigned download URLs.\
> \
> Permissions: admin, owner

```json
{"openapi":"3.1.0","info":{"title":"Platform API","version":"1.0.0"},"servers":[{"url":"https://api.platform.amigo.ai","description":"Production"}],"security":[{"BearerAuth":[]}],"components":{"securitySchemes":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key issued via `POST /v1/{workspace_id}/api-keys`. Pass the returned `api_key` value as a Bearer token."}},"schemas":{"AuditExportListResponse":{"properties":{"exports":{"items":{"$ref":"#/components/schemas/AuditExportListItem"},"type":"array","title":"Exports"}},"type":"object","required":["exports"],"title":"AuditExportListResponse"},"AuditExportListItem":{"properties":{"key":{"type":"string","title":"Key"},"size":{"type":"integer","title":"Size"},"last_modified":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Last Modified"},"download_url":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Download Url"}},"type":"object","required":["key","size"],"title":"AuditExportListItem"}}},"paths":{"/v1/{workspace_id}/audit/exports":{"get":{"tags":["Audit"],"summary":"List Audit Exports","description":"List past audit exports with presigned download URLs.\n\nPermissions: admin, owner","operationId":"list-audit-exports","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditExportListResponse"}}}},"429":{"description":"Rate limited"},"503":{"description":"Audit export not configured"}}}}}}
```