# Dog Breeds & Images API
> Dog-breed images and the full breed taxonomy via the open Dog CEO collection — no key. The breeds endpoint returns every breed with its sub-breeds (e.g. hound → afghan, basset, blood, …). The images endpoint fetches a batch of photos for a given breed and optional sub-breed, and the random endpoint pulls a batch of random dog photos from across all breeds. Real images straight from the Dog CEO dataset, with the breed list cached for speed — no key. 4 endpoints. Ideal for pet apps, placeholder imagery, breed pickers, quizzes and fun UI seeding.

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

## Pricing
- **Free** (Free) — 6,600 calls/Mo, 2 req/s
- **Basic** ($7/Mo) — 88,500 calls/Mo, 8 req/s
- **Pro** ($24/Mo) — 551,500 calls/Mo, 20 req/s
- **Mega** ($72/Mo) — 2,700,000 calls/Mo, 50 req/s

## Endpoints

### Dogs

#### `GET /v1/breeds` — All breeds & sub-breeds

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/dog-api/v1/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/images` — Images for a breed

**Parameters:**
- `breed` (query, required, string) — Breed name (see /v1/breeds) Example: `hound`
- `sub` (query, optional, string) — Sub-breed (e.g. afghan) Example: `afghan`
- `count` (query, optional, string) — Number of images (1-50, default 12) Example: `5`

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

**Response:**
```json
{
    "data": {
        "breed": "hound",
        "count": 5,
        "images": [
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_1003.jpg",
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_173.jpg",
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_3582.jpg",
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_6241.jpg",
            "https://images.dog.ceo/breeds/hound-afghan/n02088094_7683.jpg"
        ],
        "sub_breed": "afghan"
    },
    "meta": {
        "timestamp": "2026-06-08T09:48:47.869Z",
        "request_id": "bfda4cb8-bb08-4ca6-abef-41611fadae77"
    },
    "status": "ok",
    "message": "Images retrieved successfully",
    "success": true
}
```

#### `GET /v1/random` — Random dog images

**Parameters:**
- `count` (query, optional, string) — Number of images (1-50, default 1) Example: `3`

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

**Response:**
```json
{
    "data": {
        "count": 3,
        "images": [
            "https://images.dog.ceo/breeds/bullterrier-staffordshire/n02093256_14914.jpg",
            "https://images.dog.ceo/breeds/setter-gordon/n02101006_134.jpg",
            "https://images.dog.ceo/breeds/bakharwal-indian/Bakharwal.jpg"
        ]
    },
    "meta": {
        "timestamp": "2026-06-08T09:48:48.036Z",
        "request_id": "923d7c4a-e031-4ebb-9fb7-e0a79ee2fdb7"
    },
    "status": "ok",
    "message": "Random images retrieved successfully",
    "success": true
}
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "service": "dog-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/breeds": "All breeds with their sub-breeds.",
            "GET /v1/images": "Images for a breed (breed=, sub=optional, count=1-50, default 12).",
            "GET /v1/random": "Random dog images (count=1-50, default 1)."
        },
        "description": "Dog-breed images and taxonomy via the open Dog CEO API: list every breed with its sub-breeds; fetch a batch of images for a breed (and optional sub-breed); or pull random dog images. Real photos straight from the Dog CEO collection, no key."
    },
    "meta": {
        "timestamp": "2026-06-08T09:48:48.164Z",
        "request_id": "c983244d-e250-4572-8efc-9b3ea21bc9c5"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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