# API reference

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

Source: https://api.tailend.dev/docs/api

Each endpoint page below is generated from the
[OpenAPI spec](https://api.tailend.dev/docs/openapi.json), 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.

```bash
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](https://api.tailend.dev/docs/authentication.md).

## 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](https://api.tailend.dev/docs/caching.md)) |
| `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](https://api.tailend.dev/docs/errors.md).

## Endpoints

### Metros

- [GET /v1/metros](https://api.tailend.dev/docs/api/list-metros.md): List metros

### Search

- [GET /v1/{metro}/search](https://api.tailend.dev/docs/api/search-listings.md): Search every listing collection

### Events

- [GET /v1/{metro}/events](https://api.tailend.dev/docs/api/list-events.md): List events
- [GET /v1/{metro}/events/calendar](https://api.tailend.dev/docs/api/get-event-calendar.md): Event counts per day
- [GET /v1/events/{id}](https://api.tailend.dev/docs/api/get-event.md): Retrieve an event
- [GET /v1/events/slug/{slug}](https://api.tailend.dev/docs/api/get-event-by-slug.md): Retrieve an event by slug
- [GET /v1/places/{id}/events](https://api.tailend.dev/docs/api/list-place-events.md): List place events
- [GET /v1/organizations/{id}/events](https://api.tailend.dev/docs/api/list-organization-events.md): List organization events

### Classes

- [GET /v1/{metro}/classes](https://api.tailend.dev/docs/api/list-classes.md): List classes
- [GET /v1/classes/{id}](https://api.tailend.dev/docs/api/get-class.md): Retrieve a class
- [GET /v1/classes/slug/{slug}](https://api.tailend.dev/docs/api/get-class-by-slug.md): Retrieve a class by slug
- [GET /v1/places/{id}/classes](https://api.tailend.dev/docs/api/list-place-classes.md): List place classes
- [GET /v1/organizations/{id}/classes](https://api.tailend.dev/docs/api/list-organization-classes.md): List organization classes

### Camps

- [GET /v1/{metro}/camps](https://api.tailend.dev/docs/api/list-camps.md): List camps
- [GET /v1/camps/{id}](https://api.tailend.dev/docs/api/get-camp.md): Retrieve a camp
- [GET /v1/camps/slug/{slug}](https://api.tailend.dev/docs/api/get-camp-by-slug.md): Retrieve a camp by slug
- [GET /v1/places/{id}/camps](https://api.tailend.dev/docs/api/list-place-camps.md): List place camps
- [GET /v1/organizations/{id}/camps](https://api.tailend.dev/docs/api/list-organization-camps.md): List organization camps

### Places

- [GET /v1/{metro}/places](https://api.tailend.dev/docs/api/list-places.md): List places
- [GET /v1/places/{id}](https://api.tailend.dev/docs/api/get-place.md): Retrieve a place
- [GET /v1/places/slug/{slug}](https://api.tailend.dev/docs/api/get-place-by-slug.md): Retrieve a place by slug
- [GET /v1/organizations/{id}/places](https://api.tailend.dev/docs/api/list-organization-places.md): List organization places

### Organizations

- [GET /v1/organizations/{id}](https://api.tailend.dev/docs/api/get-organization.md): Retrieve an organization

### Directory

- [GET /v1/{metro}/organizations](https://api.tailend.dev/docs/api/list-organizations.md): List organizations
- [GET /v1/{metro}/neighborhoods](https://api.tailend.dev/docs/api/list-neighborhoods.md): List neighborhoods

### Address search

- [GET /v1/{metro}/around](https://api.tailend.dev/docs/api/search-around-address.md): Search around an address

### Activity

- [GET /v1/{metro}/activity](https://api.tailend.dev/docs/api/get-activity.md): Retrieve area activity
- [GET /v1/{metro}/nearby](https://api.tailend.dev/docs/api/list-nearby.md): List nearby listings

### Coverage

- [GET /v1/{metro}/coverage](https://api.tailend.dev/docs/api/get-metro-coverage.md): Retrieve metro coverage

### Changes

- [GET /v1/listings/{id}/versions](https://api.tailend.dev/docs/api/list-listing-versions.md): List listing versions
- [GET /v1/changes](https://api.tailend.dev/docs/api/list-changes.md): List changes