breedr/API.md

# BREEDR API Documentation (v0.8.0)

Base URL: `/api`

All endpoints return JSON responses. Errors follow the format `{ "error": "message" }`.

---

## 1. Dogs (`/api/dogs`)

Manage individual dogs in the kennel.

### `GET /`
Get active kennel dogs.
- **Query Params**:
  - `include_external=1`: Include external dogs (studs/others)
  - `external_only=1`: Only show external dogs
- **Response**: Array of [Dog](#dog-object) objects with `sire` and `dam` attached.

### `GET /:id`
Get single dog details.
- **Response**: [Dog](#dog-object) object including `sire`, `dam`, and `offspring` array.

### `POST /`
Create a new dog.
- **Body**: See [Dog](#dog-object) fields. `name`, `breed`, `sex` are required.
- **Response**: The created Dog object.

### `PUT /:id`
Update an existing dog.
- **Body**: Dog fields to update.
- **Response**: The updated Dog object.

### `DELETE /:id`
Permanently delete a dog and its related records (health, heat, parents).
- **Response**: `{ "success": true, "message": "..." }`

### `POST /:id/photos`
Upload a photo for a dog.
- **Form-Data**: `photo` (file)
- **Response**: `{ "url": "...", "photos": [...] }`

### `DELETE /:id/photos/:photoIndex`
Delete a specific photo from a dog's photo array.
- **Response**: `{ "photos": [...] }`

---

## 2. Litters (`/api/litters`)

Manage breeding litters and puppy logs.

### `GET /`
Get all litters.
- **Response**: Array of [Litter](#litter-object) objects with sire/dam names and puppies.

### `GET /:id`
Get single litter details.
- **Response**: [Litter](#litter-object) object.

### `POST /`
Create a new litter.
- **Body**: `sire_id`, `dam_id`, `breeding_date` (required), `whelping_date`, `puppy_count`, `notes`.
- **Response**: The created Litter object.

### `PUT /:id`
Update litter details.

### `POST /:id/puppies/:puppyId`
Link a dog to a litter as a puppy.
- **Side Effect**: Automatically sets the litter's sire and dam as the puppy's parents.

### `DELETE /:id/puppies/:puppyId`
Remove a puppy from a litter (sets `litter_id` to NULL).

### `GET /:litterId/puppies/:puppyId/logs`
Get weight and health logs for a puppy.

### `POST /:litterId/puppies/:puppyId/logs`
Add a weight/health log entry.
- **Body**: `record_date` (required), `weight_oz`, `weight_lbs`, `notes`, `record_type`.

---

## 3. Health (`/api/health`)

Manage OFA clearances and veterinary records.

**Record types** (`record_type`): `ofa_clearance`, `vaccination`, `exam`, `surgery`, `medication`, `other`.

**Valid `test_type` values** (OFA clearances only): `hip_ofa`, `hip_pennhip`, `elbow_ofa`, `patella_ofa`, `heart_ofa`, `heart_echo`, `eye_caer`, `thyroid_ofa`.
> DNA is **not** a health test type — DNA panels are managed exclusively by the Genetics module (`/api/genetics`).

### `GET /dog/:dogId`
Get all health records for a dog.

### `GET /dog/:dogId/clearance-summary`
Get GRCA core clearance status (Hip, Elbow, Heart, Eyes).
- **Response**: `{ summary, grca_eligible, age_eligible, chic_number }`
- Only recurring tests (CAER eyes, advanced/echo cardiac) carry an `expires_at`; permanent certifications (hip, elbow, etc.) never report `expired`/`expiring_soon`.

### `GET /dog/:dogId/chic-eligible`
Check if a dog has all required CHIC tests.

### `GET /:id`
Get a single health record.

### `POST /`
Create health record.
- **Body**: `dog_id`, `record_type`, `test_date` (all required), plus optional `test_type`, `test_name`, `ofa_result`, `ofa_number`, `performed_by`, `expires_at`, `result`, `next_due`, `document_url`, `notes`.
- **Validation**: `test_type`, if present, must be one of the valid values above (else `400`).
- **Note**: `performed_by` is the single clinician field (the legacy `vet_name` column is deprecated).

### `PUT /:id`
Update an existing health record. Same body as `POST /` (minus `dog_id`).

### `DELETE /:id`
Delete a health record.
- **Response**: `{ "message": "Health record deleted successfully" }`

### `POST /upload`
Upload a supporting document (PDF or image, ≤ 15 MB) and get back a URL to store in a record's `document_url`. Record-agnostic — works before the record itself is saved.
- **Form-Data**: `document` (file)
- **Response**: `{ "url": "/uploads/..." }`

### `GET /dog/:dogId/cancer-history`
Get cancer-history records for a dog.

### `POST /cancer-history`
Add a cancer-history record.
- **Body**: `dog_id`, `cancer_type` (required), `age_at_diagnosis`, `age_at_death`, `cause_of_death`, `notes`.

---

## 4. Genetics (`/api/genetics`)

Manage DNA panel results and breeding risks.

### `GET /dog/:dogId`
Get the full genetic panel for a dog. Returns `tests` (actual records) and `panel` (full list including `not_tested` placeholders).

### `GET /pairing-risk?sireId=X&damId=Y`
Check genetic compatibility between two dogs.
- **Response**: `{ risks: [...], safe_to_pair: boolean }`

### `POST /`
Add a genetic test result.
- **Body**: `dog_id`, `marker`, `result` (clear|carrier|affected|not_tested).

---

## 5. Breeding (`/api/breeding`)

Track heat cycles and whelping projections.

### `GET /heat-cycles/active`
Get currently active heat cycles.

### `GET /heat-cycles/:id/suggestions`
Get optimal breeding window (days 9-15) and whelping projections.

### `POST /heat-cycles`
Log a new heat cycle. Dog must be female.

### `GET /whelping-calculator?breeding_date=YYYY-MM-DD`
Standalone tool to calculate expected whelping window.

---

## 6. Pedigree (`/api/pedigree`)

Advanced ancestry and COI calculations.

### `GET /:id?generations=N`
Get an interactive pedigree tree (ancestors). Default 5 generations.

### `GET /:id/descendants?generations=N`
Get a descendant tree. Default 3 generations.

### `POST /trial-pairing`
Calculate Coefficient of Inbreeding (COI) for a hypothetical mating.
- **Body**: `sire_id`, `dam_id`.
- **Response**: `{ coi, commonAncestors, directRelation, recommendation }`

---

## 7. Settings (`/api/settings`)

### `GET /`
Get kennel metadata (name, address, etc.).

### `PUT /`
Update kennel settings.

---

## Data Objects

### Dog Object
```json
{
  "id": 1,
  "name": "BREEDR Champion",
  "registration_number": "AKC123456",
  "breed": "Golden Retriever",
  "sex": "male",
  "birth_date": "2020-01-01",
  "color": "Golden",
  "microchip": "900123456789",
  "is_active": 1,
  "is_champion": 1,
  "is_external": 0,
  "photo_urls": ["/uploads/img.jpg"],
  "notes": "Excellent temperament",
  "sire": { "id": 10, "name": "Sire Name" },
  "dam": { "id": 11, "name": "Dam Name" }
}
```

### Litter Object
```json
{
  "id": 5,
  "sire_id": 1,
  "dam_id": 2,
  "breeding_date": "2023-01-01",
  "whelp_date": "2023-03-05",
  "total_count": 8,
  "puppies": [ ... ]
}
```