API access and conventions

Choose the right API

These routes power the Rizicon web application. Public endpoints expose crossing data and historical trends, and accept private contact inquiries. Team and AI endpoints are internal beta interfaces for the signed-in application; their payloads can change as the product evolves.

Use the origin of your own deployment as the base URL, followed by the endpoint path. Before a production integration or scheduled bulk transfer, agree with Rizicon on the supported contract, scope and expected load.

Make your first request

Read endpoints use GET with URL query parameters. Mutation endpoints use the method shown on their reference card. For JSON request bodies, send Content-Type: application/json. Keep field names and enum values exactly as documented; locale changes human-facing content, not property names.

curl --get 'https://YOUR_DEPLOYMENT/api/crosswalks' \
  --data-urlencode 'city=YOUR_CITY_SLUG' \
  --header 'Accept: application/json'

const query = new URLSearchParams({ city: 'YOUR_CITY_SLUG' })
const response = await fetch('/api/crosswalks?' + query)
const result = await response.json()

if (!response.ok || result.error) {
  throw new Error(result.error ?? 'Request failed: ' + response.status)
}

console.log(result.crosswalks)

Authentication and permissions

Protected routes use the Supabase session stored in request cookies. Sign in through the application and make requests from the same origin. The server validates the session and reads current role and city permissions from the database.

A Supabase publishable key alone does not grant team access. The browser examples reuse the signed-in session; they do not require copying a token into source code. Keep service-role keys and AI provider secrets out of public code.

const response = await fetch(
  '/api/manage-analysis?kind=cities&page=1&pageSize=25',
  { credentials: 'same-origin', cache: 'no-store' },
)
const result = await response.json()
if (!response.ok) throw new Error(result.error ?? 'Request failed')
console.log(result.items, result.total, result.summary)

Read status codes and response bodies

Response envelopes are specific to each endpoint. Data endpoints return an array and an error field; successful contact mutations return ok. Check the reference for the exact shape instead of assuming every route has a data property.

Filtering and pagination

Always URL-encode query values. Omit optional filters when you want their documented default. Use totals returned by paginated endpoints to decide whether another page is available.