# Tebaba Public API

Tebaba's structured doctor data, accessible without authentication.
Built for AI crawlers (ChatGPT, Claude, Perplexity, Gemini) and partner
integrations. The same data is rendered as HTML on tebaba.io —
this is just the machine-readable shape.

## Endpoints

### GET /api/public/doctors
Paginated list of every active doctor.

Query params:
  - specialty={slug}  filter to a specialty (e.g. pediatrics)
  - hospital={slug}   filter to a hospital
  - area={area}       filter by hospital area (case-insensitive)
  - locale=en|ar      include only one locale's text fields (default: both)
  - page=N            0-indexed (default: 0)
  - pageSize=N        1-100 (default: 50)

Response shape:
  {
    "pagination": { "page", "pageSize", "total", "totalPages" },
    "filters": { "specialty", "hospital", "area", "locale" },
    "doctors": [Doctor]
  }

### GET /api/public/doctors/{slug}
Single doctor by slug. 404 if not found or inactive.

## Doctor object

  slug                  string         URL slug
  url_en / url_ar       string         Human-friendly profile URL
  name_en / name_ar     string         Doctor name in each locale
  title_en / title_ar   string|null    Professional title
  bio_en / bio_ar       string|null    Long-form biography
  qualifications_*      string|null    Credentials (MD, FRCS, etc.)
  scope_of_service_*    string|null    Procedures / conditions treated
  languages             string[]       Languages spoken
  years_of_experience   integer|null   Years practising
  photo_url             string|null    Headshot URL (CDN)
  trust_score           number|null    Patient Trust Index 0-100
  trust_score_out_of_5  number|null    Normalised 0-5 (UI parity)
  review_count          integer        Approved patient reviews count
  specialty             { slug, name_en, name_ar }
  hospital              { slug, name_en, name_ar, area, governorate }
  subspecialties        Subspecialty[] with is_primary flag

## Rate limiting

No per-IP rate limit. Cached at the edge for 1 hour (s-maxage=3600).
If you're crawling at high volume, prefer reading our sitemap
(https://www.tebaba.io/sitemap.xml) and fetching per-slug rather than
hammering the list endpoint with high pageSize.

## What's NOT exposed

  - Patient identifying info (we don't have it)
  - Per-review free-text comments (those live on doctor HTML pages
    with their own JSON-LD Review schema — see /api/public/README/links)
  - Internal admin fields, audit history, doctor phone numbers

## Source of truth

Data comes from Tebaba's production Supabase. Pipeline: hospital admin /
clinic staff submits → Tebaba admin reviews → PTI computed from
verified reviews → row goes live.

## Schema.org references on tebaba.io HTML pages

Every public page also emits JSON-LD that AI systems can consume
without hitting this endpoint:

  - Doctor:    Physician + FAQPage + up to 3 Review + Breadcrumb
  - Specialty: MedicalSpecialty + ItemList + FAQPage + Breadcrumb
  - Hospital:  MedicalBusiness + MedicalClinic + ItemList + FAQPage + Breadcrumb

See https://www.tebaba.io/llms-full.txt for the full catalogue.