> ## Documentation Index > Fetch the complete documentation index at: https://docs.healos.ai/llms.txt > Use this file to discover all available pages before exploring further. # Create an appointment ## OpenAPI ````yaml /openapi/ext-api-v1.json post /appointments openapi: 3.0.0 info: title: Healos External API version: 1.0.0 description: >- External API for managing patients, documents, and appointments, listing providers, and for pulling clinical notes (with transcript and patient context). servers: - url: https://api.healos.ai/ext-api/v1 description: Production - url: http://localhost:8787/ext-api/v1 description: Local development security: - ApiKeyAuth: [] paths: /appointments: post: tags: - Appointments summary: Create an appointment requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateAppointmentBody' responses: '201': description: Appointment created content: application/json: schema: $ref: '#/components/schemas/AppointmentResponse' '400': description: Validation error content: application/json: schema: $ref: '#/components/schemas/ValidationError' '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/Error' '403': description: Insufficient scope content: application/json: schema: $ref: '#/components/schemas/Error' '404': description: Patient not found content: application/json: schema: $ref: '#/components/schemas/Error' '409': description: external_id already in use content: application/json: schema: $ref: '#/components/schemas/ConflictResponse' '429': description: Rate limit exceeded content: application/json: schema: $ref: '#/components/schemas/RateLimitError' components: schemas: CreateAppointmentBody: type: object properties: patient_id: type: string pattern: ^\d+$ description: Patient ID (numeric) example: '1743552000000' provider_id: type: string minLength: 1 description: >- Optional internal provider id (see GET /providers) to assign this appointment to. Must be a provider in your organization. Defaults to the provider that owns the API key. example: aaaaaaa1-0000-0000-0000-000000000001 appointment_type: type: string description: Type of appointment example: Initial Evaluation visit_type: type: string enum: - Telehealth - In-Person - Both - Other example: Telehealth start_at: type: string format: date-time description: ISO 8601 datetime example: '2026-04-15T14:00:00.000Z' duration_minutes: type: number minimum: 1 description: Duration in minutes example: 50 notes: type: string example: New patient intake. Please complete forms beforehand. status: type: string enum: - SCHEDULED - COMPLETED - CANCELLED - NO_SHOW default: SCHEDULED example: SCHEDULED repeat_rule: type: object properties: frequency: type: string enum: - DAILY - WEEKLY - MONTHLY example: WEEKLY interval: type: number default: 1 example: 1 end_date: type: string example: '2026-07-15' required: - frequency description: Recurrence rule external_id: type: string minLength: 1 maxLength: 255 description: >- Optional caller-supplied identifier. Unique per organization; immutable once set. Duplicate values return 409 with the existing record. example: PARTNER-APPT-789 required: - patient_id - appointment_type - visit_type - start_at - duration_minutes AppointmentResponse: type: object properties: data: $ref: '#/components/schemas/Appointment' required: - data ValidationError: type: object properties: error: type: string details: type: object additionalProperties: type: array items: type: string required: - error Error: type: object properties: error: type: string required: - error ConflictResponse: type: object properties: error: type: string example: external_id already in use existing: type: object properties: id: type: string description: HealOS internal ID of the existing record external_id: type: string description: The conflicting external_id required: - id - external_id required: - error - existing RateLimitError: type: object properties: error: type: string example: Rate limit exceeded. Please retry after the window resets. required: - error Appointment: type: object properties: id: type: string format: uuid example: f47ac10b-58cc-4372-a567-0e02b2c3d479 patient_id: type: string description: Patient ID example: '1743552000000' patient_name: type: string example: Maria Santos provider_id: type: string nullable: true description: >- Internal id of the provider this appointment belongs to (see GET /providers). example: aaaaaaa1-0000-0000-0000-000000000001 provider_name: type: string nullable: true description: Provider display name example: Dr. Alice Nguyen provider_npi: type: string nullable: true description: Provider's individual (type-I) NPI, when recorded. example: '1234567890' appointment_type: type: string example: Initial Evaluation visit_type: type: string enum: - Telehealth - In-Person - Both - Other example: Telehealth start_at: type: string description: ISO 8601 datetime example: '2026-04-15T14:00:00.000Z' duration_minutes: type: number example: 50 notes: type: string nullable: true example: New patient intake. Please complete forms beforehand. status: type: string enum: - SCHEDULED - COMPLETED - CANCELLED - NO_SHOW example: SCHEDULED created_at: type: string description: ISO 8601 datetime example: '2026-04-01T10:00:00.000Z' updated_at: type: string description: ISO 8601 datetime example: '2026-04-01T10:00:00.000Z' repeat_rule: $ref: '#/components/schemas/RepeatRule' external_id: type: string nullable: true description: Caller-supplied external identifier (immutable once set) example: PARTNER-APPT-789 required: - id - patient_id - patient_name - provider_id - provider_name - provider_npi - appointment_type - visit_type - start_at - duration_minutes - notes - status - created_at - updated_at - repeat_rule - external_id RepeatRule: type: object nullable: true properties: frequency: type: string example: WEEKLY interval: type: number example: 1 end_date: type: string nullable: true example: '2026-07-15' required: - frequency - interval - end_date description: Recurrence rule, if any securitySchemes: ApiKeyAuth: type: apiKey in: header name: X-API-Key description: API key obtained from /api/v1/ext-api-keys ````