> ## 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.
# Agendamentos
> Agende consultas e acompanhe pelo id público estável
Agendamentos são consultas marcadas. Crie uma reserva e, quando a consulta acontece, ela é vinculada ao agendamento automaticamente, então a reserva passa de `booked` para `fulfilled` sozinha.
Cada reserva carrega dois ids: o id público `apt_...` que devolvemos, e o `consultationInternalId` que você escolhe — o seu próprio id da consulta, e a chave que liga a reserva à visita.
Os agendamentos são **restritos à instituição da sua chave de API**. Uma chave `doctor` ou `institutional` pode agendar e atualizar; o escopo é aplicado no servidor, então você nunca passa um id de conta ou instituição. Escritas precisam de `scribe:write` e leituras de `scribe:read`.
## Agendar uma consulta
`POST /v1/appointments` exige `consultationInternalId` e um paciente. Referencie um paciente existente por `patientId` (`sp_...`) ou `internalCode`, ou envie a identidade em linha (`name`, `idCountry`, `idType`, `idValue`) para criá-lo. Campos de agenda opcionais: `start`, `end`, `minutesDuration`, `serviceType`, `appointmentType`, `reason`, `description`.
Reenviar o mesmo `consultationInternalId` atualiza a reserva no lugar (idempotente), desde que você reenvie com a chave dona do agendamento ou com a chave que o criou. Um novo agendamento começa como `booked`.
### Em qual agenda o agendamento entra
Um agendamento pertence a uma única conta, e só essa conta o vê. Por padrão o agendamento entra na agenda da chave que o criou, então uma chave de médico não precisa de nada a mais.
Uma chave institucional envia `doctorId` para agendar para um de seus médicos: um id público de conta (`acc_...`) ou o seu próprio `internalCode` para essa conta. O médico vê o agendamento, e a chave institucional que o criou também. Uma chave de médico não pode agendar na agenda de outro médico.
A agenda fica fixa na criação. Reenviar o mesmo `consultationInternalId` com outro `doctorId` atualiza os horários e o detalhe clínico, e deixa o agendamento onde está. Para mover um agendamento para outro médico, cancele e crie um novo.
Uma chave que não é dona do agendamento nem o criou não consegue reenviá-lo, e recebe 403. Se a sua instituição agenda com mais de uma chave, reenvie cada agendamento com a chave que o criou.
```bash theme={null}
curl -X POST https://scribe-api.telepatia.ai/v1/appointments \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"consultationInternalId": "CONSULT-12345",
"patientId": "sp_a1b2c3d4e5f6g7h8",
"start": "2026-09-01T14:00:00.000Z",
"serviceType": "cardiology"
}'
```
**Resposta:**
```json theme={null}
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "booked",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
```
Opcionalmente anexe um modelo — `medicalRecordConfigurationId` (`mrc_...`). Quando presente, o contexto de consulta do médico é preparado com antecedência, então fica pronto antes da visita. Use `scribeSessionModality` (`IN_PERSON`, `TELEMEDICINE` ou `DICTATION`) para registrar como a consulta acontece; só tem efeito quando um modelo é anexado.
## Listar agendamentos
`GET /v1/appointments` devolve a agenda visível para a sua chave, ordenada pela hora de início. Filtre por um intervalo de hora de início (`startFrom`, `startTo`), um ou mais valores de `status` (repetível), ou um `consultationInternalId`. Pagine com `page` (base 1) e `limit` (1–50, padrão 20).
```bash theme={null}
curl "https://scribe-api.telepatia.ai/v1/appointments?startFrom=2026-09-01T00:00:00.000Z&status=booked&limit=20" \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Resposta:**
```json theme={null}
{
"items": [
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "booked",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
],
"total": 42,
"page": 1,
"limit": 20,
"totalPages": 3,
"hasMore": true
}
```
`total` e `totalPages` só são calculados na **primeira página** — são `null` nas páginas seguintes para evitar uma varredura completa a cada clique. Use `hasMore` para paginar de forma confiável; é preciso em todas as páginas.
## Consultar um agendamento
`GET /v1/appointments/{appointment_id}` busca um único agendamento. O `{appointment_id}` pode ser o id público (`apt_...`) ou o `consultationInternalId` que você enviou ao criar. Devolve `404` se nenhum agendamento com esse id for visível para a sua chave.
```bash theme={null}
curl https://scribe-api.telepatia.ai/v1/appointments/apt_a1b2c3d4e5f6g7h8 \
-H "Authorization: Bearer YOUR_API_KEY"
```
**Resposta:**
```json theme={null}
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "booked",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
```
## Atualizar um agendamento
`PATCH /v1/appointments/{appointment_id}` cancela uma reserva ou a marca como falta, pelo id público (`apt_...`) ou `consultationInternalId`. Defina `status` como `cancelled` ou `noshow` — `fulfilled` é definido apenas pelo servidor quando a consulta acontece. Envie exatamente um entre `status` ou `scribeSessionId`. Devolve `404` se nenhum agendamento com esse id for visível para a sua chave.
```bash theme={null}
curl -X PATCH https://scribe-api.telepatia.ai/v1/appointments/apt_a1b2c3d4e5f6g7h8 \
-H "Authorization: Bearer YOUR_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"status": "cancelled"
}'
```
**Resposta:**
```json theme={null}
{
"id": "apt_a1b2c3d4e5f6g7h8",
"consultationInternalId": "CONSULT-12345",
"status": "cancelled",
"start": "2026-09-01T14:00:00.000Z",
"end": null,
"minutesDuration": null,
"serviceType": "cardiology",
"appointmentType": null,
"reason": null,
"description": null,
"createdAt": "2026-08-29T12:00:00.000Z"
}
```
Para reparar uma reserva cuja sessão não foi vinculada automaticamente na criação, envie `scribeSessionId` (o id `ss_...` da sessão) em vez de `status`. Ele anexa a sessão e marca a reserva como `fulfilled`. Isso só se aplica a uma reserva agendada e não vinculada; qualquer outro caso devolve `409`.