# Reptile Husbandry API
> Reptile-husbandry maths as an API, computed locally and deterministically — the keeper numbers behind a healthy vivarium, so the setup is right before the animal moves in. The enclosure endpoint turns an animal length and its habit into the minimum floor length, width and height: terrestrial snakes want a floor at least as long as the snake (a 48-inch corn snake → a 48 × 24 × 24 inch minimum, eight square feet of floor), arboreal species trade floor for height (an 18-inch chameleon → 27 × 18 × 36 inches, tall), and ground lizards and tortoises need far more floor than their body length. The uvb endpoint gives the UV-B target by Ferguson zone — the 1-to-4 classification from Baines et al. (2016) of how much sun a species basks in — returning the mean and basking UV-index ranges (zone 3 open baskers want a basking UVI of 2.9–7.4), and, if you pass a lamp UVI measured at a reference distance, an inverse-square estimate of the mounting distance for the right basking UVI. The feeding endpoint sizes prey from body weight and life stage: a meal of roughly 10–15 % of body weight, no wider than the animal, on an interval that lengthens with age — a 500 g adult snake takes a 40–60 g prey item every fortnight. Everything is computed locally and deterministically, so it is instant and private. Ideal for reptile-keeper and herpetoculture apps, pet-store and breeder tools, vivarium-planning calculators, and care-sheet sites. Pure local computation — no key, no third-party service, instant. Live, nothing stored. 3 compute endpoints. Educational husbandry estimates — not veterinary advice; research your exact species.

## 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/reptile-api/..."
```

## Pricing
- **Free** (Free) — 250 calls/Mo, 2 req/s
- **Starter** ($5/Mo) — 7,500 calls/Mo, 5 req/s
- **Pro** ($18/Mo) — 52,000 calls/Mo, 13 req/s
- **Mega** ($53/Mo) — 185,000 calls/Mo, 32 req/s

## Endpoints

### Reptile

#### `GET /v1/enclosure` — Minimum enclosure size

**Parameters:**
- `length_in` (query, required, string) — Animal total length in inches Example: `48`
- `type` (query, optional, string) — terrestrial_snake | arboreal_snake | terrestrial_lizard | arboreal_lizard | tortoise Example: `terrestrial_snake`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/reptile-api/v1/enclosure?length_in=48&type=terrestrial_snake"
```

**Response:**
```json
{
    "data": {
        "note": "Minimum enclosure, not ideal — bigger is always better. Terrestrial snakes want a floor at least as long as the snake; arboreal species trade floor for height; ground lizards and tortoises need far more floor than their body length. A solid temperature gradient end-to-end matters more than raw volume.",
        "inputs": {
            "type": "terrestrial_snake",
            "length_in": 48
        },
        "min_width_in": 24,
        "min_height_in": 24,
        "min_length_in": 48,
        "floor_area_sqft": 8
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:47.908Z",
        "request_id": "44c3e715-5814-4bcf-83ef-4dad1a041b00"
    },
    "status": "ok",
    "message": "Enclosure size",
    "success": true
}
```

#### `GET /v1/feeding` — Prey size and feeding interval

**Parameters:**
- `body_weight_g` (query, required, string) — Body weight in grams Example: `500`
- `life_stage` (query, optional, string) — hatchling | juvenile | subadult | adult Example: `adult`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/reptile-api/v1/feeding?body_weight_g=500&life_stage=adult"
```

**Response:**
```json
{
    "data": {
        "note": "A meal of roughly 10–15 % of body weight, no wider than the widest part of the animal, every interval shown — younger animals eat smaller meals more often. Power-feeding to grow fast shortens lifespans; a lean, slow-grown reptile is a healthy one. Always provide a warm side for digestion.",
        "inputs": {
            "life_stage": "adult",
            "body_weight_g": 500
        },
        "prey_weight_max_g": 60,
        "prey_weight_min_g": 40,
        "feeding_interval_days": 14
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.000Z",
        "request_id": "0639a817-3c38-4670-b427-1f57abdf4a05"
    },
    "status": "ok",
    "message": "Feeding",
    "success": true
}
```

#### `GET /v1/uvb` — UV-B Ferguson-zone target

**Parameters:**
- `ferguson_zone` (query, required, string) — Ferguson zone 1-4 Example: `3`
- `lamp_uvi_at_distance` (query, optional, string) — Measured lamp UVI at the reference distance Example: `10`
- `lamp_reference_in` (query, optional, string) — Reference distance in inches (default 12) Example: `12`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/reptile-api/v1/uvb?ferguson_zone=3&lamp_uvi_at_distance=10&lamp_reference_in=12"
```

**Response:**
```json
{
    "data": {
        "note": "Ferguson zones (Baines et al. 2016) classify reptiles by how much sun they bask in. Aim the basking-spot UV index inside the basking range, with shade so the animal can self-regulate. Use a Solarmeter 6.5 to verify — bulb output drifts and decays over a year.",
        "inputs": {
            "ferguson_zone": 3
        },
        "distance_note": "Inverse-square estimate from your measured UVI at the reference distance — fluorescent tubes fall off more gently than a point source, so treat it as a starting point and verify with a meter.",
        "mean_uvi_range": [
            1,
            2.6
        ],
        "zone_description": "open / partial-sun basker",
        "basking_uvi_range": [
            2.9,
            7.4
        ],
        "target_basking_uvi": 5.15,
        "suggested_mount_distance_in": 16.7
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.086Z",
        "request_id": "e89b6ffd-0f8e-4a8b-ae29-87e44201c6eb"
    },
    "status": "ok",
    "message": "UVB Ferguson zone",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "notes": "Lengths in inches, weights in grams. Enclosure multipliers are minimums (bigger is better). Ferguson zones 1-4 per Baines et al. 2016; verify UVI with a meter. Educational — not veterinary advice; research your exact species.",
        "service": "reptile-api",
        "endpoints": {
            "GET /v1/uvb": "Ferguson-zone target UV index, with an optional lamp mounting-distance estimate.",
            "GET /v1/meta": "This document.",
            "GET /v1/feeding": "Prey weight range and feeding interval from body weight and life stage.",
            "GET /v1/enclosure": "Minimum enclosure length/width/height from the animal's length and habit."
        },
        "description": "Reptile-husbandry maths: minimum enclosure size by length, UV-B Ferguson-zone targets, and feeder/prey sizing with frequency."
    },
    "meta": {
        "timestamp": "2026-06-06T15:30:48.164Z",
        "request_id": "13e6dc14-42d3-49ca-9347-4c17faa37b9c"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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