API Reference

API reference

Every endpoint, parameter, field and status code, generated from the OpenAPI spec.

View as Markdown OpenAPI JSON OpenAPI YAML

Each endpoint page below is generated from the OpenAPI spec, so it always matches what the API does. Every page shows the parameters, the response fields, an example request and a sample body for each status code, and a Try it panel: try any request with sample data, no key needed, or paste a key to run it live.

Base URL

Text

https://api.tailend.dev

Every endpoint is a GET under /v1. The API is read-only.

Authentication

Send your API key in the X-API-Key header on every request.

cURL

curl -H "X-API-Key: $TAILEND_API_KEY" https://api.tailend.dev/v1/metros

A missing or revoked key returns 401; a key without access to a metro, type or add-on returns 403. See Authentication.

Responses

Lists return { "data": [...], "meta": {...} }; single reads return { "data": {...} }. Failures return one error envelope:

JSON

{ "error": { "code": "not_found", "message": "unknown metro 'boston'", "request_id": "req_7431b51e10ec2b77" } }

Status	Means
`200`	Success
`304`	Not modified, when you send `If-None-Match` (Caching)
`400`	The request is invalid; `details` names the parameter
`401`	Missing, invalid or revoked key
`403`	Your key is not entitled to this metro, type, add-on or feature
`404`	Unknown metro, id or slug
`405`	Not a `GET`
`429`	Rate limit or monthly quota reached; read `error.code` and `Retry-After`
`500`	Our error; retry once, then report the `request_id`
`501`	Not available on this deployment; do not retry
`503`	Temporarily unavailable; retry after `Retry-After`

Branch on error.code, not on the status. The full list is in Errors.

Endpoints

Metros

Cities the product serves.

GET/v1/metrosList metros

Search

Unified discovery across listing collections.

GET/v1/{metro}/searchSearch every listing collection

Events

Single occurrences with a local start (and optional end) time.

GET/v1/{metro}/eventsList events GET/v1/{metro}/events/calendarEvent counts per day GET/v1/events/{id}Retrieve an event GET/v1/events/slug/{slug}Retrieve an event by slug GET/v1/places/{id}/eventsList place events GET/v1/organizations/{id}/eventsList organization events

Classes

Enrollable programs with a term, a weekly schedule and tuition.

GET/v1/{metro}/classesList classes GET/v1/classes/{id}Retrieve a class GET/v1/classes/slug/{slug}Retrieve a class by slug GET/v1/places/{id}/classesList place classes GET/v1/organizations/{id}/classesList organization classes

Camps

Camps and their sessions (dated, priced blocks).

GET/v1/{metro}/campsList camps GET/v1/camps/{id}Retrieve a camp GET/v1/camps/slug/{slug}Retrieve a camp by slug GET/v1/places/{id}/campsList place camps GET/v1/organizations/{id}/campsList organization camps

Places

Places, with hours, admission, birthday and class facts.

GET/v1/{metro}/placesList places GET/v1/places/{id}Retrieve a place GET/v1/places/slug/{slug}Retrieve a place by slug GET/v1/organizations/{id}/placesList organization places

Organizations

The organization behind a listing.

GET/v1/organizations/{id}Retrieve an organization

Directory

Who publishes in a metro and where — organizations and neighborhoods with live counts.

GET/v1/{metro}/organizationsList organizations GET/v1/{metro}/neighborhoodsList neighborhoods

Address search

Search around an address: one response with grouped, ranked results and an activity summary.

GET/v1/{metro}/aroundSearch around an address

Activity

How lively a point is, computed from the listings near it.

GET/v1/{metro}/activityRetrieve area activity GET/v1/{metro}/nearbyList nearby listings

Coverage

How much, how fresh, and how clean a metro's data is.

GET/v1/{metro}/coverageRetrieve metro coverage

Changes

Versions feed for incremental sync.

GET/v1/listings/{id}/versionsList listing versions GET/v1/changesList changes