> ## 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.

# Listar citas (agenda)

> Lista las citas visibles para el llamador, ordenadas por hora de inicio, con filtros de rango de inicio y estado, paginadas.



## OpenAPI

````yaml /es/scribe-api/openapi.json get /v1/appointments
openapi: 3.1.0
info:
  title: Scribe Public API
  description: >-
    API REST externa para integración con la plataforma Telepatia. Autentíquese
    con claves API, establezca el contexto de consulta y consulte sesiones de
    scribe.
  version: 0.1.0
servers:
  - url: https://scribe-api.telepatia.ai
    description: Production
security:
  - BearerAuth: []
paths:
  /v1/appointments:
    get:
      tags:
        - Appointments
      summary: Listar citas (agenda)
      description: >-
        Lista las citas visibles para el llamador, ordenadas por hora de inicio,
        con filtros de rango de inicio y estado, paginadas.
      operationId: api_appointment_list_v1_appointments_get
      parameters:
        - name: startFrom
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: ISO-8601 lower bound on start (inclusive).
            title: Startfrom
          description: ISO-8601 lower bound on start (inclusive).
        - name: startTo
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: ISO-8601 upper bound on start (inclusive).
            title: Startto
          description: ISO-8601 upper bound on start (inclusive).
        - name: status
          in: query
          required: false
          schema:
            anyOf:
              - type: array
                items:
                  $ref: '#/components/schemas/AppointmentStatus'
              - type: 'null'
            description: Filter by one or more statuses (repeatable).
            title: Status
          description: Filter by one or more statuses (repeatable).
        - name: consultationInternalId
          in: query
          required: false
          schema:
            anyOf:
              - type: string
              - type: 'null'
            description: Filter to the booking that carries this consultation id.
            title: Consultationinternalid
          description: Filter to the booking that carries this consultation id.
        - name: page
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            description: Page number (1-based).
            default: 1
            title: Page
          description: Page number (1-based).
        - name: limit
          in: query
          required: false
          schema:
            type: integer
            maximum: 50
            minimum: 1
            description: Number of items per page.
            default: 20
            title: Limit
          description: Number of items per page.
      responses:
        '200':
          description: Respuesta exitosa
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppointmentListResponse'
        '400':
          description: >-
            Solicitud incorrecta — parámetros inválidos, fallos de validación o
            campos faltantes.
          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: No autorizado — clave API faltante o inválida.
          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'
        '503':
          description: Servicio no disponible — una dependencia externa no está disponible.
          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:
    AppointmentStatus:
      type: string
      enum:
        - proposed
        - pending
        - booked
        - arrived
        - checkedIn
        - fulfilled
        - cancelled
        - noshow
        - waitlist
        - enteredInError
      title: AppointmentStatus
      description: >-
        FHIR appointment status set (mirrors datalayer AppointmentStatus). Used
        to

        validate the agenda `status` filter, so a typo is a clean 400, not a
        5xx.
    AppointmentListResponse:
      properties:
        items:
          items:
            $ref: '#/components/schemas/AppointmentResponse'
          type: array
          title: Items
          description: Page of appointments.
        total:
          anyOf:
            - type: integer
            - type: 'null'
          title: Total
          description: Total appointments matching the filter (null on later pages).
        page:
          type: integer
          title: Page
          description: Current page number (1-based).
        limit:
          type: integer
          title: Limit
          description: Number of items per page.
        totalPages:
          anyOf:
            - type: integer
            - type: 'null'
          title: Totalpages
          description: Total number of pages (null when the total is unknown).
        hasMore:
          type: boolean
          title: Hasmore
          description: Whether another page likely exists (accurate on every page).
      type: object
      required:
        - items
        - page
        - limit
        - hasMore
      title: AppointmentListResponse
      description: Paginated list of appointments (the agenda).
    ErrorResponse:
      description: Envoltorio estandarizado de respuesta de error.
      properties:
        error:
          $ref: '#/components/schemas/ErrorDetailWithRequestId'
      required:
        - error
      title: ErrorResponse
      type: object
    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
    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: Clave API enviada como token Bearer

````