Destination access

Destination access is the primary access-answer endpoint for agent flows. Use it after destination discovery when the caller needs a destination-level verdict, path coverage, and the reason behind the current answer.

Direction-aware segments keep the arrival-oriented answer separate from disclosure: arrival_direction names travel toward the destination, while restriction_items[].direction names the flow affected by each disclosed source row.

Parameters

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

destination

Path Required

string

Canonical destination slug from GET /v1/destinations. Use a live slug such as big-bear, mammoth-lakes, dodge-ridge, or bear-valley. Unknown slugs return 404 DESTINATION_NOT_FOUND.

jurisdiction

Query Optional

string

Optional for the active California v1 surface. If omitted, the effective jurisdiction defaults to US-CA. If provided, it must canonicalize to US-CA or the request returns INVALID_PARAMETER or INVALID_JURISDICTION.

Name	Location	Required	Type	Description
destination	Path	Yes	string	Canonical destination slug from GET /v1/destinations. Use a live slug such as big-bear, mammoth-lakes, dodge-ridge, or bear-valley. Unknown slugs return 404 DESTINATION_NOT_FOUND.
jurisdiction	Query	No	string	Optional for the active California v1 surface. If omitted, the effective jurisdiction defaults to US-CA. If provided, it must canonicalize to US-CA or the request returns INVALID_PARAMETER or INVALID_JURISDICTION.

Example request

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

cURL

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

TypeScript

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

const payload = await response.json();

Python

import requests

response = requests.get(
    "https://api.mountainswitch.co/v1/destinations/big-bear/access",
    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",
    "jurisdiction": "US-CA",
    "coverage": "full",
    "access_state": "restricted",
    "reason_excerpt": "Chains or traction devices are required on SR-330.",
    "paths": [
      {
        "id": "ca:big-bear:west_via_330_18",
        "label": "West approach via SR-330 and SR-18",
        "role": "primary",
        "coverage": "full",
        "access_state": "restricted",
        "reason_excerpt": "Chains or traction devices are required on SR-330.",
        "segments": [
          {
            "id": "ca:big-bear:sr330_highland_to_running_springs",
            "route": "SR-330",
            "route_slug": "sr-330",
            "label": "Highland to Running Springs",
            "role": "primary",
            "start_boundary_label": "Highland",
            "end_boundary_label": "Running Springs",
            "coverage": "full",
            "access_state": "restricted",
            "reason_excerpt": "Chains or traction devices are required from Highland to Running Springs.",
            "segment_description": null,
            "type_of_closure": null,
            "type_of_work": null,
            "lanes_closed": null,
            "total_existing_lanes": null,
            "estimated_delay_minutes": null,
            "valid_until": "2026-04-15T18:00:00Z",
            "chain_control_severity": 3,
            "chain_control_raw": "R-2",
            "restriction_items": [
              {
                "reason_excerpt": "Chains or traction devices are required from Highland to Running Springs.",
                "direction": "both",
                "segment_description": null,
                "type_of_closure": null,
                "type_of_work": null,
                "lanes_closed": null,
                "total_existing_lanes": null,
                "estimated_delay_minutes": null,
                "valid_until": "2026-04-15T18:00:00Z",
                "chain_control_severity": 3,
                "chain_control_raw": "R-2"
              }
            ]
          },
          {
            "id": "ca:big-bear:sr18_running_springs_to_big_bear",
            "route": "SR-18",
            "route_slug": "sr-18",
            "label": "Running Springs to Big Bear Dam",
            "role": "primary",
            "start_boundary_label": "Running Springs",
            "end_boundary_label": "Big Bear Dam / SR-38 junction",
            "coverage": "full",
            "access_state": "open",
            "reason_excerpt": null,
            "segment_description": null,
            "type_of_closure": null,
            "type_of_work": null,
            "lanes_closed": null,
            "total_existing_lanes": null,
            "estimated_delay_minutes": null,
            "valid_until": null,
            "chain_control_severity": null,
            "chain_control_raw": null,
            "restriction_items": []
          }
        ]
      },
      {
        "id": "ca:big-bear:east_via_38",
        "label": "East approach via SR-38",
        "role": "alternate",
        "coverage": "full",
        "access_state": "restricted",
        "reason_excerpt": "One lane is closed on SR-38 approaching Big Bear Valley.",
        "segments": [
          {
            "id": "ca:big-bear:sr38_redlands_to_big_bear",
            "route": "SR-38",
            "route_slug": "sr-38",
            "label": "Redlands / Mentone to Big Bear Valley",
            "role": "alternate",
            "start_boundary_label": "Redlands / Mentone",
            "end_boundary_label": "Big Bear Valley",
            "coverage": "full",
            "access_state": "restricted",
            "reason_excerpt": "One lane is closed on SR-38 approaching Big Bear Valley.",
            "segment_description": "SR-38 approaching Big Bear Valley",
            "type_of_closure": "Lane closure",
            "type_of_work": "Emergency work",
            "lanes_closed": 1,
            "total_existing_lanes": 2,
            "estimated_delay_minutes": 20,
            "valid_until": "2026-04-15T20:00:00Z",
            "chain_control_severity": null,
            "chain_control_raw": null,
            "restriction_items": [
              {
                "reason_excerpt": "One lane is closed on SR-38 approaching Big Bear Valley.",
                "direction": "E",
                "segment_description": "SR-38 approaching Big Bear Valley",
                "type_of_closure": "Lane closure",
                "type_of_work": "Emergency work",
                "lanes_closed": 1,
                "total_existing_lanes": 2,
                "estimated_delay_minutes": 20,
                "valid_until": "2026-04-15T20:00:00Z",
                "chain_control_severity": null,
                "chain_control_raw": null
              }
            ]
          },
          {
            "id": "ca:big-bear:sr18_greenway_to_big_bear",
            "route": "SR-18",
            "route_slug": "sr-18",
            "label": "Big Bear City to Big Bear Valley",
            "role": "connector",
            "start_boundary_label": "Big Bear City",
            "end_boundary_label": "Big Bear Valley",
            "coverage": "full",
            "access_state": "open",
            "reason_excerpt": null,
            "segment_description": null,
            "type_of_closure": null,
            "type_of_work": null,
            "lanes_closed": null,
            "total_existing_lanes": null,
            "estimated_delay_minutes": null,
            "valid_until": null,
            "chain_control_severity": null,
            "chain_control_raw": null,
            "restriction_items": []
          }
        ]
      }
    ]
  },
  "_meta": {
    "sources": [
      {
        "source": "ca-d8-chain-controls",
        "freshness": "healthy",
        "live_eligible": true,
        "covers_query": true,
        "source_updated_at": "2026-04-15T16:50:00Z",
        "fetched_at": "2026-04-15T16:55:00Z"
      },
      {
        "source": "ca-d8-lane-closures",
        "freshness": "healthy",
        "live_eligible": true,
        "covers_query": true,
        "source_updated_at": "2026-04-15T16:45:00Z",
        "fetched_at": "2026-04-15T16:55:00Z"
      }
    ],
    "query_coverage": "full",
    "request_id": "req_destination_access_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.

destination: string; Canonical destination slug for the requested access answer.
jurisdiction: string; Canonical jurisdiction code. For the active California v1 surface, this resolves to US-CA.
coverage: "full" | "partial" | "none"; Destination-level aggregation coverage across the destination's known access paths.
access_state: "open" | "advisory" | "restricted" | "closed" | null"; Destination-level answer. When coverage is insufficient for a confident answer, this becomes null instead of synthesizing open.
reason_excerpt: string | null; Compact explanation for the current destination, path, or segment answer. Open and unknown answers return null.
paths: Array<object>; Ordered access paths for the destination, each with its own coverage, access_state, and segment detail.
paths[].segments[].route_slug: string; Stable route slug for the segment's route, such as sr-330 or sr-38.
paths[].segments[].arrival_direction: "N" | "S" | "E" | "W" | omitted; Optional normalized direction of travel toward the destination across this segment. The property is absent unless the access registry affirms an arrival orientation.
paths[].segments[].start_boundary_label: string; Human-readable start boundary for the segment.
paths[].segments[].end_boundary_label: string; Human-readable end boundary for the segment.
paths[].segments[].segment_description: string | null; Winner-row descriptive text for the segment when a matched restriction or work row provides it.
paths[].segments[].type_of_closure: string | null; Closure type from the winner row when lane-closure detail exists.
paths[].segments[].type_of_work: string | null; Work classification from the winner row when present.
paths[].segments[].lanes_closed: number | null; Closed-lane count from the gated winner row when lane-closure detail exists. Disclosure-only rows remain available under restriction_items.
paths[].segments[].total_existing_lanes: number | null; Total lane count paired with lanes_closed when the matched row provides it.
paths[].segments[].estimated_delay_minutes: number | null; Delay estimate from the matched lane-closure row when available.
paths[].segments[].valid_until: string | null; ISO timestamp for the winner row's current validity window when the source provides one.
paths[].segments[].chain_control_severity: number | null; Additive chain-control severity for the segment winner row. Lane-closure-backed rows may legally return null.
paths[].segments[].chain_control_raw: string | null; Raw chain-control code for the segment winner row when chain-control data is present.
paths[].segments[].restriction_items: Array<object>; Disclosure-complete structured detail for every matched non-open persisted row on the segment. Admitted rows are ordered before direction-excluded rows, so an item may remain disclosed without driving access_state. This field is always present and becomes [] when no live-eligible non-open rows match.
paths[].segments[].restriction_items[].direction: "N" | "S" | "E" | "W" | "both" | null; Normalized travel direction affected by this disclosed row. When arrival_direction is affirmed, an exactly opposite full-coverage Mainline or Conventional Hwy lane row remains disclosed here but is excluded from the segment winner.
paths[].segments[].restriction_items[].chain_control_severity: number | null; Per-row additive chain-control severity mirrored directly from the matched persisted restriction item.
paths[].segments[].restriction_items[].chain_control_raw: string | null; Per-row additive chain-control code mirrored directly from the matched persisted restriction item.
_meta.sources: Array<object>; Current adapter coverage records for the destination scope, ordered by source ascending.
_meta.query_coverage: "full" | "partial" | "none"; Endpoint-wide source coverage signal. Check this before treating the destination answer as fully verified.
_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 destination access is a non-paginated data 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 jurisdiction resolves to a known code other than US-CA.
400	INVALID_JURISDICTION	The provided jurisdiction value does not canonicalize to a known jurisdiction code.
404	DESTINATION_NOT_FOUND	The destination slug is unknown or unsupported for the requested jurisdiction.
429	RATE_LIMIT_EXCEEDED	The caller exceeded the shared API rate limit.
503	SERVICE_UNAVAILABLE	D1 or another critical dependency is unavailable. Source coverage gaps remain HTTP 200 with query_coverage instead of switching to 503.

Notes

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

Use destination access for the primary answer

Start with GET /v1/destinations when the caller needs to discover the live slug. Once the slug is known, use destination access before route summary or raw conditions for the destination-level reachability answer.

Coverage describes confidence, not just freshness

Check _meta.query_coverage, source freshness, source live_eligible, and the per-object coverage values for destination, path, and segment rows. Stale-but-usable sources may still support an access answer. When coverage is partial or none, access_state can be null and clients must not synthesize open.

Direction separates the access answer from full disclosure

When arrival_direction is present, clients can read it as the direction of travel toward the destination. restriction_items[].direction describes the travel flow affected by each disclosed row. Do not infer that every restriction_items entry drove access_state; use the segment's singular fields for the gated winner and restriction_items for the complete matched disclosure.

Only full coverage responses are cacheable

This endpoint follows the fresh-full-only cache posture. The API caches responses only when _meta.query_coverage is full and every covering source is below the stale threshold. Stale-but-usable, partial, and none responses are no-store and should be treated as uncached live reads.