# CamJam API and MCP notes

CamJam does not publish a write API or transactional REST API. The public integration surfaces are a read-only OpenAPI-described forecast endpoint and a read-only MCP server for New Zealand surf information.

## OpenAPI

Canonical spec: https://www.camjam.co.nz/openapi.json

Read-only REST endpoint:

- `GET /api/v1` returns the current stable REST API version, endpoint list, and deprecation policy.
- `GET /api/v1/forecast?slug={spot-slug}` returns the public surf spot record, forecast points, webcam links, and tide data for a CamJam surf spot slug such as `piha` or `raglan-bar`.
- `GET /api/v1/forecast-stream?slug={spot-slug}` returns the same style of public surf context as Server-Sent Events (SSE) with progress updates.

This OpenAPI spec intentionally excludes subscription, verification, token-refresh, and chat endpoints because those surfaces can involve user email state, operational maintenance, or model-provider cost.

## Versioning and deprecation policy

CamJam uses URL path versioning for the public read-only REST API. The current stable base path is `/api/v1`.

New agents and integrations should use `/api/v1/forecast` and `/api/v1/forecast-stream`. The older unversioned `/api/forecast` and `/api/forecast-stream` routes remain read-only compatibility aliases, but they are not canonical for new clients.

Breaking REST API changes will be introduced as a new URL path version such as `/api/v2`. Stable versioned endpoints receive at least 180 days public notice in `/openapi.json`, `/api.md`, `/developers.md`, and `/llms.txt` before removal. Deprecated aliases return `Deprecation: true` and `Link` headers pointing to the successor path and this policy.

## Streaming support

CamJam supports read-only streaming responses for agents through `GET /api/v1/forecast-stream?slug={spot-slug}`. The response content type is `text/event-stream; charset=utf-8`.

SSE event sequence:

1. `progress` with `status: accepted`.
2. `progress` with `status: fetching`.
3. `complete` with final spot, forecast, and tide data.
4. `error` if the lookup fails after the stream starts.

Use this endpoint when an agent benefits from progress feedback instead of waiting for a final JSON response.

## JSON error responses

CamJam public API errors return `application/json` instead of HTML. Error responses use this shape:

```json
{
  "error": {
    "code": "missing_slug",
    "message": "The required slug query parameter is missing.",
    "hint": "Pass a CamJam surf spot slug, for example /api/v1/forecast?slug=piha.",
    "docs": "https://www.camjam.co.nz/api.md"
  }
}
```

The OpenAPI spec defines this as a typed model: `ErrorResponse` wraps an `ApiError` object, and `ApiError.code` references the `ApiErrorCode` enum.

Unknown API paths such as `/api/no-such-route` also return structured JSON with `code: "api_route_not_found"` and a list of documented public endpoints.

## MCP

Endpoint: https://www.camjam.co.nz/mcp
Well-known endpoint alias: https://www.camjam.co.nz/.well-known/mcp
WebMCP manifest: https://www.camjam.co.nz/.well-known/webmcp.json

Available read-only tools:

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

## Security and billing

There are no payments, billing plans, OAuth scopes, webhook secrets, or customer-data mutation endpoints associated with the public OpenAPI/MCP integration surface.