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.

### `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 }`

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

### `POST /`
Create health record.
- **Body**: `dog_id`, `record_type`, `test_date` (required), `test_type`, `test_name`, `ofa_result`, `ofa_number`, etc.

---

## 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": [ ... ]
}
```