# Long Strange Click API

> A read-only, snapshot-backed JSON API over a frozen, canonicalized Grateful Dead live-performance catalog: shows, setlists, venues, songs, sources, and a URL resolver. Every response is the canonical { data, meta } envelope. No auth is required; the surface is IP rate-limited.

Version 1.0.0. Read-only, snapshot-backed, no auth. This file is the index. For the complete reference in one document read llms-full.txt; for a build-time integration recipe read agents.md; for the machine contract import the OpenAPI or Postman spec. All are linked below.

## Endpoints

Every route is GET-only, unauthenticated, and returns the { data, meta } envelope. Paths are shown relative to the API base.

- [GET /api/v1/books](https://staging.longstrangeclick.com/api/v1/books): List books as a schema.org ItemList of Book nodes (paginated).
- [GET /api/v1/books/:slug](https://staging.longstrangeclick.com/api/v1/books/:slug): A book as a schema.org Book JSON-LD node (editions, offers, citations).
- [GET /api/v1/health](https://staging.longstrangeclick.com/api/v1/health): Liveness and version probe.
- [GET /api/v1/people](https://staging.longstrangeclick.com/api/v1/people): List people as a schema.org ItemList of Person nodes (paginated).
- [GET /api/v1/people/:slug](https://staging.longstrangeclick.com/api/v1/people/:slug): A person as a schema.org Person JSON-LD node (public-safe identity; authored works).
- [GET /api/v1/releases](https://staging.longstrangeclick.com/api/v1/releases): List releases as a schema.org ItemList of MusicAlbum or MusicRelease nodes (paginated).
- [GET /api/v1/releases/:slug](https://staging.longstrangeclick.com/api/v1/releases/:slug): A release as a schema.org MusicAlbum or MusicRelease JSON-LD node (cover, links, shows captured).
- [GET /api/v1/resolve-url](https://staging.longstrangeclick.com/api/v1/resolve-url): Resolve a pasted Grateful Dead URL to the canonical show (or honest candidates / no-match).
- [GET /api/v1/shows](https://staging.longstrangeclick.com/api/v1/shows): List shows as a schema.org ItemList of MusicEvent nodes (paginated, optional year / venue filter).
- [GET /api/v1/shows/:slug](https://staging.longstrangeclick.com/api/v1/shows/:slug): The public schema.org MusicEvent JSON-LD projection for a show.
- [GET /api/v1/shows/date/:date](https://staging.longstrangeclick.com/api/v1/shows/date/:date): Every show on a calendar day as a schema.org ItemList of MusicEvent nodes (usually one; two or more for an early/late double-header). Forgiving date input.
- [GET /api/v1/songs](https://staging.longstrangeclick.com/api/v1/songs): List songs as a schema.org ItemList of MusicComposition nodes (paginated).
- [GET /api/v1/songs/:slug](https://staging.longstrangeclick.com/api/v1/songs/:slug): A song as a schema.org MusicComposition JSON-LD node (performances, segues).
- [GET /api/v1/sources](https://staging.longstrangeclick.com/api/v1/sources): The credited-source registry, provenance-derived from the changelog.
- [GET /api/v1/venues](https://staging.longstrangeclick.com/api/v1/venues): List venues as a schema.org ItemList of MusicVenue nodes (paginated).
- [GET /api/v1/venues/:slug](https://staging.longstrangeclick.com/api/v1/venues/:slug): A venue as a schema.org MusicVenue JSON-LD node (address, shows hosted).

## Rate limit

IP-keyed. Burst: 100 requests / 60s. Daily quota: 250 requests / 24h. A request must pass BOTH windows; the tighter one throttles. Full posture and headers: see llms-full.txt.

## Full reference and recipe

- [llms-full.txt](https://staging.longstrangeclick.com/llms-full.txt): The complete API reference in one self-contained document.
- [agents.md](https://staging.longstrangeclick.com/agents.md): A build-time recipe for a coding agent integrating this API.

## Machine specs

- [OpenAPI 3.1 (JSON)](https://staging.longstrangeclick.com/openapi.json)
- [OpenAPI 3.1 (YAML)](https://staging.longstrangeclick.com/openapi.yaml)
- [Postman Collection v2.1](https://staging.longstrangeclick.com/postman.json)