Suki Ambient API — Sessions

naftiko: 1.0.0-alpha2
info:
  label: Suki Ambient API — Sessions
  description: Lifecycle of an ambient documentation session — create, seed context, end, poll status.
  tags:
    - Suki
    - Ambient
    - Sessions
  created: '2026-05-24'
  modified: '2026-05-24'
binds:
  - namespace: env
    keys:
      SUKI_SDP_TOKEN: SUKI_SDP_TOKEN
capability:
  consumes:
    - type: http
      namespace: ambient-sessions
      baseUri: https://sdp.suki-stage.com
      description: Suki Speech Service ambient session lifecycle.
      resources:
        - name: ambient-sessions
          path: /api/v1/ambient/sessions
          operations:
            - name: createsession
              method: POST
              description: Create an ambient documentation session
              outputRawFormat: json
              outputParameters:
                - { name: result, type: object, value: $. }
              inputParameters:
                - { name: body, in: body, type: object, required: true }
        - name: ambient-session-context
          path: /api/v1/ambient/sessions/{sessionId}/context
          operations:
            - name: seedcontext
              method: POST
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
                - { name: body, in: body, type: object, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
            - name: updatecontext
              method: PATCH
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
                - { name: body, in: body, type: object, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: ambient-session-end
          path: /api/v1/ambient/sessions/{sessionId}/end
          operations:
            - name: endsession
              method: POST
              inputParameters:
                - { name: sessionId, in: path, type: string, required: true }
              outputParameters:
                - { name: result, type: object, value: $. }
        - name: ambient-session-status
          path: /api/v1/ambient/sessions/{sessionId}/status
          operations:
            - name: getstatus
              method: GET
              inputParameters:
                - { name: sessionId, 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: rest
      namespace: ambient-sessions-rest
      port: 8080
      description: REST adapter for Suki Ambient sessions.
      resources:
        - path: /v1/ambient/sessions
          name: ambient-sessions
          operations:
            - { method: POST, name: createsession, call: ambient-sessions.createsession, with: { body: rest.body } }
        - path: /v1/ambient/sessions/{sessionId}/context
          name: ambient-session-context
          operations:
            - { method: POST, name: seedcontext, call: ambient-sessions.seedcontext, with: { sessionId: rest.sessionId, body: rest.body } }
            - { method: PATCH, name: updatecontext, call: ambient-sessions.updatecontext, with: { sessionId: rest.sessionId, body: rest.body } }
        - path: /v1/ambient/sessions/{sessionId}/end
          name: ambient-session-end
          operations:
            - { method: POST, name: endsession, call: ambient-sessions.endsession, with: { sessionId: rest.sessionId } }
        - path: /v1/ambient/sessions/{sessionId}/status
          name: ambient-session-status
          operations:
            - { method: GET, name: getstatus, call: ambient-sessions.getstatus, with: { sessionId: rest.sessionId } }
    - type: mcp
      namespace: ambient-sessions-mcp
      port: 9090
      transport: http
      description: MCP adapter for Suki Ambient sessions.
      tools:
        - { name: suki-ambient-create-session, description: Create an ambient documentation session, hints: { readOnly: false, destructive: false, idempotent: false }, call: ambient-sessions.createsession, with: { body: tools.body } }
        - { name: suki-ambient-seed-context, description: Seed context into a session, hints: { readOnly: false, destructive: false, idempotent: true }, call: ambient-sessions.seedcontext, with: { sessionId: tools.sessionId, body: tools.body } }
        - { name: suki-ambient-update-context, description: Update context on a session, hints: { readOnly: false, destructive: false, idempotent: true }, call: ambient-sessions.updatecontext, with: { sessionId: tools.sessionId, body: tools.body } }
        - { name: suki-ambient-end-session, description: End an ambient session and queue note generation, hints: { readOnly: false, destructive: false, idempotent: true }, call: ambient-sessions.endsession, with: { sessionId: tools.sessionId } }
        - { name: suki-ambient-get-status, description: Poll ambient session status, hints: { readOnly: true, destructive: false, idempotent: true }, call: ambient-sessions.getstatus, with: { sessionId: tools.sessionId } }