Doctor Slots & Availability

External API for doctor weekly schedules, overrides, and generated appointment slots

Overview

For frontend and integration teams

Use these endpoints to read and update a doctor's availability configuration and to fetch generated slots for a given date. All routes live under /api/external.

Base URL

Use your backend host with the /api prefix, then /external/... for these routes

All calls use the same three auth headers as other external APIs. Paths below use the production host; swap the base for local development.

URL reference

Bases and paths used in this guide

API base

Production: https://server.nyraai.io/api
Local: http://127.0.0.1:5000/api

Doctor slots endpoints

GET
https://server.nyraai.io/api/external/doctors/:doctor_id/availability
Weekly schedule, overrides, slot length, fee
PUT
https://server.nyraai.io/api/external/doctors/:doctor_id/availability
Create or update availability (JSON body)
GET
https://server.nyraai.io/api/external/doctors/:doctor_id/slots
Query ?date=YYYY-MM-DD (optional; defaults to tomorrow)

Authentication

Required on every request

Send all three credentials together. If any one is missing or invalid, the API returns 401 Unauthorized.

x-api-key — external API key
x-api-secret — paired secret
Authorization: Bearer <hospital_token> — hospital token from key issuance (REST; not the WebSocket JWT)

Permissions

Scopes required on the API key

`doctor_slots:read`

GET availability and GET generated slots

`doctor_slots:write`

PUT availability (create or update schedule)

Existing keys with legacy scopes may still pass checks because the middleware supports permission aliases. New integrations should request doctor_slots:read and doctor_slots:write explicitly.

API endpoints

GEThttps://server.nyraai.io/api/external/doctors/:doctor_id/availability

Fetch weekly schedule, slot duration, date overrides, consultation fee, and metadata for a doctor.

Permission: doctor_slots:read

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Response

{
  "success": true,
  "data": {
    "doctor_id": "8f42f1a3-7d11-4ee0-8f54-7d7be7bdf2d6",
    "schedule": {
      "Monday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Tuesday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Wednesday": { "is_available": false, "slots": [] },
      "Thursday": { "is_available": true, "slots": [{ "start": "14:00", "end": "18:00" }] },
      "Friday": { "is_available": true, "slots": [{ "start": "10:00", "end": "16:00" }] },
      "Saturday": { "is_available": false, "slots": [] },
      "Sunday": { "is_available": false, "slots": [] }
    },
    "slot_duration_minutes": 30,
    "consultation_fee": 500,
    "currency": "INR",
    "overrides": {
      "2026-04-25": {
        "is_available": true,
        "slots": [{ "start": "11:00", "end": "15:00" }]
      }
    },
    "has_schedule": true,
    "updated_at": "2026-04-21T06:12:10.000Z"
  }
}

PUThttps://server.nyraai.io/api/external/doctors/:doctor_id/availability

Create or replace the doctor availability schedule used for slot generation. Supports full replace or partial updates when a schedule already exists.

Permission: doctor_slots:write

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Content-Typerequired

application/json

Request Body

{
  "schedule": {
    "Monday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }, { "start": "14:00", "end": "18:00" }] },
    "Tuesday": { "is_available": true, "slots": [{ "start": "09:00", "end": "17:00" }] },
    "Wednesday": { "is_available": true, "slots": [{ "start": "09:00", "end": "17:00" }] },
    "Thursday": { "is_available": true, "slots": [{ "start": "09:00", "end": "17:00" }] },
    "Friday": { "is_available": true, "slots": [{ "start": "09:00", "end": "17:00" }] },
    "Saturday": { "is_available": false, "slots": [] },
    "Sunday": { "is_available": false, "slots": [] }
  },
  "slot_duration_minutes": 30,
  "consultation_fee": 650,
  "overrides": {
    "2026-04-30": { "is_available": false, "slots": [] },
    "2026-05-02": { "is_available": true, "slots": [{ "start": "12:00", "end": "16:00" }] }
  }
}

Response

{
  "success": true,
  "message": "Doctor availability updated successfully",
  "data": {
    "doctor_id": "8f42f1a3-7d11-4ee0-8f54-7d7be7bdf2d6",
    "schedule": {
      "Monday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Tuesday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Wednesday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Thursday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Friday": { "is_available": true, "slots": [{ "start": "09:00", "end": "13:00" }] },
      "Saturday": { "is_available": false, "slots": [] },
      "Sunday": { "is_available": false, "slots": [] }
    },
    "slot_duration_minutes": 30,
    "overrides": {},
    "consultation_fee": 650,
    "currency": "INR",
    "updated_at": "2026-04-21T06:20:00.000Z"
  }
}

GEThttps://server.nyraai.io/api/external/doctors/:doctor_id/slots

Return generated appointment slots for a doctor on a date, with booked / free / locked counts. If date is omitted, the API defaults to tomorrow.

Permission: doctor_slots:read

Headers

x-api-keyrequired

API key

x-api-secretrequired

API secret

Authorizationrequired

Bearer hospital token

Query Parameters

date(date)

Target date YYYY-MM-DD (optional; defaults to tomorrow)

Response

{
  "success": true,
  "data": {
    "doctor_id": "8f42f1a3-7d11-4ee0-8f54-7d7be7bdf2d6",
    "date": "2026-04-22",
    "is_on_leave": false,
    "leave_reason": null,
    "total_slots": 6,
    "booked": 1,
    "free": 4,
    "locked": 1,
    "slots": [
      {
        "start": "2026-04-22T03:30:00.000Z",
        "end": "2026-04-22T04:00:00.000Z",
        "display_time": "09:00 AM",
        "status": "AVAILABLE",
        "available": true
      },
      {
        "start": "2026-04-22T04:00:00.000Z",
        "end": "2026-04-22T04:30:00.000Z",
        "display_time": "09:30 AM",
        "status": "BOOKED",
        "available": false
      }
    ],
    "consultation_fee": 650,
    "currency": "INR"
  }
}

Update modes (PUT availability)

Full vs partial body

1. Full update

Send a complete schedule for all seven days to create or replace the schedule. You may include slot_duration_minutes, consultation_fee, and overrides in the same request.

2. Partial update

When a schedule already exists, you may send only the fields you want to change (for example only consultation_fee, only overrides, or only slot_duration_minutes). If the doctor has no schedule yet, partial updates are rejected — send a full schedule first.

Partial body examples

Fee only:

{
  "consultation_fee": 700
}

Overrides only:

{
  "overrides": {
    "2026-05-12": {
      "is_available": true,
      "slots": [{ "start": "10:00", "end": "14:00" }]
    }
  }
}

Slot duration only:

{
  "slot_duration_minutes": 15
}

Validation rules (PUT availability)

doctor_id must be a UUID.
At least one of: schedule, slot_duration_minutes, overrides, consultation_fee.
slot_duration_minutes must be one of: 15, 20, 30, 45, 60.
Day slot times use 24-hour HH:MM.
For each slot, end must be greater than start.
Slots must not overlap within the same day.
A full schedule must include all seven weekdays.
overrides keys must be dates in YYYY-MM-DD.

Common errors

400 — invalid doctor_id, invalid date, or validation error (see message and optional details).

404 — doctor not found within the API key scope (hospital / branch).

401 — missing or mismatched credentials.

Integration notes

Branch-scoped API keys can only access doctors in that branch.
Slot generation uses schedule, overrides, leave, existing bookings, and lock windows.
Each slot includes available (derived from status === "AVAILABLE") for simple UI binding.
Validate HH:MM and non-overlapping ranges client-side before calling PUT to reduce round trips.

Fetch examples (JavaScript)

Uses https://server.nyraai.io/api — swap host for local dev

Shared helper + three calls

const API_BASE = "https://server.nyraai.io/api";

function externalHeaders({ apiKey, apiSecret, hospitalToken }) {
  return {
    "Content-Type": "application/json",
    "x-api-key": apiKey,
    "x-api-secret": apiSecret,
    Authorization: `Bearer ${hospitalToken}`,
  };
}

async function getDoctorAvailability(doctorId, auth) {
  const res = await fetch(
    `${API_BASE}/external/doctors/${doctorId}/availability`,
    { method: "GET", headers: externalHeaders(auth) }
  );
  if (!res.ok) throw await res.json();
  return res.json();
}

async function updateDoctorAvailability(doctorId, payload, auth) {
  const res = await fetch(
    `${API_BASE}/external/doctors/${doctorId}/availability`,
    {
      method: "PUT",
      headers: externalHeaders(auth),
      body: JSON.stringify(payload),
    }
  );
  if (!res.ok) throw await res.json();
  return res.json();
}

async function getDoctorSlots(doctorId, date, auth) {
  const query = date ? `?date=${encodeURIComponent(date)}` : "";
  const res = await fetch(
    `${API_BASE}/external/doctors/${doctorId}/slots${query}`,
    { method: "GET", headers: externalHeaders(auth) }
  );
  if (!res.ok) throw await res.json();
  return res.json();
}

cURL quick checks

# Get availability
curl -s "https://server.nyraai.io/api/external/doctors/DOCTOR_UUID/availability" \
  -H "x-api-key: nyra_..." \
  -H "x-api-secret: ..." \
  -H "Authorization: Bearer <hospital_token>"

# Get slots for a date
curl -s "https://server.nyraai.io/api/external/doctors/DOCTOR_UUID/slots?date=2026-04-22" \
  -H "x-api-key: nyra_..." \
  -H "x-api-secret: ..." \
  -H "Authorization: Bearer <hospital_token>"