# Run Cebu full agent guide

Run Cebu helps runners, coaches, travel planners, and agents find public running events in Cebu and the Philippines. The site publishes a human calendar, a REST API, OpenAPI metadata, a well-known API catalog, Markdown representations, and a read-only Model Context Protocol endpoint.

## Use cases

- Find upcoming races in Cebu City, Cebu Province, and other Philippine destinations.
- Compare events by date, location, distance, and category.
- Build a season calendar for marathons, half marathons, 10K, 5K, trail, ultra, kids, and community runs.
- Retrieve official organizer or registration links.
- Check one event by UUID after a user shares a Run Cebu event link.

## Limitations

Run Cebu is an informational directory. It does not own, organize, sponsor, or operate the listed events. Event information can change without notice. Always confirm event fees, registration deadlines, routes, inclusions, cut-off times, schedule changes, and cancellation status with the official organizer.

## REST API

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

Public reads:

- `GET /api/events`
- `GET /api/events/{eventId}`

Versioning:

- Current stable contract: `2026-08-27`.
- Optional request header: `Run-Cebu-API-Version: 2026-08-27`.
- Breaking API changes use a new version value. Deprecated versions or operations publish `Deprecation` and `Sunset` headers before removal.

List filters:

- `limit`: integer from 1 to 100, default 25.
- `offset`: integer from 0, default 0.
- `date_from`: YYYY-MM-DD lower bound.
- `date_to`: YYYY-MM-DD upper bound.
- `distance`: distance tag such as 5K, 10K, half marathon, marathon, trail, or ultra.
- `category`: category tag such as Road, Trail, Ultra, Kids, or Fun Run.

Scoped writes:

- `POST /api/events` requires `events:write`.
- `PATCH /api/events/{eventId}` requires `events:write`.
- `DELETE /api/events/{eventId}` requires `events:delete`.

Authentication uses an API key in the `X-API-Key` header. Keys are issued by Run Cebu for approved agent or maintainer workflows and are assigned roles that map to supported scopes.

## Error handling

API errors use RFC 9457 problem details with `Content-Type: application/problem+json`. Error responses include `type`, `title`, `status`, `detail`, `code`, and a compatibility `error` object with `code` and `message`.

## Rate limits

Public machine-readable responses publish current IETF RateLimit fields:

- `RateLimit-Policy: "public";q=120;w=60`
- `RateLimit: "public";r=119;t=60`

Clients should cache stable event metadata, use conditional or delayed polling where possible, and back off when remaining quota is low.

## MCP

The MCP endpoint is `https://runcebu.com/mcp` and uses Streamable HTTP with JSON-RPC 2.0. It currently exposes read-only tools:

- `list_events`: list public Run Cebu events with optional filters.
- `get_event`: fetch one public event by UUID.

The endpoint advertises support for protocol versions `2026-07-28`, `2025-11-25`, `2025-06-18`, and `2025-03-26`.

## Discovery links

- OpenAPI: https://runcebu.com/openapi.json
- API catalog: https://runcebu.com/.well-known/api-catalog
- MCP server card: https://runcebu.com/.well-known/mcp/server-card.json
- MCP manifest compatibility file: https://runcebu.com/.well-known/mcp/manifest.json
- A2A agent card: https://runcebu.com/.well-known/agent-card.json
- Agent skill index: https://runcebu.com/.well-known/agent-skills/index.json
- Protected resource metadata: https://runcebu.com/.well-known/oauth-protected-resource

## Contact

General support and API access requests: contact@runcebu.com

Privacy questions and data requests: privacy@runcebu.com