Amigo Audit API

openapi: 3.2.0
info:
  title: Platform Audit API
  description: Management API for the Amigo platform. Provides CRUD operations for workspaces, API keys, and resources.
  version: 1.0.0
servers:
- url: https://api.platform.amigo.ai
  description: Production
security:
- BearerAuth: []
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:
    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
    AuditExportListResponse:
      properties:
        exports:
          items:
            $ref: '#/components/schemas/AuditExportListItem'
          type: array
          title: Exports
      type: object
      required:
      - exports
      title: AuditExportListResponse
    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
    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
    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
    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
    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
    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
    HTTPValidationError:
      properties:
        detail:
          items:
            $ref: '#/components/schemas/ValidationError'
          type: array
          title: Detail
      type: object
      title: HTTPValidationError
  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.