openapi: 3.2.0
info:
  title: Medblocks Events 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: Events
paths:
  /events/{id}/redeliver:
    post:
      operationId: api.redeliverWebhookEvent
      summary: Manually redeliver a webhook event
      description: Re-enqueue a webhook event for delivery by its `evt_` id. Limited to one redelivery per event each minute.
      parameters:
      - name: id
        in: path
        required: true
        schema:
          type: string
          description: Webhook event id (`evt_*`).
      - $ref: '#/components/parameters/Version'
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/WebhookEvent'
        '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:
      - Events
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
  schemas:
    WebhookEvent:
      type: object
      properties:
        id:
          type: string
          description: Public id, prefixed `evt_`.
        resource_type:
          const: event
        webhook_endpoint_id:
          type: string
          description: The `wh_*` endpoint this delivery targets.
        type:
          enum:
          - patient_session.completed
          - connection.token_refresh_failed
          - records.sync.completed
          - records.sync.failed
          type: string
          description: Event type discriminator.
        data:
          type: object
          properties:
            object:
              description: Event-specific payload. Shape depends on `type` — see the SDK's typed `WebhookEvent` union for the discriminated shape.
        api_version:
          type: string
          description: API version pinned at the endpoint at fire time.
        attempts:
          type: integer
          minimum: -9007199254740991
          maximum: 9007199254740991
          description: Number of delivery attempts made so far (incl. the current one).
        next_attempt_at:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 8601 timestamp of the next scheduled retry. Null when terminal (delivered or exhausted).
        delivered_at:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 8601 timestamp of successful delivery. Null until a 2xx response is received.
        last_status_code:
          anyOf:
          - type: integer
            minimum: -9007199254740991
            maximum: 9007199254740991
          - type: 'null'
          description: HTTP status code from the most recent attempt.
        last_response_body:
          anyOf:
          - type: string
          - type: 'null'
          description: Response body from the most recent attempt, truncated to 4 KB.
        last_redelivered_at:
          anyOf:
          - type: string
          - type: 'null'
          description: ISO 8601 timestamp of the most recent manual redelivery. Null if never redelivered.
        created_at:
          type: string
      required:
      - id
      - resource_type
      - webhook_endpoint_id
      - type
      - data
      - api_version
      - attempts
      - next_attempt_at
      - delivered_at
      - last_status_code
      - last_response_body
      - last_redelivered_at
      - created_at
      examples:
      - id: evt_01J9YR9N3X4VZ6P2K5RH7M3LMP
        resource_type: event
        webhook_endpoint_id: wh_01J9YR9N3X4VZ6P2K5RH7M3LMP
        type: patient_session.completed
        data:
          object:
            id: ps_01J9YQ8M2X4VZ6P2K5RH7M3KQT
            resource_type: patient_session
            status: complete
            patient_id: user_42
        api_version: '2026-04-25'
        attempts: 1
        next_attempt_at: null
        delivered_at: '2026-04-25T14:35:02.000Z'
        last_status_code: 200
        last_response_body: ok
        last_redelivered_at: null
        created_at: '2026-04-25T14:35:00.000Z'
    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
  headers:
    RetryAfter:
      description: Whole seconds to wait before retrying a rate-limited request.
      schema:
        type: integer
        minimum: 1
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key (mb_sk_live_...)
      description: Medblocks API key for server-side requests.