breedr/API.md

BREEDR API Documentation (v0.8.1)

Base URL: /api

All endpoints return JSON responses. Errors follow the format { "error": "message" }. Validation failures return 400, missing resources return 404.

---

1. Dogs (/api/dogs)

Manage individual dogs in the kennel.

GET /

Get active kennel dogs (paginated).

• Query Params:
  • include_external=1: Include external dogs (studs/others)
  • external_only=1: Only show external dogs
  • page (default 1), limit (default 50, max 200)
  • search: Filter by name or registration number
  • sex: male | female
• Response: { "data": [Dog...], "total", "page", "limit", "stats": { "total", "males", "females" } } — each Dog has sire and dam attached.

GET /all

Get all active dogs (kennel + external, unpaginated). Used for dropdowns/pairing/pedigree.

GET /:id

Get single dog details.

• Response: Dog object including sire, dam, and offspring array. 404 if not found.

POST /

Create a new dog.

• Body: See Dog fields. name, breed, sex are required.
• Validation: If sire_id/dam_id are provided they must reference an existing dog of the correct sex (sire → male, dam → female), else 400. The dog + parent links are written in a single transaction.
• Response: The created Dog object (201).

PUT /:id

Update an existing dog.

• Body: Dog fields to update.
• Validation: 404 if the dog doesn't exist. Same sire/dam checks as POST /, plus a dog cannot be its own parent.
• Response: The updated Dog object.

DELETE /:id

Permanently delete a dog and its related records (health, heat cycles, parent links) in a single transaction.

• Response: { "success": true, "message": "..." } — 404 if not found.

POST /:id/photos

Upload a photo for a dog (JPEG/PNG/GIF/WebP, ≤ 10 MB).

• Form-Data: photo (file)
• Response: { "url": "...", "photos": [...] }

DELETE /:id/photos/:photoIndex

Delete a specific photo from a dog's photo array.

• Validation: 400 if photoIndex is not an integer within the photo array's bounds.
• Response: { "photos": [...] }

---

2. Litters (/api/litters)

Manage breeding litters and puppy logs.

GET /

Get all litters (paginated).

• Query Params: page (default 1), limit (default 50)
• Response: { "data": [Litter...], "total", "page", "limit" } with sire/dam names and puppies attached.

GET /:id

Get single litter details.

• Response: Litter object.

POST /

Create a new litter.

• Body: sire_id, dam_id, breeding_date (required), whelping_date, puppy_count, notes.
• Validation: Sire must be male, dam must be female.
• Response: The created Litter object.

PUT /:id

Update litter details (breeding_date, whelping_date, puppy_count, notes — parents cannot change).

DELETE /:id

Delete a litter. Puppies are unlinked (their dog records are kept).

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 (stored in health_records; weights serialized into description).

• Body: record_date (required), weight_oz, weight_lbs, notes, record_type (default weight_log).

DELETE /:litterId/puppies/:puppyId/logs/:logId

Delete a weight/health log entry.

---

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 }

GET /:id

Get a single genetic test record.

POST /

Add a genetic test result.

• Body: dog_id, marker, result (clear|carrier|affected|not_tested), plus optional test_provider, test_date, document_url, notes.

PUT /:id

Update a genetic test result.

DELETE /:id

Delete a genetic test result.

---

5. Breeding (/api/breeding)

Track heat cycles and whelping projections.

GET /heat-cycles

Get all heat cycles (with dog info). Optional ?year=YYYY&month=M filter.

GET /heat-cycles/active

Get currently active heat cycles.

GET /heat-cycles/dog/:dogId

Get all heat cycles for a specific dog.

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.

• Body: dog_id, start_date (required), end_date, breeding_date, breeding_successful, notes.

PUT /heat-cycles/:id

Update a heat cycle (same body as POST, minus dog_id).

DELETE /heat-cycles/:id

Delete a heat cycle.

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. (POST /coi is an alias.)

• Body: sire_id, dam_id.
• Response: { coi, commonAncestors, directRelation, recommendation }

GET /:id/coi

Get the COI for an existing dog (computed from its actual parents).

GET /relations/:sireId/:damId

Check the direct relationship between two dogs (parent/offspring, siblings, etc.).

GET /:id/cancer-lineage

Cancer history aggregated across a dog's lineage.

---

7. Settings (/api/settings)

GET /

Get kennel metadata (name, address, etc.).

PUT /

Update kennel settings.

---

Data Objects

Dog Object

{
  "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

{
  "id": 5,
  "sire_id": 1,
  "dam_id": 2,
  "sire_name": "Sire Name",
  "dam_name": "Dam Name",
  "breeding_date": "2026-01-01",
  "whelping_date": "2026-03-05",
  "puppy_count": 8,
  "notes": null,
  "puppies": [ ... ],
  "actual_puppy_count": 8
}