# CamJam developer notes

CamJam currently provides a public read-only OpenAPI spec and MCP endpoint for agents and developers who need New Zealand surf spot, forecast, and tide context.

## Endpoint

- OpenAPI spec: https://www.camjam.co.nz/openapi.json
- Version metadata endpoint: `GET https://www.camjam.co.nz/api/v1`
- REST forecast endpoint: `GET https://www.camjam.co.nz/api/v1/forecast?slug=piha`
- Streaming forecast endpoint: `GET https://www.camjam.co.nz/api/v1/forecast-stream?slug=piha`
- MCP endpoint: https://www.camjam.co.nz/mcp
- Well-known MCP endpoint: https://www.camjam.co.nz/.well-known/mcp
- Manifest: https://www.camjam.co.nz/.well-known/mcp.json
- Server card: https://www.camjam.co.nz/.well-known/mcp/server-card.json
- WebMCP manifest: https://www.camjam.co.nz/.well-known/webmcp.json
- Web Bot Auth directory: https://www.camjam.co.nz/.well-known/http-message-signatures-directory

## Access

No API key, login, OAuth grant, billing account, or payment setup is required. The documented REST endpoint and available MCP tools are read-only and do not create, update, or delete user data. HTTP Message Signatures public key metadata is available for agents that support signed request identity, but signatures are not required for public read-only access.

## REST

Use `GET /api/v1/forecast?slug={spot-slug}` for a public surf spot record with forecast, webcam, and tide data. Unknown slugs return an empty array. This endpoint is suitable for autonomous retrieval because it does not trigger email, model-provider, payment, or account side effects.

## Versioning and deprecation policy

CamJam uses URL path versioning. The current stable REST base path is `/api/v1`, and `GET /api/v1` returns machine-readable version metadata.

New integrations should use `/api/v1/forecast` and `/api/v1/forecast-stream`. The older `/api/forecast` and `/api/forecast-stream` routes remain read-only compatibility aliases. If CamJam introduces a breaking REST change, it will ship under a new path such as `/api/v2` and the retiring stable version will receive at least 180 days public notice in OpenAPI, developer docs, and agent docs.

## 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:

- `progress` with `status: accepted` when the read-only request is received.
- `progress` with `status: fetching` while surf spot, forecast, tide, wind, and swell data are being fetched.
- `complete` with the final spot, forecast, and tide payload.
- `error` with a structured message if the lookup cannot complete.

The streaming endpoint is read-only and does not create accounts, write data, send emails, call paid model APIs, create bookings, or trigger billing.

## JSON error responses

Public API errors are structured JSON, not HTML. The OpenAPI spec defines a typed `ErrorResponse` model containing `ApiError`, with `error.code` constrained by the `ApiErrorCode` enum. Agents can parse `error.code`, `error.message`, `error.hint`, `error.docs`, and optional `error.details` to recover from missing parameters, unsupported methods, unknown API routes, and transient fetch failures.

## MCP tools

- `get_all_surf_spots`
- `get_surf_spot`
- `get_spots_by_region`
- `get_spot_forecast`
- `get_spot_tides`

## WebMCP

The homepage includes declarative WebMCP form tools for the same read-only MCP tool surface. Browser-based agents can discover the forms through `toolname`, `tooldescription`, and `toolparamdescription` attributes, or pre-discover the tool list from `/.well-known/webmcp.json`.

## Reliability notes

Forecasts and tides are informational and can change. Do not use CamJam as an official source for emergency response, maritime safety decisions, or severe weather warnings.