# Animals API
> Dogs and cats as a single friendly API. List every dog breed and its sub-breeds and pull dog photos (e.g. breed=hound or hound/afghan, up to 10 at once), browse 60+ cat breeds with rich metadata — temperament, country of origin, life span, weight and child/dog-friendliness scores — pull cat photos, and grab a random cat fact. Three reliable, key-less open sources (dog.ceo, TheCatAPI, catfact.ninja) behind one clean envelope. Perfect for pet adoption and veterinary apps, kids and education content, Discord/Telegram bots, placeholder imagery, quizzes and any product that needs a quick hit of dogs and cats.

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

## Pricing
- **Free** (Free) — 5,000 calls/Mo, 2 req/s
- **Starter** ($4/Mo) — 80,000 calls/Mo, 8 req/s
- **Pro** ($12/Mo) — 400,000 calls/Mo, 20 req/s
- **Mega** ($35/Mo) — 2,000,000 calls/Mo, 50 req/s

## Endpoints

### Dogs

#### `GET /v1/dog/breeds` — Every dog breed and its sub-breeds

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

**Response:**
```json
{
    "data": {
        "count": 108,
        "breeds": [
            {
                "breed": "affenpinscher",
                "sub_breeds": []
            },
            {
                "breed": "african",
                "sub_breeds": [
                    "wild"
                ]
            },
            {
                "breed": "airedale",
                "sub_breeds": []
            },
            {
                "breed": "akita",
                "sub_breeds": []
            },
            {
                "breed": "appenzeller",
                "sub_breeds": []
            },
            {
                "breed": "australian",
                "sub_breeds": [
                    "kelpie",
                    "shepherd"
                ]
            },
            {
                "breed": "bakharwal",
                "sub_breeds": [
                    "indian"
                ]
            },
            {
                "breed": "basenji",
                "sub_breeds": []
            },
            {
                "breed": "beagle",
                "sub_breeds": []
            },
            {
                "breed": "bluetick",
                "sub_breeds": []
            },
            {
                "breed": "borzoi",
                "sub_breeds": []
            },
            {
                "breed": "bouvier",
                "sub_breeds": []
            },
            {
                "breed": "boxer",
                "sub_breeds": []
    
…(truncated, see openapi.json for full schema)
```

#### `GET /v1/dog/image` — Random dog photo(s), optionally by breed

**Parameters:**
- `breed` (query, optional, string) — Breed or breed/sub-breed, e.g. hound or hound/afghan Example: `hound`
- `count` (query, optional, string) — How many photos (1-10, default 1) Example: `3`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/animals-api/v1/dog/image?breed=hound&count=3"
```

**Response:**
```json
{
    "data": {
        "breed": "hound",
        "count": 3,
        "images": [
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_4230.jpg",
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_7683.jpg",
            "https://images.dog.ceo/breeds/hound-walker/n02089867_1599.jpg"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:41.192Z",
        "request_id": "0dc92b69-4b46-43cd-b39d-149bdee3e642"
    },
    "status": "ok",
    "message": "Dog image retrieved",
    "success": true
}
```

### Cats

#### `GET /v1/cat/breeds` — Cat breeds with metadata (searchable)

**Parameters:**
- `q` (query, optional, string) — Search name / origin / temperament, e.g. siamese Example: `siamese`
- `limit` (query, optional, string) — Max breeds (1-100, default 50) Example: `50`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/animals-api/v1/cat/breeds?q=siamese&limit=50"
```

**Response:**
```json
{
    "data": {
        "count": 1,
        "query": "siamese",
        "total": 1,
        "breeds": [
            {
                "id": "siam",
                "name": "Siamese",
                "indoor": false,
                "origin": "Thailand",
                "weight": "4 - 7 kg",
                "hairless": false,
                "life_span": "12 - 15",
                "description": "While Siamese cats are extremely fond of their people, they will follow you around and supervise your every move, being talkative and opinionated. They are a demanding and social cat, that do not like being left alone for long periods.",
                "temperament": "Active, Agile, Clever, Sociable, Loving, Energetic",
                "dog_friendly": 5,
                "energy_level": 5,
                "intelligence": 5,
                "wikipedia_url": "https://en.wikipedia.org/wiki/Siamese_(cat)",
                "child_friendly": 4,
                "affection_level": 5,
                "reference_image_id": "ai6Jps4sx"
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:41.604Z",
        "request_id": "479c7681-9c5a-4947-862e-166e95fd9e18"
    },
    "status": "ok",
    "message": "Cat breeds retrieved",
    "success": true
}
```

#### `GET /v1/cat/fact` — A random cat fact

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

**Response:**
```json
{
    "data": {
        "fact": "Cat families usually play best in even numbers. Cats and kittens should be acquired in pairs whenever possible.",
        "length": 111
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:41.843Z",
        "request_id": "f4736800-7b5d-4a4e-8b4b-1b82098e16b2"
    },
    "status": "ok",
    "message": "Cat fact retrieved",
    "success": true
}
```

#### `GET /v1/cat/image` — Random cat photo(s)

**Parameters:**
- `count` (query, optional, string) — How many photos (1-10, default 1) Example: `3`
- `breed_id` (query, optional, string) — Filter by TheCatAPI breed id, e.g. beng

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/animals-api/v1/cat/image?count=3"
```

**Response:**
```json
{
    "data": {
        "count": 3,
        "images": [
            {
                "id": "41e",
                "url": "https://cdn2.thecatapi.com/images/41e.gif",
                "width": 275,
                "height": 189
            },
            {
                "id": "4jh",
                "url": "https://cdn2.thecatapi.com/images/4jh.gif",
                "width": 478,
                "height": 334
            },
            {
                "id": "apn",
                "url": "https://cdn2.thecatapi.com/images/apn.jpg",
                "width": 612,
                "height": 612
            }
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:42.108Z",
        "request_id": "e0e77067-c6f4-4544-8e7c-e9e906614902"
    },
    "status": "ok",
    "message": "Cat image retrieved",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Sources & usage notes

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

**Response:**
```json
{
    "data": {
        "note": "Dogs & cats. /v1/dog/breeds = all dog breeds + sub-breeds; /v1/dog/image = random dog photo(s) (breed=hound or hound/afghan, count up to 10); /v1/cat/breeds = cat breeds with temperament/origin/life-span/traits (q= to search); /v1/cat/image = random cat photo(s) (count, optional breed_id); /v1/cat/fact = a random cat fact. All upstreams are key-less.",
        "sources": {
            "cats": "TheCatAPI (thecatapi.com)",
            "dogs": "dog.ceo",
            "cat_facts": "catfact.ninja"
        },
        "endpoints": [
            "/v1/dog/breeds",
            "/v1/dog/image",
            "/v1/cat/breeds",
            "/v1/cat/image",
            "/v1/cat/fact",
            "/v1/meta"
        ]
    },
    "meta": {
        "timestamp": "2026-06-01T00:04:42.175Z",
        "request_id": "60c5a9c7-2792-4c47-bd84-d260cf7c5c12"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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