# Chuck Norris Jokes API
> The famous Chuck Norris joke collection via the open chucknorris.io API — no key. The random endpoint returns a random Chuck Norris joke and can be filtered to a category (e.g. dev, food, sport, money, science); the categories endpoint lists every available category; and the search endpoint runs a full-text query across the whole collection. Each joke carries its id, text, categories and a permalink. Real jokes, with categories cached for speed — no key. 4 endpoints. Ideal for chatbots, Slack/Discord bots, 404 pages, loading screens and developer-fun easter eggs.

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

## Pricing
- **Free** (Free) — 7,000 calls/Mo, 2 req/s
- **Basic** ($6/Mo) — 94,500 calls/Mo, 8 req/s
- **Pro** ($22/Mo) — 557,500 calls/Mo, 20 req/s
- **Mega** ($66/Mo) — 2,720,000 calls/Mo, 50 req/s

## Endpoints

### Jokes

#### `GET /v1/categories` — All joke categories

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

**Response:**
```json
{
    "data": {
        "count": 16,
        "categories": [
            "animal",
            "career",
            "celebrity",
            "dev",
            "explicit",
            "fashion",
            "food",
            "history",
            "money",
            "movie",
            "music",
            "political",
            "religion",
            "science",
            "sport",
            "travel"
        ]
    },
    "meta": {
        "timestamp": "2026-06-08T09:48:46.033Z",
        "request_id": "9cc3f04e-84df-43dd-a8b5-1c9e189e651d"
    },
    "status": "ok",
    "message": "Categories retrieved successfully",
    "success": true
}
```

#### `GET /v1/random` — A random joke

**Parameters:**
- `category` (query, optional, string) — Category to draw from (see /v1/categories) Example: `dev`

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

**Response:**
```json
{
    "data": {
        "joke": {
            "id": "i8k15bwdq4iwpdz3__u8fg",
            "url": "https://api.chucknorris.io/jokes/i8k15bwdq4iwpdz3__u8fg",
            "joke": "Chuck Norris' programs never exit, they terminate.",
            "icon_url": "https://api.chucknorris.io/img/avatar/chuck-norris.png",
            "categories": [
                "dev"
            ]
        }
    },
    "meta": {
        "timestamp": "2026-06-08T09:48:46.331Z",
        "request_id": "ec848dc9-8de3-43fd-812d-be600977f332"
    },
    "status": "ok",
    "message": "Joke retrieved successfully",
    "success": true
}
```

#### `GET /v1/search` — Search the collection

**Parameters:**
- `q` (query, required, string) — Search query (min 3 chars) Example: `computer`
- `limit` (query, optional, string) — Max results (1-100, default 20) Example: `20`

**Example:**
```bash
curl -H "x-oanor-key: $KEY" \
  "https://api.oanor.com/chucknorris-api/v1/search?q=computer&limit=20"
```

**Response:**
```json
{
    "data": {
        "count": 20,
        "jokes": [
            {
                "id": "y-b7g8trr96pfmopdplf4g",
                "url": "https://api.chucknorris.io/jokes/y-b7g8trr96pfmopdplf4g",
                "joke": "Chuck Norris doesn't use a computer because a computer does everything slower than Chuck Norris.",
                "icon_url": "https://api.chucknorris.io/img/avatar/chuck-norris.png",
                "categories": []
            },
            {
                "id": "AN7_hBUjSW-Fnbn-28jaVQ",
                "url": "https://api.chucknorris.io/jokes/AN7_hBUjSW-Fnbn-28jaVQ",
                "joke": "When Chuck Norris wants cookies, he crashes open a computer.",
                "icon_url": "https://api.chucknorris.io/img/avatar/chuck-norris.png",
                "categories": []
            },
            {
                "id": "mHaLxKzVRjiBLgE1KhEZ_g",
                "url": "https://api.chucknorris.io/jokes/mHaLxKzVRjiBLgE1KhEZ_g",
                "joke": "Chuck Norris can build a computer with Windows 7.",
                "icon_url": "https://api.chucknorris.io/img/avatar/chuck-norris.png",
                "categories": []
            },
            {
                "id": "9oOcprOiRh6ucQj0Lr8dHw",
                "url": "https://api.chucknorris.io/jokes/9oOcprOiRh6ucQj0Lr8dHw",
                "joke": "There is no 'ctrl' button on Chuck Norris's computer. Chuck Norris is always in control.",
                "icon_url": "https://api.chucknorris.io/img/a
…(truncated, see openapi.json for full schema)
```

### Meta

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

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

**Response:**
```json
{
    "data": {
        "service": "chucknorris-api",
        "endpoints": {
            "GET /v1/meta": "This document.",
            "GET /v1/random": "A random Chuck Norris joke (category=optional, e.g. dev).",
            "GET /v1/search": "Full-text search the collection (q=, min 3 chars, limit=).",
            "GET /v1/categories": "All joke categories."
        },
        "description": "The famous Chuck Norris joke collection via the open chucknorris.io API: pull a random joke (optionally from a category like dev, food or sport), list the available categories, or full-text search the collection. Real jokes, no key."
    },
    "meta": {
        "timestamp": "2026-06-08T09:48:46.607Z",
        "request_id": "49995389-1924-454c-bad3-a5c3f35e26eb"
    },
    "status": "ok",
    "message": "Meta",
    "success": true
}
```


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