# Oddworth API

Base URL: `https://oddworth.com/api/oddworth`

Oddworth is a database of what things are worth — from everyday items to priceless artifacts. All endpoints are free, no auth required.

## Endpoints

### List Items
```
GET /api/oddworth/items
```

Query params:
- `limit` (number, default 20, max 50) — items per page
- `cursor` (string) — pagination cursor from previous response
- `category` (string) — filter by category ID
- `q` (string) — search by name

Response:
```json
{
  "items": [
    {
      "id": "bitcoin",
      "name": "1 Bitcoin",
      "slug": "bitcoin",
      "worthCents": 8700000,
      "worthLabel": "$87,000",
      "imageSmall": "https://cdn.swell.so/oddworth/items/bitcoin/small.png",
      "imageLarge": "https://cdn.swell.so/oddworth/items/bitcoin/large.png",
      "categoryId": "tech",
      "shortDescription": "One unit of the original cryptocurrency.",
      "tags": ["crypto", "bitcoin"]
    }
  ],
  "nextCursor": "2026-03-29T03:14:11.995Z"
}
```

### Get Single Item
```
GET /api/oddworth/items/{slug}
GET /api/oddworth/items/{slug}?format=text
```

Returns full item details including category, fun facts, and affiliate links. Add `?format=text` for plain text output.

### Random Item
```
GET /api/oddworth/items/random
```

Returns a random published item.

### Compare Two Items
```
GET /api/oddworth/compare?a={slug}&b={slug}
```

Returns both items and their value ratio.

### Random Comparison
```
GET /api/oddworth/compare/random
```

Returns two random items and their ratio.

### Ask a Question (Natural Language)
```
POST /api/oddworth/ask
Content-Type: application/json

{ "q": "How many avocado toasts equal a Bitcoin?" }
```

AI-powered natural language queries about item values. Rate limited to 10 requests/minute per IP.

Supports `Accept: text/plain` header for plain text responses.

Response:
```json
{
  "answer": "About 7,250.",
  "items": ["avocado-toast", "bitcoin"]
}
```

## Categories

- `art-collectibles` — Paintings, cards, memorabilia
- `vehicles` — Cars, planes, boats, spacecraft
- `real-estate` — Homes, palaces, islands
- `food-drink` — Groceries to luxury dining
- `tech` — Gadgets, crypto, digital age
- `nature` — Precious metals, gems, earth
- `sports` — Championships, memorabilia
- `history` — Artifacts, documents
- `pop-culture` — Movie props, music, internet
- `everyday` — Common items, life milestones

## Notes

- All prices are in USD cents (`worthCents`) and human-readable (`worthLabel`)
- Images are transparent PNGs — `imageSmall` (200x200) and `imageLarge` (800x800)
- Data updates weekly via automated research
- No authentication required
- Please be respectful with rate limits