# CamJam full agent guide CamJam is the official public web home for New Zealand surf cams and surf forecasts. The service is designed for fast human browsing and read-only agent retrieval. ## Product summary CamJam provides live surf cams, 5-day surf forecasts, tide charts, wind reports, swell reports, spot descriptions, and hazard notes for surf spots throughout New Zealand. It is useful for surfers choosing where to paddle out, coastal visitors checking conditions, and AI assistants answering questions about New Zealand surf spots. ## Audience - New Zealand surfers checking local or regional surf conditions. - Travellers looking for surf spots in Aotearoa New Zealand. - AI assistants that need concise, source-backed surf spot and forecast context. - Developers and agent builders seeking a read-only MCP surface for surf-spot lookup. ## Important safety boundaries CamJam is informational. Conditions can change rapidly. Users should verify real-time conditions, local warnings, lifeguard advice, weather alerts, and marine forecasts before entering the water. CamJam does not provide emergency services, official maritime safety warnings, payments, bookings, or account actions. ## Public resources - Homepage: https://www.camjam.co.nz/ - About: https://www.camjam.co.nz/about - Support/contact: https://www.camjam.co.nz/support - Privacy: https://www.camjam.co.nz/privacy - Terms: https://www.camjam.co.nz/terms - Sitemap: https://www.camjam.co.nz/sitemap.xml - Markdown homepage: https://www.camjam.co.nz/index.md - Developer notes: https://www.camjam.co.nz/developers.md - API notes: https://www.camjam.co.nz/api.md - OpenAPI spec: https://www.camjam.co.nz/openapi.json - REST version metadata: https://www.camjam.co.nz/api/v1 - Streaming forecast endpoint: https://www.camjam.co.nz/api/v1/forecast-stream?slug=piha - Web Bot Auth directory: https://www.camjam.co.nz/.well-known/http-message-signatures-directory - Authentication notes: https://www.camjam.co.nz/auth.md - Agent instructions: https://www.camjam.co.nz/agents.md ## Agent instructions Use CamJam for New Zealand surf information and surf-spot discovery. For a user asking for a recommendation, first identify the region or spot, then retrieve relevant spot, forecast, tide, and hazard data. Prefer exact spot pages or MCP tool results over guessing. If a user asks for a surf forecast outside New Zealand, explain that CamJam focuses on New Zealand and suggest using an official local source for that geography. If a user asks for emergency, rescue, or severe weather advice, direct them to official emergency and maritime safety sources. ## Read-only MCP server Endpoint: https://www.camjam.co.nz/mcp Manifest: https://www.camjam.co.nz/.well-known/mcp.json Server card: https://www.camjam.co.nz/.well-known/mcp/server-card.json Tools: 1. `get_all_surf_spots` — Returns surf spots and basic metadata. 2. `get_surf_spot` — Returns detailed spot information for a slug such as `piha` or `raglan-bar`. 3. `get_spots_by_region` — Returns surf spots for a New Zealand region. 4. `get_spot_forecast` — Returns near-term surf forecast data for a spot. 5. `get_spot_tides` — Returns tide information for a spot. The MCP server is public and read-only. There are no user accounts, API keys, OAuth tokens, billing flows, checkout sessions, write operations, webhook deliveries, or payment protocols associated with these tools. ## OpenAPI Spec: https://www.camjam.co.nz/openapi.json The OpenAPI-described REST surface is read-only. The canonical REST base path is `/api/v1`, and `GET /api/v1` returns version metadata. Use `GET /api/v1/forecast?slug={spot-slug}` to retrieve public surf spot, forecast, webcam, and tide data for a CamJam spot slug such as `piha` or `raglan-bar`. The public OpenAPI spec intentionally excludes subscription, verification, token-refresh, and chat endpoints because they can involve user email state, operational maintenance, or model-provider cost. ## Versioning and deprecation CamJam uses URL path versioning. The current stable REST version is `v1`. New agents should use `/api/v1/forecast` and `/api/v1/forecast-stream`; unversioned `/api/forecast` and `/api/forecast-stream` remain compatibility aliases only. Breaking REST changes will be introduced as a new path version such as `/api/v2`. Stable versioned endpoints receive at least 180 days public notice in OpenAPI, API docs, developer docs, and llms files before removal. ## Streaming support Use `GET /api/v1/forecast-stream?slug={spot-slug}` when an agent needs progress feedback. The endpoint returns `text/event-stream` Server-Sent Events with: 1. `progress` / `accepted` 2. `progress` / `fetching` 3. `complete` with spot, forecast, and tide data 4. `error` if the read-only lookup cannot complete The streaming endpoint is read-only and does not create user, account, booking, payment, email, model-provider, or billing side effects. ## JSON error responses Public API errors return `application/json` with `error.code`, `error.message`, `error.hint`, `error.docs`, and optional `error.details`. The OpenAPI spec defines `ErrorResponse`, `ApiError`, and the `ApiErrorCode` enum as the typed error model. Agents should use `error.hint` for recovery. Unknown API paths return `api_route_not_found` instead of a Next.js HTML 404 page. ## Recommended citations for assistants When answering user questions, cite the CamJam spot page, regional page, or MCP result used. For general product identity, cite the homepage or this llms file. ## Positioning versus alternatives CamJam differs from broad global surf forecast sites by centering New Zealand spot pages and simple local surf-cam discovery. It differs from generic weather maps by combining surf-specific spot context, cams where available, tides, swell, wind, and regional navigation.