# Egg Incubation API
> Egg-incubation maths as an API, computed locally and deterministically — the hatch timeline, conditions and brooder numbers a hatchery or backyard chicken-keeper raises a clutch by. The hatch endpoint turns the set day (day 0) into the schedule by species: it knows the incubation period — chicken 21 days, duck 28, quail 17, goose 30, turkey 28, Muscovy 35 and more — and gives the lockdown day, about three days before hatch, when you stop turning the eggs, raise the humidity and leave the lid shut; pass a custom incubation_days for anything else. The conditions endpoint gives the targets: a forced-air incubator at 99.5 °F (still-air a degree or two higher at the top of the eggs), with humidity around 45–55 % through incubation and 65–75 % at lockdown so the membrane stays soft. The brooder endpoint schedules the chicks after they hatch — 95 °F under the lamp in week one, dropping 5 °F a week until they reach room temperature around 70 °F and are feathered enough to leave it. Everything is computed locally and deterministically, so it is instant and private. Ideal for poultry, hatchery, homesteading and farm app developers, incubation-timer and brooder tools, and 4-H / education software. Pure local computation — no key, no third-party service, instant. Guidance — candle the eggs and watch the chicks. Live, nothing stored. 3 compute endpoints.

## Authentication
All requests require your oanor API key in the `x-oanor-key` header. Get one at https://www.oanor.com/developer/keys.

```bash
curl -H "x-oanor-key: oanor_live_…" "https://api.oanor.com/incubation-api/..."
```

## Pricing
- **Free** (Free) — 6,560 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 55,700 calls/Mo, 6 req/s
- **Pro** ($12/Mo) — 228,700 calls/Mo, 15 req/s
- **Mega** ($38/Mo) — 1,329,000 calls/Mo, 40 req/s

## Endpoints

### Incubation

#### `GET /v1/brooder` — Brooder temperature

**Parameters:**
- `week` (query, required, string) — Chick age in weeks Example: `1`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/incubation-api/v1/brooder?week=1"
```

**Response:**
```json
{
    "data": {
        "note": "Start chicks at 95 °F (35 °C) under the lamp in week 1 and lower 5 °F each week until you reach about 70 °F, then they're feathered enough for ambient. Watch the birds, not just the thermometer: huddled = too cold, spread to the edges = too hot.",
        "inputs": {
            "week": 1
        },
        "temperature_c": 35,
        "temperature_f": 95,
        "at_room_temperature": false
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.026Z",
        "request_id": "b78fecc8-e82b-4060-87d0-60f0cc0961a1"
    },
    "status": "ok",
    "message": "Brooder temp",
    "success": true
}
```

#### `GET /v1/conditions` — Temp & humidity

**Parameters:**
- `stage` (query, optional, string) — incubation or lockdown (default incubation) Example: `incubation`
- `still_air` (query, optional, string) — true for a still-air incubator Example: `false`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/incubation-api/v1/conditions?stage=incubation&still_air=false"
```

**Response:**
```json
{
    "data": {
        "note": "Forced-air incubators run 99.5 °F (37.5 °C); still-air 1–2 °F higher measured at the top of the eggs. Humidity ~45–55 % during incubation, raised to 65–75 % at lockdown so the membrane stays soft for the hatch. Ventilate more as hatch nears.",
        "inputs": {
            "stage": "incubation",
            "still_air": false
        },
        "humidity": "45–55 %",
        "temperature_c": 37.5,
        "temperature_f": 99.5
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.096Z",
        "request_id": "b37b4b2d-925e-44fc-9338-8468a2900b21"
    },
    "status": "ok",
    "message": "Incubation conditions",
    "success": true
}
```

#### `GET /v1/hatch` — Hatch timeline

**Parameters:**
- `species` (query, optional, string) — chicken, duck, quail, goose, turkey, muscovy, … Example: `chicken`
- `incubation_days` (query, optional, string) — Custom incubation period (days)
- `lockdown_days_before` (query, optional, string) — Days before hatch to lock down (default 3) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/incubation-api/v1/hatch?species=chicken&lockdown_days_before=3"
```

**Response:**
```json
{
    "data": {
        "note": "Day 0 is when you set the eggs. Turn them until lockdown — about 3 days before hatch — then stop turning, raise the humidity and don't open the incubator. Chicken 21 days, duck 28, quail 17, goose 30; bigger or waterfowl eggs take longer.",
        "inputs": {
            "species": "chicken",
            "incubation_days": 21,
            "lockdown_days_before": 3
        },
        "set_day": 0,
        "lockdown_day": 18,
        "incubation_days": 21,
        "stop_turning_day": 18,
        "expected_hatch_day": 21
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.177Z",
        "request_id": "fd557a3f-a38f-43c2-a443-d70a8abe2bc6"
    },
    "status": "ok",
    "message": "Hatch timeline",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Spec

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/incubation-api/v1/meta"
```

**Response:**
```json
{
    "data": {
        "notes": "Day 0 = set day; lockdown ~3 days before hatch. Chicken 21, duck 28, quail 17, goose 30, turkey 28 days. Forced-air 99.5 °F; brooder 95 °F week 1, −5 °F/week. Guidance — watch the birds and candle the eggs.",
        "service": "incubation-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/hatch": "Lockdown day and hatch day from the set day, by species or incubation days.",
            "GET /v1/brooder": "Brooder temperature for a chick's age in weeks.",
            "GET /v1/conditions": "Temperature and humidity for the incubation and lockdown stages."
        },
        "description": "Egg-incubation maths: hatch timeline by species, temperature & humidity targets, and the chick brooder temperature schedule."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:52.252Z",
        "request_id": "f6774f76-3960-4400-8c7c-e23fdb160147"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


---
Marketplace page: https://www.oanor.com/api/incubation-api
OpenAPI spec: https://www.oanor.com/api/incubation-api/openapi.json