Amigo FHIR API

openapi: 3.1.0
info:
  title: Amigo Account FHIR 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: FHIR
paths:
  /v1/{workspace_id}/fhir/status:
    get:
      tags:
      - FHIR
      summary: Get clinical data status
      description: Get event and entity counts for the workspace's clinical data.
      operationId: fhir-status
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirStatusResponse'
        '404':
          description: Workspace not found.
        '401':
          description: Missing or invalid API key.
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
  /v1/{workspace_id}/fhir/import:
    post:
      tags:
      - FHIR
      summary: Import FHIR Bundle
      description: Import a FHIR Bundle. Decomposes supported resources into upserted world events and creates patient entities. Unsupported resource types are skipped and reported; omitted resources are not deleted.
      operationId: fhir-import
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FhirImportRequest'
        required: true
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirImportResponse'
        '400':
          description: Invalid bundle format.
        '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}/fhir/import-stream:
    post:
      tags:
      - FHIR
      summary: Import FHIR resources via NDJSON streaming
      description: 'Stream FHIR resources as NDJSON (one resource per line). Bypasses the buffered-body size cap on /fhir/import. Callers MUST pre-resolve any bundle-internal urn:uuid: references. Unsupported resource types are skipped and reported; omitted resources are not deleted.'
      operationId: fhir-import-stream
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: source
        in: query
        required: false
        schema:
          type: string
          maxLength: 128
          default: fhir_import
          title: Source
      - name: source_system
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Source System
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          title: Data Source Id
      - name: dedup
        in: query
        required: false
        schema:
          type: boolean
          description: Skip identical re-uploads via content-hash dedup
          default: true
          title: Dedup
        description: Skip identical re-uploads via content-hash dedup
      - name: unsupported_resource_policy
        in: query
        required: false
        schema:
          $ref: '#/components/schemas/FhirUnsupportedResourcePolicy'
          description: Use 'error' to report unsupported resources, or 'skip' to skip them without errors.
          default: error
        description: Use 'error' to report unsupported resources, or 'skip' to skip them without errors.
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirImportResponse'
        '400':
          description: Stream exceeded line cap.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/views/patients:
    get:
      tags:
      - FHIR
      summary: List patients (clinical view)
      description: Frontend-ready patient list with flattened demographics, conditions, medications, allergies, and insurance. Optionally scoped to a specific data source via data_source_id.
      operationId: fhir-patients-view
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by name
          title: Q
        description: Search by name
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Scope to data source
          title: Data Source Id
        description: Scope to data source
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirPatientListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/views/practitioners:
    get:
      tags:
      - FHIR
      summary: List practitioners
      description: Frontend-ready practitioner list with name, NPI, specialty, phone. Optionally scoped to a data source.
      operationId: fhir-practitioners-view
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by name
          title: Q
        description: Search by name
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Scope to data source
          title: Data Source Id
        description: Scope to data source
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirPractitionerListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/views/locations:
    get:
      tags:
      - FHIR
      summary: List locations
      description: Frontend-ready location list with name, address, phone, hours. Optionally scoped to a data source.
      operationId: fhir-locations-view
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by name
          title: Q
        description: Search by name
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Scope to data source
          title: Data Source Id
        description: Scope to data source
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirLocationListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/views/appointments:
    get:
      tags:
      - FHIR
      summary: List appointments
      description: Frontend-ready appointment list with date, status, patient, practitioner, location, reason. Optionally scoped to a data source.
      operationId: fhir-appointments-view
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search
          title: Q
        description: Search
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Scope to data source
          title: Data Source Id
        description: Scope to data source
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirAppointmentListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/views/slots:
    get:
      tags:
      - FHIR
      summary: List availability slots
      description: Frontend-ready provider availability slot list with start, end, status, schedule reference, and provider display name. Optionally scoped to a data source.
      operationId: fhir-slots-view
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search
          title: Q
        description: Search
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Scope to data source
          title: Data Source Id
        description: Scope to data source
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Slot status (e.g. 'free', 'busy')
          title: Status
        description: Slot status (e.g. 'free', 'busy')
      - name: date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Start date YYYY-MM-DD (filters slots on or after this date)
          title: Date
        description: Start date YYYY-MM-DD (filters slots on or after this date)
      - name: days
        in: query
        required: false
        schema:
          type: integer
          maximum: 90
          minimum: 1
          description: Number of days forward from date (default 7)
          default: 7
          title: Days
        description: Number of days forward from date (default 7)
      - name: provider
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Provider name (partial match, e.g. 'Woloski')
          title: Provider
        description: Provider name (partial match, e.g. 'Woloski')
      - name: specialty
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Specialty (partial match, e.g. 'Psychiatry')
          title: Specialty
        description: Specialty (partial match, e.g. 'Psychiatry')
      - name: service_type
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Visit/service type name (partial match, e.g. 'Follow-up')
          title: Service Type
        description: Visit/service type name (partial match, e.g. 'Follow-up')
      - name: facility_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Facility ID
          title: Facility Id
        description: Facility ID
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirSlotListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/views/organizations:
    get:
      tags:
      - FHIR
      summary: List organizations
      description: Frontend-ready organization list with name, phone, domain, industry, address. Optionally scoped to a data source.
      operationId: fhir-organizations-view
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by name
          title: Q
        description: Search by name
      - name: data_source_id
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            format: uuid
          - type: 'null'
          description: Scope to data source
          title: Data Source Id
        description: Scope to data source
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirOrganizationListResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/patients:
    get:
      tags:
      - FHIR
      summary: Search patients
      description: Search patient entities by name, MRN, or phone.
      operationId: fhir-patient-search
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by name, MRN, phone, or entity ID
          title: Q
        description: Search by name, MRN, phone, or entity ID
      - name: mrn
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by MRN
          title: Mrn
        description: Search by MRN
      - name: phone
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Search by phone
          title: Phone
        description: Search by phone
      - name: sort_by
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          description: Sort field with +/- prefix (e.g. -last_event_at)
          title: Sort By
        description: Sort field with +/- prefix (e.g. -last_event_at)
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientSearchResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/patients/{patient_id}/timeline:
    get:
      tags:
      - FHIR
      summary: Patient timeline
      description: Get the full event timeline for a patient entity.
      operationId: fhir-patient-timeline
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: patient_id
        in: path
        required: true
        schema:
          type: string
          title: Patient Id
      - name: domain
        in: query
        required: false
        schema:
          anyOf:
          - type: string
          - type: 'null'
          title: Domain
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 200
          minimum: 1
          default: 50
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientTimelineResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/patients/{patient_id}/summary:
    get:
      tags:
      - FHIR
      summary: Patient summary
      description: Get the agent-maintained world model state for a patient.
      operationId: fhir-patient-summary
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: patient_id
        in: path
        required: true
        schema:
          type: string
          title: Patient Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PatientSummaryResponse'
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/resources/{resource_type}:
    get:
      tags:
      - FHIR
      summary: Search FHIR resources
      description: Search FHIR resources by type with standard search parameters.
      operationId: fhir-search-resources
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Resource Type
      - name: _count
        in: query
        required: false
        schema:
          type: integer
          maximum: 100
          minimum: 1
          default: 20
          title: ' Count'
      - name: _offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: ' Offset'
      - name: name
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Name
      - name: identifier
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          title: Identifier
      - name: birthdate
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Birthdate
      - name: date
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 32
          - type: 'null'
          title: Date
      - name: patient
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 128
          - type: 'null'
          title: Patient
      - name: status
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 64
          - type: 'null'
          title: Status
      - name: q
        in: query
        required: false
        schema:
          anyOf:
          - type: string
            maxLength: 200
          - type: 'null'
          description: General search text
          title: Q
        description: General search text
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirSearchResponse'
        '400':
          description: Invalid resource type.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    post:
      tags:
      - FHIR
      summary: Create a FHIR resource
      description: Create a new FHIR resource. Automatically creates patient entities.
      operationId: fhir-create-resource
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Resource Type
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FhirWriteRequest'
      responses:
        '201':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirResourceResponse'
        '400':
          description: Invalid resource type or payload.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/resources/{resource_type}/{resource_id}/history:
    get:
      tags:
      - FHIR
      summary: Get FHIR resource history
      description: Fetch the version history and changed-field provenance for a FHIR resource.
      operationId: fhir-get-resource-history
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Resource Type
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Resource Id
      - name: limit
        in: query
        required: false
        schema:
          type: integer
          maximum: 50
          minimum: 1
          default: 10
          title: Limit
      - name: offset
        in: query
        required: false
        schema:
          type: integer
          minimum: 0
          default: 0
          title: Offset
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirResourceHistoryResponse'
        '400':
          description: Invalid resource type.
        '404':
          description: Resource not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
  /v1/{workspace_id}/fhir/resources/{resource_type}/{resource_id}:
    get:
      tags:
      - FHIR
      summary: Get a FHIR resource
      description: Fetch a single FHIR resource by type and ID.
      operationId: fhir-get-resource
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Resource Type
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Resource Id
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirResourceResponse'
        '400':
          description: Invalid resource type.
        '404':
          description: Resource not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
    put:
      tags:
      - FHIR
      summary: Update a FHIR resource
      description: Update a FHIR resource. Creates a new event that supersedes the old one.
      operationId: fhir-update-resource
      parameters:
      - name: workspace_id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          title: Workspace Id
      - name: resource_type
        in: path
        required: true
        schema:
          type: string
          maxLength: 64
          title: Resource Type
      - name: resource_id
        in: path
        required: true
        schema:
          type: string
          maxLength: 128
          title: Resource Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FhirWriteRequest'
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/FhirResourceResponse'
        '400':
          description: Invalid resource type or payload.
        '404':
          description: Resource not found.
        '422':
          description: Validation Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HTTPValidationError'
components:
  schemas:
    FhirStatusResponse:
      properties:
        configured:
          type: boolean
          title: Configured
        connector_type:
          anyOf:
          - type: string
          - type: 'null'
          title: Connector Type
        event_count:
          type: integer
          title: Event Count
        entity_count:
          type: integer
          title: Entity Count
        entity_type_counts:
          additionalProperties:
            type: integer
          type: object
          title: Entity Type Counts
        resource_type_counts:
          additionalProperties:
            type: integer
          type: object
          title: Resource Type Counts
        last_poll_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Poll At
        last_change_at:
          anyOf:
          - type: string
          - type: 'null'
          title: Last Change At
        sync_healthy:
          anyOf:
          - type: boolean
          - type: 'null'
          title: Sync Healthy
      type: object
      required:
      - configured
      - event_count
      - entity_count
      title: FhirStatusResponse
    FhirSlotView:
      properties:
        entity_id:
          type: string
          format: uuid
          title: Entity Id
        status:
          anyOf:
          - type: string
          - type: 'null'
          title: Status
        start:
          anyOf:
          - type: string
          - type: 'null'
          title: Start
        end:
          anyOf:
          - type: string
          - type: 'null'
          title: End
        schedule_ref:
          anyOf:
          - type: string
          - type: 'null'
          title: Schedule Ref
        provider_name:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Name
        provider_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Provider Id
        facility_id:
          anyOf:
          - type: string
          - type: 'null'
          title: Facility Id
        specialty:
          anyOf:
          - type: string
          - type: 'null'
          title: Specialty
        visit_type_ids:
          anyOf:
     

# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/amigo/refs/heads/main/openapi/amigo-fhir-api-openapi.yml