Suki Ambient API — Content

naftiko: 1.0.0-alpha2
info:
  label: Suki Ambient API — Content
  description: Retrieve generated clinical notes, transcripts, recordings, and structured data after ambient sessions complete.
  tags:
    - Suki
    - Ambient
    - Content
  created: '2026-05-24'
  modified: '2026-05-24'
binds:
  - namespace: env
    keys:
      SUKI_SDP_TOKEN: SUKI_SDP_TOKEN
capability:
  consumes:
    - type: http
      namespace: ambient-content
      baseUri: https://sdp.suki-stage.com
      description: Suki Speech Service post-session content retrieval.
      resources:
        - name: ambient-session-content
          path: /api/v1/ambient/sessions/{sessionId}/content
          operations:
            - name: getcontent
              method: GET
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: ambient-session-transcript
          path: /api/v1/ambient/sessions/{sessionId}/transcript
          operations:
            - name: gettranscript
              method: GET
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: ambient-session-recording
          path: /api/v1/ambient/sessions/{sessionId}/recording
          operations:
            - name: getrecording
              method: GET
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: ambient-session-structured-data
          path: /api/v1/ambient/sessions/{sessionId}/structured-data
          operations:
            - name: getstructureddata
              method: GET
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: encounter-content
          path: /api/v1/encounters/{encounterId}/content
          operations:
            - name: getencountercontent
              method: GET
              inputParameters:
                - { name: encounterId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: encounter-structured-data
          path: /api/v1/encounters/{encounterId}/structured-data
          operations:
            - name: getencounterstructured
              method: GET
              inputParameters:
                - { name: encounterId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
      authentication:
        type: apikey
        key: sdp_suki_token
        value: '{{env.SUKI_SDP_TOKEN}}'
        placement: header
  exposes:
    - type: mcp
      namespace: ambient-content-mcp
      port: 9090
      transport: http
      description: MCP adapter for Suki Ambient content retrieval.
      tools:
        - { name: suki-ambient-get-content, description: Retrieve the generated clinical note for a session, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-content.getcontent, with: { sessionId: tools.sessionId } }
        - { name: suki-ambient-get-transcript, description: Retrieve the diarized conversation transcript for a session, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-content.gettranscript, with: { sessionId: tools.sessionId } }
        - { name: suki-ambient-get-recording, description: Retrieve a presigned URL for the captured audio recording, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-content.getrecording, with: { sessionId: tools.sessionId } }
        - { name: suki-ambient-get-structured-data, description: Retrieve structured clinical data from a session, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-content.getstructureddata, with: { sessionId: tools.sessionId } }
        - { name: suki-ambient-get-encounter-content, description: Retrieve note across all sessions for an encounter, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-content.getencountercontent, with: { encounterId: tools.encounterId } }
        - { name: suki-ambient-get-encounter-structured, description: Retrieve structured data across all sessions for an encounter, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-content.getencounterstructured, with: { encounterId: tools.encounterId } }