> For the complete documentation index, see [llms.txt](https://docs.amigo.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.amigo.ai/api-reference/readme/platform/audit.md).

# Audit

## List Audit Events

> List audit events with filters and pagination.\
> \
> Permissions: admin, owner (\`\`Audit.view\`\`)

```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","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"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 (``Audit.view``)","operationId":"list-audit-events","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Filter by service name","title":"Service"},"description":"Filter by service name"},{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"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","maxLength":64},{"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 (\`\`Audit.view\`\`)

```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","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"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 (``Audit.view``)","operationId":"get-phi-access-report","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"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 (\`\`Audit.view\`\`)

```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","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"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 (``Audit.view``)","operationId":"get-entity-access-log","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"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 (\`\`Audit.view\`\`)

```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 (``Audit.view``)","operationId":"get-audit-summary","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace 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"}],"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

> Submit an async audit-events export.\
> \
> Runs the filtered query on the SQL warehouse with results staged to\
> presigned CSV EXTERNAL\_LINKS, and returns a Databricks \`\`statement\_id\`\`.\
> Poll \`\`GET /export/{statement\_id}\`\` for the download links. Nothing is\
> materialized in platform-api, so the export scales to large date windows.\
> \
> 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","maxLength":64},{"type":"null"}],"title":"Service","description":"Filter by service name."},"action":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"title":"Action","description":"Filter by action type."},"phi_only":{"type":"boolean","title":"Phi Only","default":false}},"type":"object","required":["date_from","date_to"],"title":"AuditExportRequest"},"AuditExportSubmitResponse":{"properties":{"statement_id":{"type":"string","title":"Statement Id","description":"Databricks statement handle — poll GET /export/{statement_id} for links."},"status":{"type":"string","enum":["pending","ready"],"title":"Status","description":"pending: still running. ready: links available immediately."}},"type":"object","required":["statement_id","status"],"title":"AuditExportSubmitResponse"},"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":"Submit an async audit-events export.\n\nRuns the filtered query on the SQL warehouse with results staged to\npresigned CSV EXTERNAL_LINKS, and returns a Databricks ``statement_id``.\nPoll ``GET /export/{statement_id}`` for the download links. Nothing is\nmaterialized in platform-api, so the export scales to large date windows.\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/AuditExportSubmitResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}},"parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}}]}}}}
```

## Get Audit Export

> Poll a submitted audit export and return presigned CSV download links.\
> \
> \`\`status\`\` is \`\`pending\`\` until the statement finishes, then \`\`ready\`\` with\
> \`\`chunks\`\` carrying short-lived presigned URLs the client downloads\
> directly from object storage. The links expire quickly (\~15 min) — re-poll\
> to refresh. The workspace scope was fixed into the statement at submit\
> time; \`\`statement\_id\`\` is an unguessable, short-lived capability.\
> \
> Permissions: admin, owner (\`\`Audit.export\`\` — same gate as create).

```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":{"AuditExportResultResponse":{"properties":{"statement_id":{"type":"string","title":"Statement Id"},"status":{"type":"string","enum":["pending","ready"],"title":"Status"},"result_format":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Result Format","description":"Result file format (CSV)."},"total_row_count":{"type":"integer","title":"Total Row Count","default":0},"chunks":{"items":{"$ref":"#/components/schemas/AuditExportChunk"},"type":"array","title":"Chunks"}},"type":"object","required":["statement_id","status"],"title":"AuditExportResultResponse"},"AuditExportChunk":{"properties":{"chunk_index":{"type":"integer","title":"Chunk Index"},"row_count":{"type":"integer","title":"Row Count"},"byte_count":{"type":"integer","title":"Byte Count"},"external_link":{"type":"string","title":"External Link","description":"Short-lived presigned URL — download directly, do not proxy."},"expiration":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Expiration","description":"ISO-8601 expiry of the presigned link."}},"type":"object","required":["chunk_index","row_count","byte_count","external_link"],"title":"AuditExportChunk"}}},"paths":{"/v1/{workspace_id}/audit/export/{statement_id}":{"get":{"tags":["Audit"],"summary":"Get Audit Export","description":"Poll a submitted audit export and return presigned CSV download links.\n\n``status`` is ``pending`` until the statement finishes, then ``ready`` with\n``chunks`` carrying short-lived presigned URLs the client downloads\ndirectly from object storage. The links expire quickly (~15 min) — re-poll\nto refresh. The workspace scope was fixed into the statement at submit\ntime; ``statement_id`` is an unguessable, short-lived capability.\n\nPermissions: admin, owner (``Audit.export`` — same gate as create).","operationId":"get-audit-export","parameters":[{"name":"workspace_id","in":"path","required":true,"schema":{"type":"string","format":"uuid","title":"Workspace Id"}},{"name":"statement_id","in":"path","required":true,"schema":{"type":"string","title":"Statement Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AuditExportResultResponse"}}}},"422":{"description":"Invalid statement_id"},"429":{"description":"Rate limited"}}}}}}
```

## List My Audit Events

> List the authenticated caller's own audit events across every workspace.\
> \
> Any authenticated caller may read their OWN trail — deliberately no\
> \`\`Audit.view\`\` gate. \`\`actor\_entity\_id\`\` is server-set to the caller's entity\
> and is NEVER accepted from the client, so the \`\`workspace\_id=None\`\` query can\
> only ever return the caller's own events (safe cross-workspace).

```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","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"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/audit-log/me":{"get":{"tags":["Audit"],"summary":"List My Audit Events","description":"List the authenticated caller's own audit events across every workspace.\n\nAny authenticated caller may read their OWN trail — deliberately no\n``Audit.view`` gate. ``actor_entity_id`` is server-set to the caller's entity\nand is NEVER accepted from the client, so the ``workspace_id=None`` query can\nonly ever return the caller's own events (safe cross-workspace).","operationId":"list-my-audit-events","parameters":[{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"type":"null"}],"description":"Filter by action type","title":"Action"},"description":"Filter by action type"},{"name":"resource_type","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Filter by resource type","title":"Resource Type"},"description":"Filter by resource type"},{"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"}}}},"403":{"description":"Credential has no associated actor entity"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```

## List Platform Audit Events

> Cross-workspace + null-workspace audit read — platform administrators only.\
> \
> The surface for cross-workspace and null-workspace events (login /\
> token-theft events carry no workspace). Gated strictly on the global\
> \`\`platform:admin\`\` scope carried by an identity JWT; every other caller —\
> including a workspace owner/admin — is rejected with 403.

```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","format":"uuid","title":"Id","description":"Unique audit event identifier"},"workspace_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Workspace Id","description":"Workspace that owns this event; null for pre-workspace events (e.g. login)"},"timestamp":{"type":"string","title":"Timestamp","description":"ISO-8601 timestamp of the event"},"service":{"type":"string","title":"Service","description":"Service that produced the event"},"actor_entity_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Entity Id","description":"Entity ID of the actor who performed the action"},"actor_credential_id":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"title":"Actor Credential Id","description":"Credential ID used by the actor"},"action":{"type":"string","title":"Action","description":"Action that was performed (e.g. 'entity.read')"},"resource_type":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Type","description":"Type of resource that was accessed"},"resource_id":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Id","description":"ID of the accessed resource"},"resource_name":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Resource Name","description":"Human-readable name of the accessed resource"},"ip_address":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Ip Address","description":"IP address of the actor"},"user_agent":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"User Agent","description":"User-Agent header from the request"},"metadata":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Metadata","description":"Additional event-specific metadata"},"phi_accessed":{"type":"boolean","title":"Phi Accessed","description":"Whether protected health information was accessed","default":false}},"type":"object","required":["id","timestamp","service","action"],"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/audit-log/platform":{"get":{"tags":["Audit"],"summary":"List Platform Audit Events","description":"Cross-workspace + null-workspace audit read — platform administrators only.\n\nThe surface for cross-workspace and null-workspace events (login /\ntoken-theft events carry no workspace). Gated strictly on the global\n``platform:admin`` scope carried by an identity JWT; every other caller —\nincluding a workspace owner/admin — is rejected with 403.","operationId":"list-audit-events-platform","parameters":[{"name":"workspace_id","in":"query","required":false,"schema":{"anyOf":[{"type":"string","format":"uuid"},{"type":"null"}],"description":"Filter by workspace; omit for all workspaces","title":"Workspace Id"},"description":"Filter by workspace; omit for all workspaces"},{"name":"service","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":64},{"type":"null"}],"description":"Filter by service name","title":"Service"},"description":"Filter by service name"},{"name":"action","in":"query","required":false,"schema":{"anyOf":[{"type":"string","maxLength":128},{"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","maxLength":64},{"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"}}}},"403":{"description":"platform:admin scope required"},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}},"429":{"description":"Rate limited"}}}}}}
```


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.amigo.ai/api-reference/readme/platform/audit.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.