> ## Documentation Index
> Fetch the complete documentation index at: https://docs.telepatia.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Update an appointment

> Cancel a booking or mark it no-show, or repair a missed session link, by its public id (apt_...) or the consultationInternalId you sent at create. `status` accepts only `cancelled` or `noshow` (a booking is marked fulfilled only by the server when its session is created). `scribeSessionId` attaches the session whose id did not match the booking at create time, and marks it fulfilled. Provide exactly one of the two.



## OpenAPI

````yaml /scribe-api/openapi.json patch /v1/appointments/{appointment_id}
openapi: 3.1.0
info:
  title: Scribe Public API
  description: >-
    External-facing REST API for integrating with the Telepatia platform.
    Authenticate with API keys, set consultation context, and look up scribe
    sessions.
  version: 0.1.0
servers:
  - url: https://scribe-api.telepatia.ai
    description: Production
security:
  - BearerAuth: []
paths:
  /v1/appointments/{appointment_id}:
    patch:
      tags:
        - Appointments
      summary: Update an appointment
      description: >-
        Cancel a booking or mark it no-show, or repair a missed session link, by
        its public id (apt_...) or the consultationInternalId you sent at
        create. `status` accepts only `cancelled` or `noshow` (a booking is
        marked fulfilled only by the server when its session is created).
        `scribeSessionId` attaches the session whose id did not match the
        booking at create time, and marks it fulfilled. Provide exactly one of
        the two.
      operationId: api_appointment_update_v1_appointments__appointment_id__patch
      parameters:
        - name: appointment_id
          in: path
          required: true
          schema:
            type: string
            title: Appointment Id
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AppointmentUpdateRequest'
            example:
              status: cancelled
      responses:
        '200':
          description: Successful Response
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentResponse'
              example:
                appointmentType: follow-up
                consultationInternalId: CONSULT-12345
                createdAt: '2026-08-28T12:00:00.000Z'
                end: '2026-09-01T14:30:00.000Z'
                id: apt_a1b2c3d4e5f6g7h8
                minutesDuration: 30
                reason: Follow-up
                serviceType: cardiology
                start: '2026-09-01T14:00:00.000Z'
                status: booked
        '400':
          description: >-
            Bad Request — invalid parameters, validation failures, or missing
            fields.
          content:
            application/json:
              examples:
                parameter_missing:
                  summary: Missing required field
                  value:
                    error:
                      type: invalid_request_error
                      code: parameter_missing
                      message: name is required.
                      param: name
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
                parameter_invalid:
                  summary: Invalid field value
                  value:
                    error:
                      type: invalid_request_error
                      code: parameter_invalid
                      message: >-
                        idCountry must be a valid country name, ISO alpha-2, or
                        ISO alpha-3 code.
                      param: idCountry
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
                account_invalid:
                  summary: Invalid account
                  value:
                    error:
                      type: invalid_request_error
                      code: account_invalid
                      message: Account has no valid authId.
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '401':
          description: Unauthorized — missing or invalid API key.
          content:
            application/json:
              examples:
                authentication_required:
                  summary: Invalid or missing API key
                  value:
                    error:
                      type: authentication_error
                      code: authentication_required
                      message: Invalid API key.
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '403':
          description: Forbidden — the API key is not allowed to perform this operation.
          content:
            application/json:
              examples:
                permission_denied:
                  summary: Caller lacks permission for this resource
                  value:
                    error:
                      type: permission_error
                      code: permission_denied
                      message: You do not have permission to access this resource.
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
                permission_denied_role:
                  summary: API key's account role is not allowed this operation
                  value:
                    error:
                      type: permission_error
                      code: permission_denied
                      message: >-
                        Your API key is not allowed to create accounts. Account
                        creation requires an institutional API key; this key is
                        scoped to a doctor account.
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '404':
          description: Not Found — the requested resource does not exist.
          content:
            application/json:
              examples:
                resource_not_found:
                  summary: Resource not found
                  value:
                    error:
                      type: invalid_request_error
                      code: resource_not_found
                      message: No session scribe found for the given consultation ID.
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '409':
          description: Conflict — resource already exists or is in a conflicting state.
          content:
            application/json:
              examples:
                resource_conflict:
                  summary: Resource conflict
                  value:
                    error:
                      type: invalid_request_error
                      code: resource_conflict
                      message: >-
                        consultationInternalId is already in use by a different
                        consultation.
                      param: consultationInternalId
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
              schema:
                $ref: '#/components/schemas/ErrorResponse'
        '503':
          description: Service Unavailable — an external dependency is down.
          content:
            application/json:
              examples:
                service_unavailable:
                  summary: External service unavailable
                  value:
                    error:
                      type: api_error
                      code: service_unavailable
                      message: >-
                        The service is temporarily unavailable. Please try again
                        later.
                      requestId: 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
              schema:
                $ref: '#/components/schemas/ErrorResponse'
      security:
        - BearerAuth: []
components:
  schemas:
    AppointmentUpdateRequest:
      properties:
        status:
          anyOf:
            - type: string
              enum:
                - cancelled
                - noshow
            - type: 'null'
          title: Status
          description: Set the booking to cancelled or noshow.
          examples:
            - cancelled
        scribeSessionId:
          anyOf:
            - type: string
              pattern: ^ss_[a-z0-9]{16}$
            - type: 'null'
          title: Scribesessionid
          description: >-
            Public id of the session to attach when it was not auto-linked at
            create time. Sets the link and marks the booking fulfilled.
          examples:
            - ss_a1b2c3d4e5f6g7h8
      type: object
      title: AppointmentUpdateRequest
      description: >-
        PATCH body. Provide exactly one of `status` or `scribeSessionId`.


        `status` is limited to `cancelled` / `noshow` (a booking is fulfilled
        only by the

        server when its session is created). `scribeSessionId` repairs a missed
        link:

        attach the session (`ss_`) whose id did not match the booking at create
        time; the

        booking then becomes `fulfilled`.
      examples:
        - status: cancelled
        - scribeSessionId: ss_a1b2c3d4e5f6g7h8
    AppointmentResponse:
      properties:
        id:
          type: string
          title: Id
          description: Stable public identifier.
          examples:
            - apt_a1b2c3d4e5f6g7h8
        consultationInternalId:
          anyOf:
            - type: string
            - type: 'null'
          title: Consultationinternalid
          examples:
            - CONSULT-12345
        status:
          type: string
          title: Status
          examples:
            - booked
        start:
          anyOf:
            - type: string
            - type: 'null'
          title: Start
          examples:
            - '2026-09-01T14:00:00.000Z'
        end:
          anyOf:
            - type: string
            - type: 'null'
          title: End
          examples:
            - '2026-09-01T14:30:00.000Z'
        minutesDuration:
          anyOf:
            - type: integer
            - type: 'null'
          title: Minutesduration
          examples:
            - 30
        serviceType:
          anyOf:
            - type: string
            - type: 'null'
          title: Servicetype
          examples:
            - cardiology
        appointmentType:
          anyOf:
            - type: string
            - type: 'null'
          title: Appointmenttype
          examples:
            - follow-up
        reason:
          anyOf:
            - type: string
            - type: 'null'
          title: Reason
          examples:
            - Follow-up
        description:
          anyOf:
            - type: string
            - type: 'null'
          title: Description
          examples:
            - Routine check
        createdAt:
          type: string
          title: Createdat
          description: ISO-8601 timestamp when the appointment was created.
      type: object
      required:
        - id
        - status
        - createdAt
      title: AppointmentResponse
      description: A single appointment. `id` is the stable public id (apt_...).
      examples:
        - appointmentType: follow-up
          consultationInternalId: CONSULT-12345
          createdAt: '2026-08-28T12:00:00.000Z'
          end: '2026-09-01T14:30:00.000Z'
          id: apt_a1b2c3d4e5f6g7h8
          minutesDuration: 30
          reason: Follow-up
          serviceType: cardiology
          start: '2026-09-01T14:00:00.000Z'
          status: booked
    ErrorResponse:
      description: Standardized error response envelope.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetailWithRequestId'
      required:
        - error
      title: ErrorResponse
      type: object
    ErrorDetailWithRequestId:
      description: >-
        Top-level error object: :class:`ErrorDetail` plus the request
        correlation id.


        Kept as a subclass rather than a field on ``ErrorDetail`` because
        ``ErrorDetail`` is

        also the per-item error shape inside the batch account-creation response

        (``BatchAccountResult.error``), which is serialized with nulls included.
        Adding the

        field there would publish ``"requestId": null`` on an HTTP 200, and
        there is only

        ever one request id per batch anyway -- batch callers read the
        ``X-Request-ID``

        response header.
      properties:
        type:
          description: Broad error category for high-level handling.
          examples:
            - invalid_request_error
          title: Type
          type: string
        code:
          description: Machine-readable error code. Clients should switch on this value.
          examples:
            - parameter_invalid
          title: Code
          type: string
        message:
          description: Human-readable error message ending with a period.
          examples:
            - >-
              idCountry must be a valid country name, ISO alpha-2, or ISO
              alpha-3 code.
          title: Message
          type: string
        param:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: The request field that caused the error, if applicable.
          examples:
            - idCountry
          title: Param
        details:
          anyOf:
            - additionalProperties: true
              type: object
            - type: 'null'
          default: null
          description: Optional structured, machine-readable context for the error.
          examples:
            - pendingConsultations:
                - sessionId: abc123
                  url: https://...
          title: Details
        requestId:
          anyOf:
            - type: string
            - type: 'null'
          default: null
          description: >-
            Unique id for this request, identical to the X-Request-ID response
            header. Quote it when contacting support.
          examples:
            - 3f9a1c2e-5b7d-4a21-9f0c-8e6d4b2a1c30
          title: Requestid
      required:
        - type
        - code
        - message
      title: ErrorDetailWithRequestId
      type: object
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      description: API key passed as a Bearer token

````