# One Page Love API

> Developer-facing REST API for the One Page Love catalog: 8,900+ hand-curated single-page websites with rich taxonomy (genre, color, style, typeface, platform, tech, sections, authors), full-size and cropped screenshots, and aggregated design trend data. Designed for AI tools and developers — structured JSON, consistent schemas, and stable URLs.

**Base URL:** `https://api.onepagelove.com`
**Version:** `v1` (path-prefixed)
**Auth:** Bearer token — register at `POST /v1/register`
**Rate limits:** 100 requests / 60 seconds on authenticated endpoints; 5 registrations / hour per IP
**Catalog:** 8,993 sites as of 2026-05-25 — see `GET /v1/meta` for a live breakdown.

## Why this dataset is different

Every entry is a permanent record of a one-page website, captured and classified at the moment it was interesting:

- **Hand-curated** — each site was selected and tagged by a human editor, not scraped en masse.
- **Structured taxonomy** — every site carries genre, color, style, typeface, platform, sections, and author metadata in clean slugs.
- **2× retina full-page screenshots** — captured at high resolution, served through Cloudflare Image Resizing with presets for hero, thumbnail, full, and mobile.
- **Categorized section crops** — hero, pricing tables, FAQs, testimonials, client logo rows, and more — each surface-able individually via `/v1/sections`.
- **Preserved forever** — sites whose live URL has gone dark still have their screenshot, taxonomy, and context intact. Nothing disappears from the archive.

## Documentation

- [Interactive reference (Scalar)](https://api.onepagelove.com/docs): full docs with try-it
- [OpenAPI 3.1 spec](https://api.onepagelove.com/docs/openapi.json): machine-readable schema
- [Full spec in markdown](https://api.onepagelove.com/docs/llms-full.txt): complete endpoint reference for LLM ingestion
- [Changelog](https://api.onepagelove.com/docs/changelog.md): versioned additions, changes, deprecations
- [Terms of use](https://api.onepagelove.com/docs/terms.md): usage rules, including prohibition on redistributing the catalog as a competing gallery

## Endpoints

- `POST /v1/register` — create a free API key (email-scoped, max 2 keys per email)
- `GET /v1/me` — authenticated key info + usage counters
- `GET /v1/meta` — public catalog counts (inspirations, taxonomies, last update)
- `GET /v1/inspirations` — search the catalog with taxonomy filters
- `GET /v1/inspirations/{slug}` — fetch a single inspiration by slug
- `GET /v1/search` — free-text search with grouped results (matched filters + suggestion pills + result grid). Every taxonomy term includes a ready-to-use `url` field. Curated **synonyms** (per term, see `/v1/taxonomies`) are honored: a query that doesn't match a term name/slug will fall through to synonym match before the title-LIKE fallback. Example: `coral` → `Red` color (Red has synonym `coral`); `dark mode` → `Dark` color.
- `GET /v1/sections` — cropped section images (pricing tables, heroes, FAQs, etc.) with parent-site metadata
- `GET /v1/taxonomies` — every filter term across every taxonomy, each with its archive `url` and any curated **synonyms** (alt-spellings/vernacular editors set in wp-admin to route queries to the term)
- `GET /v1/stats/taxonomy` — aggregate term usage, optionally time-scoped

## Common use cases

- **AI-assisted design research** — pull structured examples filtered by color, genre, platform, tech, typeface
- **Cropped section library** — pricing layouts, hero variants, testimonial patterns via `/v1/sections`
- **Font discovery** — query every site using a given typeface (~1,069 typefaces catalogued)
- **Trend analysis** — aggregate taxonomy usage over the last 7d / 30d / 12mo / all-time
- **Historical design archive** — the only place on the web where one-page designs from 2008 onward are preserved with taxonomy + retina screenshots, even when the original site has long gone

## Response shape

All successful responses are JSON. Paginated endpoints return `{ total, limit, offset, results: [...] }`.

Errors are `{ error: "<code>", message: "<human-readable>" }` with codes: `unauthorized` (401), `forbidden` (403), `bad_request` (400), `not_found` (404), `rate_limited` (429), `internal` (500).

## Screenshots

Images are served via Cloudflare Image Resizing. Each inspiration includes `screenshot.hero` (1280×800 crop), `thumbnail` (400×300), `full` (2560px), `original` (unresized), `mobile` (375px if captured), and `width`/`height` pixels. Custom transforms are supported via the `/cdn-cgi/image/...` URL pattern.

## Usage rules (summary)

- Individual developers may use the data for inspiration search, AI-assisted generation, and personal tooling — attribution appreciated.
- **Commercial AI training** requires a paid plan or custom license — contact rob@onepagelove.com.
- **Prohibited:** redistributing the catalog (in whole or substantial part) as a browsable or searchable interface that competes with One Page Love.

Full terms: https://api.onepagelove.com/docs/terms.md

## Contact

Rob Hope — rob@onepagelove.com — https://onepagelove.com/api