openapi: 3.1.0 info: title: Amigo Account Audit API version: 0.1.0 servers: - url: https://api.amigo.ai - url: https://internal-api.amigo.ai - url: https://api-eu-central-1.amigo.ai - url: https://api-ap-southeast-2.amigo.ai - url: https://api-ca-central-1.amigo.ai security: - Bearer-Authorization: [] Bearer-Authorization-Organization: [] Basic: [] tags: - name: Audit paths: /v1/{workspace_id}/audit: get: tags: - Audit summary: List Audit Events description: 'List audit events with filters and pagination. Permissions: 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' '429': description: Rate limited '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /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. Required for HIPAA breach investigation (§164.312(b)). Permissions: 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' '429': description: Rate limited '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /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. Permissions: 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 '429': description: Rate limited '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/{workspace_id}/audit/summary: get: tags: - Audit summary: Get Audit Summary description: 'Audit summary statistics for compliance dashboard. Permissions: 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' '429': description: Rate limited '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/{workspace_id}/audit/export: post: tags: - Audit summary: Create Audit Export description: 'Export audit events to the UC Volume as NDJSON. Returns a platform-api proxy download path (UC Volumes have no presigned URLs — ``download_audit_export`` streams the bytes). Permissions: 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' '429': description: Rate limited '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' parameters: - name: workspace_id in: path required: true schema: type: string format: uuid title: Workspace Id /v1/{workspace_id}/audit/exports: get: tags: - Audit summary: List Audit Exports description: 'List past audit exports with platform-api proxy download paths. Permissions: admin, owner' operationId: list-audit-exports parameters: - name: workspace_id in: path required: true schema: type: string format: uuid title: Workspace Id - name: limit in: query required: false schema: type: integer maximum: 200 minimum: 1 description: Max exports to return default: 50 title: Limit description: Max exports to return responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/AuditExportListResponse' '429': description: Rate limited '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/HTTPValidationError' /v1/{workspace_id}/audit/exports/download/{filename}: get: tags: - Audit summary: Download Audit Export description: 'Proxy-download an audit export artifact (NDJSON) from the UC Volume. ``filename`` must be a bare export filename (``{export_id}.ndjson``); path separators and traversal sequences are rejected with 422. The volume key is reconstructed server-side as ``exports/{workspace_id}/{filename}``, so a caller can never reach outside its own workspace prefix. The bytes are streamed volume→client without buffering the artifact in memory. Permissions: admin, owner (``Audit.export`` — same gate as create/list).' operationId: download-audit-export parameters: - name: workspace_id in: path required: true schema: type: string format: uuid title: Workspace Id - name: filename in: path required: true schema: type: string title: Filename responses: '200': description: The export artifact, streamed as NDJSON. content: application/json: schema: {} application/x-ndjson: {} '404': description: Audit export not found '422': description: Invalid export filename '429': description: Rate limited components: schemas: src__routes__audit__AuditEventResponse: properties: id: type: string format: uuid title: Id description: Unique audit event identifier workspace_id: type: string format: uuid title: Workspace Id description: Workspace that owns this audit event 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 - workspace_id - timestamp - service - action title: AuditEventResponse HTTPValidationError: properties: detail: items: $ref: '#/components/schemas/ValidationError' type: array title: Detail type: object title: HTTPValidationError 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 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 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 AuditExportListResponse: properties: exports: items: $ref: '#/components/schemas/AuditExportListItem' type: array title: Exports type: object required: - exports title: AuditExportListResponse 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 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 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 securitySchemes: Bearer-Authorization: type: http scheme: bearer bearerFormat: JWT description: Amigo issued JWT token that identifies an user. It's issued either after logging in through the frontend, or manually through the [`SignInWithAPIKey`](sign-in-with-api-key) endpoint. Bearer-Authorization-Organization: type: apiKey in: header name: X-ORG-ID description: An optional organization identifier that indicates from which organization the token is issued. This is used in rare cases where the user to authenticate is making a request for resources in another organization. Basic: type: http scheme: basic description: The username should be set to {org_id}_{user_id}, and the password should be the Amigo issued JWT token that identifies the user.