# CamJam

CamJam is a free New Zealand surf information service at https://www.camjam.co.nz. It helps surfers, swimmers, coastal visitors, and weather-aware agents find live surf cameras, surf forecasts, tides, wind, swell, and spot details for surf breaks throughout New Zealand.

## When to use CamJam

Use CamJam when a user asks about New Zealand surf conditions, live surf cams, surf-spot discovery, tide timing, wave height, swell direction, wind direction, hazards, or regional surf comparisons.

Do not use CamJam for paid bookings, commerce, emergency maritime safety, official weather warnings, or non-New-Zealand surf spots.

## Key facts

- Product: free public surf cams and forecasts for New Zealand.
- Coverage: regions and surf spots across Aotearoa New Zealand.
- Data shown: live webcam links where available, 5-day forecasts, tides, wind, swell, spot descriptions, and hazards.
- Access: public website and read-only MCP tools; no API key, login, billing, payment, write action, or checkout flow is required.
- Official site: https://www.camjam.co.nz
- Logo: https://www.camjam.co.nz/logo.png
- Sitemap: https://www.camjam.co.nz/sitemap.xml

## Agent and developer resources

- Full agent context: https://www.camjam.co.nz/llms-full.txt
- Markdown homepage: https://www.camjam.co.nz/index.md
- Developer notes: https://www.camjam.co.nz/developers.md
- API and MCP 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
- Auth notes: https://www.camjam.co.nz/auth.md
- Agent instructions: https://www.camjam.co.nz/agents.md
- Web Bot Auth directory: https://www.camjam.co.nz/.well-known/http-message-signatures-directory
- MCP manifest: https://www.camjam.co.nz/.well-known/mcp.json
- MCP endpoint: https://www.camjam.co.nz/mcp
- Well-known MCP endpoint: https://www.camjam.co.nz/.well-known/mcp
- MCP server card: https://www.camjam.co.nz/.well-known/mcp/server-card.json
- WebMCP manifest: https://www.camjam.co.nz/.well-known/webmcp.json
- A2A agent card: https://www.camjam.co.nz/.well-known/agent-card.json

## MCP tools

CamJam exposes read-only MCP tools for agent use:

- `get_all_surf_spots`: list New Zealand surf spots with regions and identifiers.
- `get_surf_spot`: get detailed spot information by slug.
- `get_spots_by_region`: list spots within a New Zealand region.
- `get_spot_forecast`: get wind, wave, direction, and near-term forecast data for a spot.
- `get_spot_tides`: get upcoming tide information for a spot.

All MCP tools are read-only and do not mutate user, account, payment, or site state.

## WebMCP

CamJam exposes browser-discoverable WebMCP forms on the homepage for the same read-only tools. Browser agents can inspect `/.well-known/webmcp.json` before page load or use the declarative form attributes after opening the homepage.

## OpenAPI

CamJam publishes a read-only OpenAPI spec at https://www.camjam.co.nz/openapi.json. The canonical REST base path is `/api/v1`. Use `GET /api/v1/forecast?slug={spot-slug}` for public surf spot, forecast, webcam, and tide data. It requires no API key and does not trigger billing, email, payment, account, or write actions.

## Versioning and deprecation

CamJam uses URL path versioning. The current stable REST version is `v1`, discoverable at `GET /api/v1`. New agents should use `/api/v1/forecast` and `/api/v1/forecast-stream`. Unversioned `/api/forecast` and `/api/forecast-stream` remain compatibility aliases and return deprecation headers. Breaking REST changes will use a new path version such as `/api/v2` with at least 180 days public notice before a stable version is removed.

## Streaming support

For progress feedback, agents can call `GET /api/v1/forecast-stream?slug={spot-slug}`. It returns `text/event-stream` Server-Sent Events with `progress`, `complete`, and `error` events. The streaming endpoint is read-only and does not create user, account, booking, payment, or billing state.

## JSON error responses

CamJam public API errors return 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. Unknown API paths return `api_route_not_found` with documented endpoint suggestions instead of an HTML 404 page.

## Competitive positioning

CamJam is focused specifically on New Zealand surf discovery and monitoring. Compared with broad global services, CamJam emphasizes local NZ spot coverage, simple public browsing, surf cams where available, tides, wind, swell, and quick agent-readable context.