> ## 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. # Agendar una cita > Crea una consulta agendada (idempotente por consultationInternalId). Devuelve la cita con su id público estable (apt_). ## OpenAPI ````yaml /es/scribe-api/openapi.json post /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: post: tags: - Appointments summary: Agendar una cita description: >- Crea una consulta agendada (idempotente por consultationInternalId). Devuelve la cita con su id público estable (apt_). operationId: api_appointment_create_v1_appointments_post requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/AppointmentCreateRequest' example: consultationInternalId: CONSULT-12345 end: '2026-09-01T14:30:00.000Z' idCountry: COLOMBIA idType: CC idValue: '1024567890' medicalRecordConfigurationId: mrc_a1b2c3d4e5f6g7h8 name: John Doe reason: Follow-up scribeSessionModality: IN_PERSON serviceType: cardiology start: '2026-09-01T14:00:00.000Z' responses: '200': description: Respuesta exitosa 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: >- 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' '403': description: Prohibido — la clave API no puede realizar esta operación. 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: No encontrado — el recurso solicitado no existe. 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: Conflicto — el recurso ya existe o está en estado conflictivo. 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: 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: AppointmentCreateRequest: properties: consultationInternalId: type: string maxLength: 128 pattern: ^[a-zA-Z0-9_-]{1,128}$ title: Consultationinternalid description: >- Your own consultation id. The booking join key: the consultation that fulfils this appointment carries the same id. examples: - CONSULT-12345 name: anyOf: - type: string maxLength: 500 minLength: 1 - type: 'null' title: Name description: >- Patient full name. Part of the inline identity. Provide the full inline identity (name + idCountry + idType + idValue), or reference an existing patient with patientId or internalCode: exactly one of the three is required. examples: - John Doe idCountry: anyOf: - $ref: '#/components/schemas/IdCountry' - type: 'null' description: Patient document country. Part of the inline identity (see `name`). examples: - CO idType: anyOf: - $ref: '#/components/schemas/IdType' - type: 'null' description: Patient document type. Part of the inline identity (see `name`). examples: - CC idValue: anyOf: - type: string maxLength: 50 minLength: 1 - type: 'null' title: Idvalue description: Patient document number. Part of the inline identity (see `name`). examples: - '1024567890' patientId: anyOf: - type: string pattern: ^sp_[a-z0-9]{16}$ - type: 'null' title: Patientid description: >- Public id of an existing patient (sp_...). One of the three patient references (exactly one required): patientId, internalCode, or the inline identity. examples: - sp_a1b2c3d4e5f6g7h8 internalCode: anyOf: - type: string maxLength: 128 minLength: 1 - type: 'null' title: Internalcode description: >- Your own patient code, unique per institution. Looks up an existing patient; when none matches, the inline identity creates one. One of the three patient references (exactly one required). examples: - MRN-000123 doctorId: anyOf: - type: string maxLength: 128 minLength: 1 - type: 'null' title: Doctorid description: >- The doctor whose agenda this booking joins: an account publicId (acc_...) or your own internalCode for that account. Omit it to book into the calling key's own agenda. Naming another account requires an institutional key; a doctor key always books for itself. examples: - acc_a1b2c3d4e5f6g7h8 start: type: string maxLength: 64 title: Start description: ISO-8601 start. Required. examples: - '2026-09-01T14:00:00.000Z' end: type: string maxLength: 64 title: End description: ISO-8601 end. Required. examples: - '2026-09-01T14:30:00.000Z' minutesDuration: anyOf: - type: integer minimum: 1 - type: 'null' title: Minutesduration description: Duration in minutes. examples: - 30 serviceType: anyOf: - type: string maxLength: 256 - type: 'null' title: Servicetype examples: - cardiology appointmentType: anyOf: - type: string maxLength: 256 - type: 'null' title: Appointmenttype examples: - follow-up reason: anyOf: - type: string maxLength: 2000 - type: 'null' title: Reason examples: - Follow-up description: anyOf: - type: string maxLength: 2000 - type: 'null' title: Description examples: - Routine check medicalRecordConfigurationId: anyOf: - type: string maxLength: 128 - type: 'null' title: Medicalrecordconfigurationid description: >- Public id of a medical record configuration (mrc_...). When present, the consultation context is seeded. examples: - mrc_a1b2c3d4e5f6g7h8 scribeSessionModality: anyOf: - $ref: '#/components/schemas/ScribeSessionModality' - type: 'null' examples: - IN_PERSON notes: anyOf: - type: string maxLength: 10000 - type: 'null' title: Notes examples: - Patient reports headache pastMedicalHistory: anyOf: - type: string maxLength: 10000 - type: 'null' title: Pastmedicalhistory examples: - Hypertension type: object required: - consultationInternalId - start - end title: AppointmentCreateRequest description: >- Request body for creating (idempotent upsert) an appointment. The patient identity mirrors set-consultation-context: reference an existing patient by `patientId` (sp_) or `internalCode`, or send the inline identity to create one. Send a template (`medicalRecordConfigurationId`) to also seed the consultation context so it is ready before the visit. examples: - consultationInternalId: CONSULT-12345 end: '2026-09-01T14:30:00.000Z' idCountry: COLOMBIA idType: CC idValue: '1024567890' medicalRecordConfigurationId: mrc_a1b2c3d4e5f6g7h8 name: John Doe reason: Follow-up scribeSessionModality: IN_PERSON serviceType: cardiology start: '2026-09-01T14:00:00.000Z' - consultationInternalId: CONSULT-12345 end: '2026-09-01T14:30:00.000Z' medicalRecordConfigurationId: mrc_a1b2c3d4e5f6g7h8 patientId: sp_a1b2c3d4e5f6g7h8 start: '2026-09-01T14:00:00.000Z' - consultationInternalId: CONSULT-12345 end: '2026-09-01T14:30:00.000Z' internalCode: MRN-000123 medicalRecordConfigurationId: mrc_a1b2c3d4e5f6g7h8 start: '2026-09-01T14:00:00.000Z' - consultationInternalId: CONSULT-12345 doctorId: acc_a1b2c3d4e5f6g7h8 end: '2026-09-01T14:30:00.000Z' patientId: sp_a1b2c3d4e5f6g7h8 start: '2026-09-01T14:00:00.000Z' 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: Envoltorio estandarizado de respuesta de error. properties: error: $ref: '#/components/schemas/ErrorDetailWithRequestId' required: - error title: ErrorResponse type: object IdCountry: type: string enum: - AF - AX - AL - DZ - AS - AD - AO - AI - AQ - AG - AR - AM - AW - AU - AT - AZ - BS - BH - BD - BB - BY - BE - BZ - BJ - BM - BT - BO - BQ - BA - BW - BV - BR - IO - BN - BG - BF - BI - KH - CM - CA - CV - KY - CF - TD - CL - CX - CC - CO - KM - CK - CR - CI - HR - CU - CW - CY - CZ - CD - DK - DJ - DM - DO - EC - EG - SV - GQ - ER - EE - SZ - ET - FK - FO - FJ - FI - FR - GF - PF - TF - GA - GE - DE - GH - GI - GR - GL - GD - GP - GU - GT - GG - GN - GW - GY - HT - HM - VA - HN - HK - HU - IS - IN - ID - IQ - IE - IR - IM - IL - IT - JM - JP - JE - JO - KZ - KE - KI - XK - KW - KG - LA - LV - LB - LS - LR - LY - LI - LT - LU - MO - MG - MW - MY - MV - ML - MT - MH - MQ - MR - MU - YT - MX - FM - MD - MC - MN - ME - MS - MA - MZ - MM - NA - NR - NP - NL - NC - NZ - NI - NE - NG - NU - NF - KP - MP - 'NO' - OM - PK - PW - PA - PG - PY - CN - PE - PH - PN - PL - PT - PR - QA - CG - GM - RE - RO - RU - RW - BL - SH - KN - LC - MF - PM - VC - WS - SM - ST - SA - SN - RS - SC - SL - SG - SX - SK - SI - SB - SO - ZA - GS - KR - SS - ES - LK - PS - SD - SR - SJ - SE - CH - SY - TW - TJ - TH - MK - TL - TG - TK - TO - TT - TN - TR - TM - TC - TV - UG - UA - AE - GB - TZ - UM - US - UY - UZ - VU - VE - VN - VG - VI - WF - EH - YE - ZM - ZW title: IdCountry description: ISO 3166-1 alpha-2 country codes. Mirrors tanjiro's CountryCodes enum. IdType: type: string enum: - CC - TI - CE - RC - PASSPORT - RG - CPF - OTHER_DOC title: IdType description: Tipos de documento de identificación de paciente soportados. ScribeSessionModality: type: string enum: - IN_PERSON - TELEMEDICINE - DICTATION title: ScribeSessionModality description: Modalidades de sesión de scribe soportadas. 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 ````