Destinations

Destinations is the discovery endpoint for destination-first clients. Use it first when the caller needs the live supported destination slugs before requesting destination access or route-specific drilldown.

Parameters

Path and query parameters are documented together so the request surface stays easy to scan.

jurisdiction

Query Optional

string

Optional canonical jurisdiction filter. If omitted, the API returns every live supported destination. In the current California scope, jurisdiction must canonicalize to US-CA.

Name	Location	Required	Type	Description
jurisdiction	Query	No	string	Optional canonical jurisdiction filter. If omitted, the API returns every live supported destination. In the current California scope, jurisdiction must canonicalize to US-CA.

Example request

Use the same endpoint across all three snippets. The tabs switch only the client syntax.

cURL

curl -sS "https://api-staging.mountainswitch.co/v1/destinations?jurisdiction=US-CA" \
  -H "Accept: application/json"

TypeScript

const response = await fetch(
  "https://api-staging.mountainswitch.co/v1/destinations?jurisdiction=US-CA",
  {
    headers: {
      Accept: "application/json",
    },
  },
);

const payload = await response.json();

Python

import requests

response = requests.get(
    "https://api-staging.mountainswitch.co/v1/destinations",
    params={"jurisdiction": "US-CA"},
    headers={"Accept": "application/json"},
)

payload = response.json()

Example response

The example response shows the documented JSON envelope with endpoint data in data and request metadata in _meta.

200 OK application/json

{
  "data": [
    {
      "destination": "big-bear",
      "label": "Big Bear Lake",
      "jurisdiction": "US-CA",
      "jurisdiction_slug": "ca",
      "routes": ["SR-18", "SR-38", "SR-138", "SR-330"],
      "communities": []
    }
  ],
  "_meta": {
    "request_id": "req_destinations_docs",
    "response_generated_at": "2026-04-15T17:00:00Z",
    "pagination": null
  }
}

Response fields

This reference stays flat on purpose so the documented fields remain easy to scan.

data: Array<object>; Live supported destination records ordered by label ascending.
data[].destination: string; Canonical destination slug used by GET /v1/destinations/:destination/access.
data[].label: string; Human-facing destination label.
data[].jurisdiction: string; Canonical API jurisdiction code for the destination record.
data[].jurisdiction_slug: string; Website jurisdiction slug paired with the canonical jurisdiction code.
data[].routes: string[]; Canonical API route values preserved in the destination-owned route order.
data[].communities: string[]; Curated community labels in the destination-owned order. Empty arrays remain valid.
_meta.request_id: string; Request identifier for debugging and support workflows.
_meta.response_generated_at: string; ISO timestamp describing when the API assembled the response.
_meta.pagination: null; Always null because destinations is a non-paginated discovery endpoint.

Errors

These rows keep the repo-wide rate-limit and infrastructure behavior visible without inventing endpoint-specific transport semantics.

Status	Code	When it happens
400	INVALID_PARAMETER	The request contains a repeated or unrecognized query parameter, or a known jurisdiction other than US-CA.
400	INVALID_JURISDICTION	The provided jurisdiction value does not canonicalize to a known jurisdiction code.
429	RATE_LIMIT_EXCEEDED	The caller exceeded the shared API rate limit.
503	SERVICE_UNAVAILABLE	D1 or another critical dependency is unavailable.

Notes

These notes capture the contract edges that matter most for consumers of the endpoint.

Use this endpoint for live discovery

Call GET /v1/destinations first when the caller needs the currently supported destination set. Once the slug is known, continue to destination access for the reachability answer or route summary for a specific route.

This endpoint omits source coverage metadata

GET /v1/destinations returns registry metadata, not live condition-derived truth. The response keeps _meta.request_id, _meta.response_generated_at, and _meta.pagination, but omits _meta.sources and _meta.query_coverage.

Destinations is always a live no-store read

This endpoint is not written to the response KV cache. It returns Cache-Control: no-store even though the response is non-paginated.