# Jokes API
> A clean, family-friendly jokes API. Fetch a random joke — or several at once — as a single-line one-liner or a two-part setup-and-delivery, filtered by category (Programming, Misc, Pun, Spooky, Christmas); search for jokes containing a specific word; and list the available categories. Safe-mode is always enforced and the offensive "Dark" category is excluded, so every joke is workplace- and family-safe. Ideal for chat and Discord bots, websites and apps that want a touch of humour, loading screens, and developer tools. Built on JokeAPI.

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

## Pricing
- **Free** (Free) — 5,200 calls/Mo, 2 req/s
- **Starter** ($3/Mo) — 80,000 calls/Mo, 10 req/s
- **Pro** ($8/Mo) — 420,000 calls/Mo, 25 req/s
- **Mega** ($22/Mo) — 2,080,000 calls/Mo, 60 req/s

## Endpoints

### Jokes

#### `GET /v1/categories` — Available categories

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

**Response:**
```json
{
    "data": {
        "note": "Only family-friendly categories are available; safe-mode is always on, and the offensive 'Dark' category is excluded.",
        "types": [
            "single",
            "twopart"
        ],
        "excluded": [
            "Dark"
        ],
        "categories": [
            "Programming",
            "Misc",
            "Pun",
            "Spooky",
            "Christmas"
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T15:38:05.627Z",
        "request_id": "78bf7570-6265-40be-9d1a-b64107545085"
    },
    "status": "ok",
    "message": "Categories retrieved",
    "success": true
}
```

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

**Parameters:**
- `category` (query, optional, string) — Programming | Misc | Pun | Spooky | Christmas (default any clean) Example: `Programming`
- `type` (query, optional, string) — single | twopart
- `amount` (query, optional, string) — How many jokes (1-10, default 1)

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

**Response:**
```json
{
    "data": {
        "joke": {
            "id": 293,
            "type": "twopart",
            "setup": "why do python programmers wear glasses?",
            "category": "Programming",
            "delivery": "Because they can't C."
        }
    },
    "meta": {
        "timestamp": "2026-05-31T15:38:05.767Z",
        "request_id": "64194971-4efa-46b4-b0cb-1a39d0e4d1fb"
    },
    "status": "ok",
    "message": "Joke retrieved",
    "success": true
}
```

#### `GET /v1/search` — Jokes containing a word

**Parameters:**
- `q` (query, required, string) — Word the joke must contain Example: `computer`
- `category` (query, optional, string) — Restrict to a category
- `amount` (query, optional, string) — Max results (1-10, default 5)

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

**Response:**
```json
{
    "data": {
        "count": 1,
        "jokes": [
            {
                "id": 210,
                "type": "twopart",
                "setup": "What are bits?",
                "category": "Programming",
                "delivery": "Tiny things left when you drop your computer down the stairs."
            }
        ],
        "query": "computer"
    },
    "meta": {
        "timestamp": "2026-05-31T15:38:05.881Z",
        "request_id": "c965ff66-d808-4951-b989-ba9cf7d95966"
    },
    "status": "ok",
    "message": "Jokes searched",
    "success": true
}
```

### Meta

#### `GET /v1/meta` — Source & options

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

**Response:**
```json
{
    "data": {
        "note": "Clean, family-friendly jokes. /v1/random = a random joke (or several via amount) — filter by category and type (single/twopart); /v1/search = jokes containing a word; /v1/categories = the available categories. Safe-mode is always enforced and the offensive Dark category is excluded.",
        "source": "JokeAPI (v2.jokeapi.dev) — safe-mode, clean categories only",
        "endpoints": [
            "/v1/random",
            "/v1/search",
            "/v1/categories",
            "/v1/meta"
        ],
        "categories": [
            "Programming",
            "Misc",
            "Pun",
            "Spooky",
            "Christmas"
        ]
    },
    "meta": {
        "timestamp": "2026-05-31T15:38:05.962Z",
        "request_id": "abf5e8dc-02c3-4ef4-9784-93566c22a572"
    },
    "status": "ok",
    "message": "Meta retrieved",
    "success": true
}
```


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