# Long Strange Click API - complete reference

> Version 1.0.0. The self-contained long-form companion to https://staging.longstrangeclick.com/llms.txt (the index) and https://staging.longstrangeclick.com/agents.md (the build-time recipe). Everything an agent needs to consume the API is in this one document.

## Base URL and versioning

All endpoints live under `https://staging.longstrangeclick.com/api/v1`. There is no separate API host and no version negotiation - the surface is v1.0.0, read-only, and snapshot-backed (a frozen, canonicalized catalog).

## Authentication

None. The API is public and read-only. Do not send Authorization headers or API keys; there is no account, key, or quota tier to manage. Identity is not tracked; rate limiting is by client IP only.

## Response envelope

Every 2xx response is the canonical `{ data, meta }` envelope. Read your rows from `data`; `meta` carries `queryTimeMs` and `generatedAt` (the snapshot instant) plus, on list routes, `total`/`limit`/`offset`.

Read-side honesty: absent facts are omitted, never fabricated. A show with no known setlist omits the setlist rather than emitting an empty one; a source's confidence is a word label (`confirmed`/`probable`/`possible`), never a raw score. Treat a missing field as "unknown", not "none".

## Rate limiting and headers

IP-keyed. Burst: 100 requests / 60s. Daily quota: 250 requests / 24h. A request must pass BOTH windows; the tighter one throttles.

Every response carries `RateLimit-Limit`, `RateLimit-Remaining`, and `RateLimit-Reset` for the tightest-binding window. A throttled request returns `429 Too Many Requests` with a `Retry-After` header (seconds) - honor it rather than retrying immediately; retrying on 429 only lengthens the window. Health and discovery files (/llms.txt, /llms-full.txt, /agents.md, the specs, robots) are exempt from counting so an agent can orient before it knows the limit.

## Endpoints

Every route is GET-only and unauthenticated. Paths are relative to `https://staging.longstrangeclick.com`. The MCP column marks routes also exposed as MCP tools.

| Method | Path | Summary | MCP |
|---|---|---|---|
| GET | `/api/v1/books` | List books as a schema.org ItemList of Book nodes (paginated). | yes |
| GET | `/api/v1/books/:slug` | A book as a schema.org Book JSON-LD node (editions, offers, citations). | yes |
| GET | `/api/v1/health` | Liveness and version probe. | yes |
| GET | `/api/v1/people` | List people as a schema.org ItemList of Person nodes (paginated). | yes |
| GET | `/api/v1/people/:slug` | A person as a schema.org Person JSON-LD node (public-safe identity; authored works). | yes |
| GET | `/api/v1/releases` | List releases as a schema.org ItemList of MusicAlbum or MusicRelease nodes (paginated). | yes |
| GET | `/api/v1/releases/:slug` | A release as a schema.org MusicAlbum or MusicRelease JSON-LD node (cover, links, shows captured). | yes |
| GET | `/api/v1/resolve-url` | Resolve a pasted Grateful Dead URL to the canonical show (or honest candidates / no-match). | yes |
| GET | `/api/v1/shows` | List shows as a schema.org ItemList of MusicEvent nodes (paginated, optional year / venue filter). | yes |
| GET | `/api/v1/shows/:slug` | The public schema.org MusicEvent JSON-LD projection for a show. | yes |
| GET | `/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. | yes |
| GET | `/api/v1/songs` | List songs as a schema.org ItemList of MusicComposition nodes (paginated). | yes |
| GET | `/api/v1/songs/:slug` | A song as a schema.org MusicComposition JSON-LD node (performances, segues). | yes |
| GET | `/api/v1/sources` | The credited-source registry, provenance-derived from the changelog. | yes |
| GET | `/api/v1/venues` | List venues as a schema.org ItemList of MusicVenue nodes (paginated). | yes |
| GET | `/api/v1/venues/:slug` | A venue as a schema.org MusicVenue JSON-LD node (address, shows hosted). | yes |

## Worked flows

**Resolve an external URL to a canonical show.** Given an archive.org, setlist.fm, or similar Grateful Dead URL, call `GET https://staging.longstrangeclick.com/api/v1/resolve-url?url=...`; the `data` carries the matched canonical show (or a miss you can surface honestly).

**Look up a date.** Call `GET https://staging.longstrangeclick.com/api/v1/shows/date/{date}`; `data` is an ARRAY - a single date can hold more than one show (early/late sets), so never assume exactly one.

## Machine specs

OpenAPI 3.1: `https://staging.longstrangeclick.com/openapi.json` (JSON) or `https://staging.longstrangeclick.com/openapi.yaml` (YAML). Postman v2.1: `https://staging.longstrangeclick.com/postman.json`. All are derived from the same typed contracts the server validates against, so they cannot drift from the live surface.