openapi: 3.1.0
servers:
  - url: https://chat.api.sunnyhealthai-staging.com
    description: Chat API server
info:
  description: |
    The Sunny Agents SDK provides a TypeScript/JavaScript library designed specifically for building healthcare concierge applications. Embed AI-powered chat experiences that help patients find providers, book appointments, get health information, and navigate care—all in real-time.
    
    ### Key Features
    - **Headless Client**: Build custom healthcare chat UIs with full control over the interface
    - **Vanilla Widget**: Drop-in healthcare concierge widget for quick integration
    - **Real-time Messaging**: WebSocket-based streaming responses for instant care guidance
    - **Token Exchange**: Secure authentication flow using ID tokens for HIPAA-compliant sessions
    - **Artifact Support**: Rich content delivered inline via WebSocket JIT transformation
    - **MCP Approvals**: Handle tool execution approvals interactively for secure healthcare operations
    
    ### Authentication
    The SDK supports multiple authentication modes:
    - **SAML/OIDC**: Enterprise SSO via Auth0 with automatic popup login
    - **Token Exchange**: Convert partner-provided ID tokens to access tokens
    - **Passwordless**: Email or SMS-based OTP authentication without passwords
    - **Anonymous Mode**: Local-only conversations without server persistence
    
    ### Developer Notes
    - WebSocket connections are made directly to the WebSocket URL
    - Authentication happens via `auth.upgrade` messages over the WebSocket connection
    - Token exchange is handled transparently when configured
    - Artifacts are expanded JIT in the WebSocket stream and delivered inline in message text
    - Designed for healthcare use cases: provider search, appointment booking, health information, and benefits navigation
  version: 1.0.0
  title: Sunny Agents SDK API
  contact:
    name: Sunny Agents SDK Support
    email: support@sunnyhealthai.com
  license:
    name: MIT
    url: "https://opensource.org/licenses/MIT"
tags:
  - name: Chat
    description: WebSocket-based chat messaging operations
  - name: Conversations
    description: Conversation management operations
  - name: Artifacts
    description: Inline artifact format in message text (WebSocket JIT expansion)
  - name: Authentication
    description: Authentication and token exchange operations
  - name: Configuration
    description: SDK configuration retrieval
paths:
  /oauth/token:
    post:
      tags:
        - Authentication
      summary: Exchange ID token for access token
      description: |
        Exchange an ID token for an access token using OAuth 2.0 token exchange.
        This endpoint is used internally by the SDK when token exchange is configured.
      operationId: tokenExchange
      servers:
        - url: https://auth.sunnyhealthai.com
          description: Production API server
        - url: https://auth.sunnyhealth.live
          description: Staging API server
      requestBody:
        required: true
        content:
          application/x-www-form-urlencoded:
            schema:
              type: object
              required:
                - grant_type
                - subject_token
                - subject_token_type
                - audience
                - client_id
              properties:
                grant_type:
                  type: string
                  example: "urn:ietf:params:oauth:grant-type:token-exchange"
                subject_token:
                  type: string
                  description: The ID token to exchange
                subject_token_type:
                  type: string
                  description: Token type identifier (e.g., "urn:sunny-health-external-mock:id-token")
                audience:
                  type: string
                  description: API audience for the access token
                  example: "https://api.sunnyhealthai-staging.com"
                client_id:
                  type: string
                  description: Auth0 client ID
      responses:
        "200":
          description: Token exchange successful
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/TokenExchangeResponse"
              examples:
                exampleResponse:
                  summary: Successful token exchange
                  value:
                    access_token: "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9..."
                    token_type: "Bearer"
                    expires_in: 3600
        "400":
          description: Invalid request
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
        "401":
          description: Invalid ID token
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/Error"
  /sdk/config:
    get:
      tags:
        - Configuration
      summary: Fetch SDK configuration
      description: |
        Fetch auth configuration for the SDK. Called by `createSunnyChat` before
        establishing a WebSocket connection. Returns Auth0 domain, client ID,
        token exchange URL, and other partner-specific settings needed to
        activate the chosen authentication mode.
      operationId: getSdkConfig
      parameters:
        - name: x-sunny-partner-identifier
          in: header
          required: true
          schema:
            type: string
          description: Partner identifier (e.g., "acme-health")
          example: "acme-health"
        - name: x-sunny-api-key
          in: header
          required: true
          schema:
            type: string
          description: Public API key (e.g., "pk-sunnyagents_abc_xyz")
          example: "pk-sunnyagents_abc_xyz"
      responses:
        "200":
          description: SDK configuration retrieved successfully
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SdkConfigResponse"
              examples:
                samlConfig:
                  summary: SAML partner configuration
                  value:
                    config:
                      auth0_domain: "login.sunnyhealthai.com"
                      auth0_client_id: "abc123def456"
                      auth0_connection: "acme-saml"
                      audience: "https://api.sunnyhealthai-staging.com"
                      organization: "org_acme"
                tokenExchangeConfig:
                  summary: Token exchange configuration
                  value:
                    config:
                      auth0_domain: "login.sunnyhealthai.com"
                      auth0_client_id: "abc123def456"
                      audience: "https://api.sunnyhealthai-staging.com"
                      organization: "org_acme"
                      token_exchange_url: "https://auth.sunnyhealthai-staging.com/oauth/token"
        "400":
          description: Invalid request (missing or malformed headers)
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SdkConfigError"
        "401":
          description: Invalid API key or unrecognized partner
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SdkConfigError"
components:
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: JWT
      description: Access token obtained via token exchange
  schemas:
    TokenExchangeResponse:
      type: object
      required:
        - access_token
        - token_type
        - expires_in
      properties:
        access_token:
          type: string
          description: Access token for API authentication
        token_type:
          type: string
          example: "Bearer"
        expires_in:
          type: integer
          description: Token expiration time in seconds
          example: 3600
    ChatArtifact:
      type: object
      description: Inline artifact format embedded in message text (WebSocket JIT expansion)
      required:
        - item_type
        - item_content
      properties:
        id:
          type: string
          description: Unique artifact identifier (may be omitted in inline format)
        item_type:
          type: string
          description: Type of artifact (e.g., "doctor_profile")
          example: "doctor_profile"
        item_content:
          type: object
          description: Artifact content (structure varies by type)
          additionalProperties: true
        content:
          type: object
          description: Alternative content field (for backward compatibility)
          additionalProperties: true
        created_at:
          type: string
          format: date-time
          description: Artifact creation timestamp (in inline format)
    DoctorProfileArtifact:
      type: object
      properties:
        npi:
          type: string
          description: National Provider Identifier
        first_name:
          type: string
        last_name:
          type: string
        title:
          type: string
        specialty:
          type: string
        languages_spoken:
          type: array
          items:
            type: string
        gender:
          type: string
        rating:
          type: number
          format: float
        review_count:
          type: integer
        last_updated_at:
          type: string
          format: date-time
        locations:
          type: object
          additionalProperties: true
        rank_score:
          type: number
          format: float
        mrf_rates:
          type: array
          items:
            type: object
            additionalProperties: true
        out_of_pocket_costs:
          type: array
          items:
            $ref: "#/components/schemas/OutOfPocketCost"
    OutOfPocketCost:
      type: object
      properties:
        procedure_code:
          type: string
        procedure_code_type:
          type: string
        procedure_name:
          type: string
        rate:
          type: number
        out_of_pocket:
          type: number
    Conversation:
      type: object
      required:
        - id
        - messages
      properties:
        id:
          type: string
          description: Unique conversation identifier
        title:
          type: string
          nullable: true
          description: Optional conversation title
        messages:
          type: array
          items:
            $ref: "#/components/schemas/Message"
        quickResponses:
          type: array
          items:
            type: string
          description: Suggested quick response options
    Message:
      type: object
      required:
        - id
        - role
        - text
        - createdAt
      properties:
        id:
          type: string
          description: Unique message identifier
        role:
          type: string
          enum: [user, assistant, system]
          description: Message role
        text:
          type: string
          description: Message text content
        createdAt:
          type: string
          format: date-time
          description: Message creation timestamp
        isStreaming:
          type: boolean
          description: Whether the message is currently streaming
        outputItems:
          type: array
          items:
            $ref: "#/components/schemas/MessageItem"
          description: Rich content items in the message
        feedback:
          type: boolean
          nullable: true
          description: User feedback on the message (true=positive, false=negative)
    MessageItem:
      type: object
      properties:
        type:
          type: string
          description: Item type (e.g., "message", "mcp_approval_request")
        id:
          type: string
          description: Item identifier
        name:
          type: string
          description: Item name
        server_label:
          type: string
          description: Server-provided label
        arguments:
          type: object
          additionalProperties: true
          description: Item arguments (structure varies by type)
        approval_request_id:
          type: string
          description: Approval request ID (for MCP approval items)
        approve:
          type: boolean
          description: Approval decision (for MCP approval responses)
        reason:
          type: string
          nullable: true
          description: Reason for approval/rejection
        content:
          type: array
          items:
            $ref: "#/components/schemas/MessageContentFragment"
          description: Content fragments
    MessageContentFragment:
      type: object
      properties:
        type:
          type: string
        text:
          type: string
    SdkConfigResponse:
      type: object
      required:
        - config
      properties:
        config:
          $ref: "#/components/schemas/SdkAuthConfig"
    SdkAuthConfig:
      type: object
      description: Server-provided auth configuration. Contains only public fields — no secrets.
      properties:
        auth0_domain:
          type: string
          description: Auth0 tenant domain for SAML/OIDC/token-exchange flows
          example: "login.sunnyhealthai.com"
        auth0_client_id:
          type: string
          description: Auth0 application client ID
          example: "abc123def456"
        auth0_connection:
          type: string
          description: Auth0 connection name (e.g., SAML connection identifier)
          example: "acme-saml"
        audience:
          type: string
          description: API audience for access tokens
          example: "https://api.sunnyhealthai-staging.com"
        organization:
          type: string
          description: Auth0 organization identifier
          example: "org_acme"
        token_exchange_url:
          type: string
          description: Custom token exchange endpoint URL (used when authType is "tokenExchange")
          example: "https://auth.sunnyhealthai-staging.com/oauth/token"
    SdkConfigError:
      type: object
      required:
        - error
      properties:
        error:
          type: object
          required:
            - message
          properties:
            message:
              type: string
              description: Human-readable error message
    Error:
      type: object
      required:
        - message
      properties:
        message:
          type: string
          description: Error message
        code:
          type: string
          description: Error code
        details:
          type: object
          additionalProperties: true
          description: Additional error details