# 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
- `tag` (string) — filter by tag (e.g. "weapon", "construction", "gold")
- `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"
}
```

### Search Items (Fuzzy)
```
GET /api/oddworth/items/search?q={query}
```

Query params:
- `q` (string, required) — search term (e.g. "sword", "gold ring", "laptop")
- `limit` (number, default 5, max 20) — max results
- `minSimilarity` (number, default 0.15, range 0-1) — minimum fuzzy match threshold. Higher values return fewer, more exact matches.

Returns the closest matches using fuzzy trigram matching, ranked by similarity score. Falls back to substring search if no fuzzy matches found.

Response:
```json
{
  "query": "sword",
  "results": [
    {
      "id": "sword",
      "name": "Sword",
      "slug": "sword",
      "worthCents": 15000,
      "worthLabel": "$150",
      "imageSmall": "https://cdn.swell.so/oddworth/items/sword/small.png",
      "imageLarge": "https://cdn.swell.so/oddworth/items/sword/large.png",
      "categoryId": "history",
      "tags": ["weapon", "blade", "medieval"],
      "similarity": 1.0
    }
  ]
}
```

### 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.

### Request an Item
```
POST /api/oddworth/items/request
Content-Type: application/json

{ "name": "2024 Toyota Camry XSE" }
```

Submit a request for a new item to be added. Reviewed and processed by admins. Optionally include `email` to be notified.

Response:
```json
{
  "ok": true,
  "message": "Request for \"2024 Toyota Camry XSE\" submitted. It will be reviewed and added if approved."
}
```

### 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