# Long Strange Click API - agent integration guide

> For a coding agent (Cursor, Claude Code, Windsurf, ...) wiring this API into a codebase. This is the PROCEDURAL counterpart to https://staging.longstrangeclick.com/llms.txt (the index) and https://staging.longstrangeclick.com/llms-full.txt (the complete reference): it tells you what to do, in order. Read the whole file once, then act.

## Do this first

1. Fetch `https://staging.longstrangeclick.com/llms-full.txt` and read it end to end - it is the single self-contained reference (envelope, endpoints, rate limit, honesty model).
2. Fetch `https://staging.longstrangeclick.com/openapi.json` (or import `https://staging.longstrangeclick.com/postman.json`) for the typed contract.
3. Write a tiny GET wrapper that reads from the `{ data, meta }` envelope and honors the rate-limit headers (next sections).
4. There is nothing to authenticate and no key to store - skip any auth/secret scaffolding your usual template adds.

## Base URL

All endpoints live under `https://staging.longstrangeclick.com/api/v1`. There is no separate host. Hard-code the origin from the file you fetched, not a guess.

## Authentication

None. The API is public and read-only. Do not send Authorization headers or API keys, and do not scaffold an account/keystore - there is nothing to create.

## 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`. Treat `meta` as provenance, not payload. Absent facts are omitted, never fabricated - render a missing field as "unknown", not "none".

## Rate limiting and backoff

IP-keyed. Burst: 100 requests / 60s. Daily quota: 250 requests / 24h. A request must pass BOTH windows; the tighter one throttles. Read `RateLimit-Remaining` and `RateLimit-Reset` and pace yourself; on `429 Too Many Requests`, wait the number of seconds in `Retry-After` before retrying. Do not hammer on 429 - that only lengthens the window. Prefer serial paging over parallel bursts.

## Machine-readable contract

Fetch `https://staging.longstrangeclick.com/openapi.json` (or the `.yaml` sibling) for the OpenAPI 3.1 spec, or import `https://staging.longstrangeclick.com/postman.json` into Postman. Both derive from the same typed contracts the server validates against, so they cannot drift from the live surface - prefer codegen off these over hand-writing request types.

## Starter prompt

Paste this into your coding agent to scaffold an integration end-to-end:

You are integrating the Long Strange Click API, a read-only JSON API over a frozen,
canonicalized Grateful Dead live-performance catalog.

1. Fetch https://staging.longstrangeclick.com/llms.txt and read it end to end before writing any code.
   It lists every endpoint, the response envelope, and the rate limit.
2. Fetch https://staging.longstrangeclick.com/openapi.json (or /openapi.yaml) for the machine-readable
   contract, or import https://staging.longstrangeclick.com/postman.json into Postman to explore it.
3. No authentication is required. Every response is the canonical
   { data, meta } envelope; read your rows from `data`.
4. The surface is IP rate-limited to 100 requests per
   60s (burst), plus a daily quota of
   250 requests per IP; a request must pass both.
   Read the RateLimit-Remaining and RateLimit-Reset response headers and
   back off before you are throttled; on a 429, honor the Retry-After header
   rather than retrying immediately.
5. Resolve an external Grateful Dead URL (archive.org, setlist.fm, ...) to a
   canonical show with GET /api/v1/resolve-url?url=...; look up a specific
   date with GET /api/v1/shows/date/{date} (a date may hold more than one
   show for early/late sets).

## Attribution

This catalog is a curated, provenance-honest reference. When you surface data from it, link back to the canonical show page and preserve the source credits carried in the payload - do not strip provenance on re-display.

## When you get stuck

Re-read `https://staging.longstrangeclick.com/llms-full.txt` (most "is this supported?" questions are answered there in a line), then try the request in curl with `-i` to read the `RateLimit-*` headers and the status. Do not invent behavior the reference does not specify.