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.

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. For the active Big Bear MVP flow, use a live slug such as big-bear. Unknown slugs return 404 DESTINATION_NOT_FOUND.

jurisdiction

Query Optional

string

Optional for the active Big Bear MVP. 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. For the active Big Bear MVP flow, use a live slug such as big-bear. Unknown slugs return 404 DESTINATION_NOT_FOUND.
jurisdiction	Query	No	string	Optional for the active Big Bear MVP. 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-staging.mountainswitch.co/v1/destinations/big-bear/access?jurisdiction=US-CA" \
  -H "Accept: application/json"

TypeScript

const response = await fetch(
  "https://api-staging.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-staging.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.",
                "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 Valley",
            "role": "primary",
            "start_boundary_label": "Running Springs",
            "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": []
          }
        ]
      },
      {
        "id": "ca:big-bear:north_via_38",
        "label": "North approach via SR-38",
        "role": "alternate",
        "coverage": "full",
        "access_state": "restricted",
        "reason_excerpt": "One lane is closed on SR-38 approaching Big Bear Lake.",
        "segments": [
          {
            "id": "ca:big-bear:sr38_redlands_to_big_bear_lake",
            "route": "SR-38",
            "route_slug": "sr-38",
            "label": "Redlands to Big Bear Lake",
            "role": "alternate",
            "start_boundary_label": "Redlands",
            "end_boundary_label": "Big Bear Lake",
            "coverage": "full",
            "access_state": "restricted",
            "reason_excerpt": "One lane is closed on SR-38 approaching Big Bear Lake.",
            "segment_description": "SR-38 approaching Big Bear Lake",
            "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 Lake.",
                "segment_description": "SR-38 approaching Big Bear Lake",
                "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
              }
            ]
          }
        ]
      }
    ]
  },
  "_meta": {
    "sources": [
      {
        "source": "ca-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-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 Big Bear MVP flow, 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[].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 winner row when lane-closure detail exists.
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>; Additive structured detail for every matched non-open persisted row on the segment. This field is always present and becomes [] when no live-eligible non-open rows match.
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 for endpoint-wide source health and the per-object coverage values for destination, path, and segment rows. When coverage is partial or none, access_state can be null and clients must not synthesize open.

Only full coverage responses are cacheable

This endpoint follows the Big Bear full-only cache posture. The API caches responses only when _meta.query_coverage is full. Partial and none responses are no-store and should be treated as uncached live reads.