openapi: 3.2.0
info:
  title: Medblocks Launch Contexts API
  version: '2026-04-25'
  description: 'Developer API for the Medblocks Platform.


    Connect any patient to one or more EHRs (Epic, Cerner, Athena, …) via a single hosted PatientSession, then pull their unified FHIR records through this API. Server-to-server only — no browser-side calls. Authenticate every request with a Bearer secret key.


    **Resources:** `PatientSession`, `Patient`, `Connection`, `FhirSource`. **Conventions:** date-pinned versioning (optional `Version` header), a typed error envelope on every non-2xx response.'
  license:
    name: Proprietary
    url: https://medblocks.com/terms
servers:
- url: https://app.medblocks.com
security:
- BearerAuth: []
tags:
- name: Launch Contexts
paths:
  /launch-contexts/{id}:
    get:
      operationId: api.retrieveLaunchContext
      summary: Retrieve an EHR launch context
      description: Resolve the `mb_launch` handle (appended to your app's launch URL after an EHR launch) into the patient / encounter / practitioner / EHR the app was launched in.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          format: uuid
          description: The `mb_launch` handle appended to your app's launch URL by Connect after an EHR launch.
      - $ref: '#/components/parameters/Version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                type: object
                properties:
                  id:
                    type: string
                    description: The launch handle (echoes the `mb_launch` value).
                  resource_type:
                    const: launch_context
                    description: Resource type discriminator. Always `"launch_context"`.
                  status:
                    enum:
                    - ready
                    - pending
                    type: string
                    description: '`ready` once the launch''s token exchange has completed; `pending` before it has.'
                  patient:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: FHIR reference of the launched patient (e.g. `Patient/123`). Null if the launch had no patient context.
                  encounter:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: FHIR reference of the launched encounter (e.g. `Encounter/456`). Null if absent.
                  fhir_user:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: FHIR reference of the launching user / practitioner (e.g. `Practitioner/789`), from the id_token. Null if absent.
                  scope:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: Space-delimited scopes granted by the EHR for this launch. Null if absent.
                  fhir_source:
                    anyOf:
                    - type: string
                    - type: 'null'
                    description: EHR id (`fhirsrc_*`) the launch originated from. Null if the source is no longer registered.
                  fhir_base_url:
                    type: string
                    description: FHIR base URL (the launch `iss`) the launch originated from.
                  created_at:
                    type: string
                    description: ISO 8601 timestamp of when the launch was initiated.
                required:
                - id
                - resource_type
                - status
                - patient
                - encounter
                - fhir_user
                - scope
                - fhir_source
                - fhir_base_url
                - created_at
                examples:
                - id: 9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d
                  resource_type: launch_context
                  status: ready
                  patient: Patient/erXuFYUfucBZaryVksYEcMg3
                  encounter: Encounter/eMHbz3rPbqUjMqpUgVrhwgB3
                  fhir_user: Practitioner/eM5CWtq15N0WJeuCet5bJlQ3
                  scope: launch openid fhirUser patient/Patient.read
                  fhir_source: fhirsrc_02Zh2bnvRoWQJYgOAkI0Twcc
                  fhir_base_url: https://fhir.epic.com/interconnect-fhir-oauth/api/FHIR/R4
                  created_at: '2026-06-09T14:30:00.000Z'
        '400':
          description: '400'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '401':
          description: '401'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '403':
          description: '403'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '404':
          description: '404'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '409':
          description: '409'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
        '429':
          description: '429'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
          headers:
            Retry-After:
              $ref: '#/components/headers/RetryAfter'
        '500':
          description: '500'
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorEnvelope'
      tags:
      - Launch Contexts
components:
  parameters:
    Version:
      name: Version
      in: header
      required: false
      description: Date-pinned API version. If omitted, Medblocks uses the version pinned on your API key.
      example: '2026-04-25'
      schema:
        type: string
  headers:
    RetryAfter:
      description: Whole seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        minimum: 1
  schemas:
    ErrorEnvelope:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error category (e.g. authentication_error, permission_error, conflict_error).
            code:
              type: string
              description: Stable code within the type (e.g. invalid_api_key, external_id_already_exists).
            message:
              type: string
              description: Human-readable error message.
            param:
              anyOf:
              - type: string
              - type: 'null'
              description: Affected request parameter, if applicable.
            doc_url:
              type: string
              description: Link to the API errors reference.
            request_id:
              type: string
              description: Correlation id - include in support tickets. Echoes the `X-Request-Id` response header.
          required:
          - type
          - code
          - message
          - param
          - doc_url
          - request_id
      required:
      - error
      examples:
      - error:
          type: authentication_error
          code: invalid_api_key
          message: API key invalid
          param: null
          doc_url: https://medblocks.com/docs/reference/errors
          request_id: 9c9b6f7a-8e4f-4a3b-9c1e-6f3a2d8b7c4d
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key (mb_sk_live_...)
      description: Medblocks API key for server-side requests.