# Tailend API

> Read-only events, classes, camps, places and organizations for a multi-city family-activity product.

> **Agent instructions**
> - Base URL: `https://api.tailend.dev`. Every data endpoint is a `GET` under `/v1`; the API is read-only.
> - Authenticate every `/v1` request with the `X-API-Key: <key>` header. Keys are never accepted in the query string.
> - Keys are issued on request (not self-service yet): https://tailend.dev. Never put a key in client-side code.
> - Start with `GET /v1/metros`; most paths begin with a metro slug such as `philadelphia`.
> - On failure, branch on `error.code` in the JSON body, not on the HTTP status or message; quote `request_id` to support.
> - The OpenAPI spec is the source of truth for every parameter, field and status code: https://api.tailend.dev/docs/openapi.json
> - Humans can try any request with sample data (no key needed) from the API reference at https://api.tailend.dev/docs/api.
> - Every page below is Markdown; the HTML version is the same URL without `.md`.

## Docs

- [Overview](https://api.tailend.dev/docs/index.md): What the Tailend API returns, who it is for, and a working request for each common job.
- [Quickstart](https://api.tailend.dev/docs/quickstart.md): Make your first request, narrow it by date, age and location, and read the next page.
- [Authentication](https://api.tailend.dev/docs/authentication.md): Send your key in the X-API-Key header; what a key controls and how to keep it safe.
- [Conventions](https://api.tailend.dev/docs/conventions.md): Time fields, ids, booleans, prices and the response envelope every endpoint shares.
- [Build with AI agents](https://api.tailend.dev/docs/agents.md): llms.txt, Markdown pages and the OpenAPI spec for coding agents and assistants.
- [Search](https://api.tailend.dev/docs/search.md): One query across events, classes, camps and places, with match levels and scores.
- [Around an address](https://api.tailend.dev/docs/around-an-address.md): Everything near an address or point, grouped and ranked, with an activity summary.
- [Recurring events](https://api.tailend.dev/docs/recurring-events.md): How a weekly or monthly series is represented and how its next date is computed.
- [Classes with sections](https://api.tailend.dev/docs/class-sections.md): Programs offered in several variants, filtered one section at a time.
- [Finding a business](https://api.tailend.dev/docs/finding-a-business.md): Look up one organization by name, website or pasted URL, and read score and match.
- [Market overview with facets](https://api.tailend.dev/docs/market-overview-with-facets.md): Counts by category, weekday, time, price, age and organization over a whole filtered set.
- [Shaping responses](https://api.tailend.dev/docs/shaping-responses.md): Trim or extend what comes back with fields=, expand= and include=.
- [Pagination](https://api.tailend.dev/docs/pagination.md): Walk a collection past the first page with an opaque cursor.
- [Keep your copy in sync](https://api.tailend.dev/docs/syncing-changes.md): Mirror listings with the changes feed without missing an edit or a removal.
- [Caching](https://api.tailend.dev/docs/caching.md): Conditional requests with ETag and If-None-Match.
- [How we verify listings](https://api.tailend.dev/docs/how-we-verify.md): Where a listing comes from, and what confidence and verified_at tell you.
- [Audience & versioning](https://api.tailend.dev/docs/audience-and-versioning.md): The family-safe default, and what v1 promises not to break.
- [Plans & access](https://api.tailend.dev/docs/plans-and-access.md): What each plan includes, and what a 403 for a missing entitlement looks like.
- [Limits & usage](https://api.tailend.dev/docs/limits-and-usage.md): The per-minute rate limit, the monthly quota, and the headers that report both.
- [Errors](https://api.tailend.dev/docs/errors.md): The one error envelope, every error code, and whether to retry.

## API reference

- [API reference overview](https://api.tailend.dev/docs/api.md): Base URL, authentication, the response envelope and every endpoint.
- [List metros](https://api.tailend.dev/docs/api/list-metros.md): `GET /v1/metros`. Active metros, with their slug, name, timezone and known aliases.
- [Search every listing collection](https://api.tailend.dev/docs/api/search-listings.md): `GET /v1/{metro}/search`. Searches published, active listings in one metro.
- [List events](https://api.tailend.dev/docs/api/list-events.md): `GET /v1/{metro}/events`. Published, active events in the metro, ordered by starts_at ascending (then id).
- [Event counts per day](https://api.tailend.dev/docs/api/get-event-calendar.md): `GET /v1/{metro}/events/calendar`. For each local date in [from, to] (both required, at most 62 days inclusive), how many event occurrences start that day, how many of them are free, and how many fall in each category — every date included, with zeros.
- [Retrieve an event](https://api.tailend.dev/docs/api/get-event.md): `GET /v1/events/{id}`. An event by id.
- [Retrieve an event by slug](https://api.tailend.dev/docs/api/get-event-by-slug.md): `GET /v1/events/slug/{slug}`. Returns the same event as /v1/events/{id}, addressed by slug instead of id.
- [List place events](https://api.tailend.dev/docs/api/list-place-events.md): `GET /v1/places/{id}/events`. Same as GET /v1/{metro}/events?place_id={id}, addressed by the place instead of the metro.
- [List organization events](https://api.tailend.dev/docs/api/list-organization-events.md): `GET /v1/organizations/{id}/events`. Same as GET /v1/{metro}/events?organization_id={id}, addressed by the organization instead of the metro.
- [List classes](https://api.tailend.dev/docs/api/list-classes.md): `GET /v1/{metro}/classes`. Published, active classes.
- [Retrieve a class](https://api.tailend.dev/docs/api/get-class.md): `GET /v1/classes/{id}`. A class by id.
- [Retrieve a class by slug](https://api.tailend.dev/docs/api/get-class-by-slug.md): `GET /v1/classes/slug/{slug}`. Returns the same class as /v1/classes/{id}, addressed by slug instead of id.
- [List place classes](https://api.tailend.dev/docs/api/list-place-classes.md): `GET /v1/places/{id}/classes`. Same as GET /v1/{metro}/classes?place_id={id}, addressed by the place instead of the metro.
- [List organization classes](https://api.tailend.dev/docs/api/list-organization-classes.md): `GET /v1/organizations/{id}/classes`. Same as GET /v1/{metro}/classes?organization_id={id}, addressed by the organization instead of the metro.
- [List camps](https://api.tailend.dev/docs/api/list-camps.md): `GET /v1/{metro}/camps`. Published, active camps, with their sessions.
- [Retrieve a camp](https://api.tailend.dev/docs/api/get-camp.md): `GET /v1/camps/{id}`. A camp by id.
- [Retrieve a camp by slug](https://api.tailend.dev/docs/api/get-camp-by-slug.md): `GET /v1/camps/slug/{slug}`. Returns the same camp as /v1/camps/{id}, addressed by slug instead of id.
- [List place camps](https://api.tailend.dev/docs/api/list-place-camps.md): `GET /v1/places/{id}/camps`. Same as GET /v1/{metro}/camps?place_id={id}, addressed by the place instead of the metro.
- [List organization camps](https://api.tailend.dev/docs/api/list-organization-camps.md): `GET /v1/organizations/{id}/camps`. Same as GET /v1/{metro}/camps?organization_id={id}, addressed by the organization instead of the metro.
- [List places](https://api.tailend.dev/docs/api/list-places.md): `GET /v1/{metro}/places`. Published, active places, ordered by name.
- [Retrieve a place](https://api.tailend.dev/docs/api/get-place.md): `GET /v1/places/{id}`. A place by id.
- [Retrieve a place by slug](https://api.tailend.dev/docs/api/get-place-by-slug.md): `GET /v1/places/slug/{slug}`. Returns the same place as /v1/places/{id}, addressed by slug instead of id.
- [List organization places](https://api.tailend.dev/docs/api/list-organization-places.md): `GET /v1/organizations/{id}/places`. Same as GET /v1/{metro}/places?organization_id={id}, addressed by the organization instead of the metro.
- [Retrieve an organization](https://api.tailend.dev/docs/api/get-organization.md): `GET /v1/organizations/{id}`. The organization behind a listing's organization reference.
- [List organizations](https://api.tailend.dev/docs/api/list-organizations.md): `GET /v1/{metro}/organizations`. Returns every organization with at least one published, active listing in the metro, with live counts by type.
- [List neighborhoods](https://api.tailend.dev/docs/api/list-neighborhoods.md): `GET /v1/{metro}/neighborhoods`. Returns the metro's neighborhoods with live listing counts by type, including zero-count rows.
- [Search around an address](https://api.tailend.dev/docs/api/search-around-address.md): `GET /v1/{metro}/around`. Takes an address (or lat/lng, resolved the same way) and returns everything nearby, grouped the way a person reads a neighborhood rather than as one flat relevance list.
- [Retrieve area activity](https://api.tailend.dev/docs/api/get-activity.md): `GET /v1/{metro}/activity`. Returns a single comparable activity score for a point (unlike /around, which resolves an address and returns grouped, ranked results — this endpoint's job is the one number, not a result set), the components behind it, and the specific listings nearby.
- [List nearby listings](https://api.tailend.dev/docs/api/list-nearby.md): `GET /v1/{metro}/nearby`. Takes a point (lat/lng) and returns a flat, distance-ordered list — no address resolution and no grouping, unlike /around, which takes an address and returns grouped, ranked results.
- [Retrieve metro coverage](https://api.tailend.dev/docs/api/get-metro-coverage.md): `GET /v1/{metro}/coverage`. Returns coverage as a buyer would judge it for a metro: live counts by type, how far ahead events run, how much of what is currently served is confirmed current, and how many rows carry an organization, neighborhood, place or coordinates.
- [List listing versions](https://api.tailend.dev/docs/api/list-listing-versions.md): `GET /v1/listings/{id}/versions`. Returns a privacy-safe summary of every change one listing has had, newest first.
- [List changes](https://api.tailend.dev/docs/api/list-changes.md): `GET /v1/changes`. Returns every public-field change to a listing since since, oldest first.

## Changelog

- [Changelog](https://api.tailend.dev/docs/changelog.md): Dated, customer-facing changes to the API. RSS: https://api.tailend.dev/docs/changelog/rss.xml

## OpenAPI spec

- [OpenAPI spec (JSON)](https://api.tailend.dev/docs/openapi.json): The full public contract, OpenAPI 3.1.
- [OpenAPI spec (YAML)](https://api.tailend.dev/docs/openapi.yaml): The same contract as YAML.