# Run Cebu API Documentation

The Run Cebu Events API exposes public race listings and scoped write operations for approved maintainers and agents. Public reads require no credentials and return JSON. Write operations require an API key in the `X-API-Key` header.

Base URL: `https://runcebu.com`

## Versioning

The current stable API contract is `2026-08-27`. Agents may send `Run-Cebu-API-Version: 2026-08-27` to pin documented behavior. Breaking changes use a new version value, and deprecated versions or operations publish `Deprecation` and `Sunset` headers before removal.

## Supported scopes

- `events:read`: read public event records.
- `events:write`: create and update event records.
- `events:delete`: delete event records.

## Error format

API errors use RFC 9457 problem details with `application/problem+json`. Responses include `type`, `title`, `status`, `detail`, `code`, and a compatibility `error` object.

## Rate limits

Public machine-readable responses publish `RateLimit-Policy: "public";q=120;w=60` and `RateLimit: "public";r=119;t=60`. Clients should back off when limits are low and cache stable event metadata when appropriate.

OpenAPI specification: https://runcebu.com/openapi.json