Riva dei Coz — API e sviluppatori

Informazioni tecniche per consultare alloggi, prezzi indicativi e contatti. La documentazione tecnica è disponibile in inglese.

# Riva dei Coz API documentation

## When to use this
Compare accommodations, retrieve indicative EUR prices, plan arrival, and find the direct booking link. Quotes do not confirm availability or create reservations. Complete bookings through the booking engine with the guest's approval.

## Quickstart and authentication
Public endpoints and MCP tools are free to read without registration or an API key. Admin statistics require an existing administrator's Supabase Bearer token. Do not request admin access for public stay planning.

curl 'https://www.rivadeicoz.com/api/v1/health'
curl 'https://www.rivadeicoz.com/api/v1/apartment-prices'
curl 'https://www.rivadeicoz.com/api/v1/seasonal-prices'
curl 'https://www.rivadeicoz.com/api/v1/pricing/quote' -H 'Content-Type: application/json' -d '{"apartment":"pink","checkIn":"2027-06-01","checkOut":"2027-06-04","adults":2,"children":0}'

## Endpoints and schemas
- [OpenAPI specification](https://www.rivadeicoz.com/openapi.json): all five REST operations, inputs, success responses, and typed errors.
- GET /api/v1/health: service status.
- GET /api/v1/apartment-prices: headline prices, which may fall back to defaults.
- GET /api/v1/seasonal-prices: seasonal price windows.
- POST /api/v1/pricing/quote: indicative calculation only, with no reservation or payment.
- GET /api/v1/admin/stats: authenticated dashboard statistics.
- [MCP discovery](https://www.rivadeicoz.com/.well-known/mcp/server-card.json): read-only site tools at /api/mcp.
- [Agent skills](https://www.rivadeicoz.com/.well-known/agent-skills/index.json): stay planning instructions.

## Errors
REST errors use application/problem+json (RFC 9457): type, title, status, detail, code, and hint. Existing error fields remain available. A 405 includes Allow. Unknown /api/ paths return JSON 404s. MCP retains its JSON-RPC error model.

## Versioning and deprecation
Version 1 uses /api/v1/. The original /api/ paths are compatible aliases. Breaking changes require a new major URL version. Deprecation notices will be published at /developers before retirement. No version currently has a retirement date.

## Rate limits
The contact form's existing limit is five requests per hour per IP, per server instance. Its responses include RateLimit-Policy and RateLimit using draft-ietf-httpapi-ratelimit-headers-11 syntax, and 429 includes Retry-After in seconds. These are advisory local quotas, not a distributed service guarantee. Public read endpoints do not currently impose a quota. Never automate the contact form or bypass its anti-spam checks.

## Safe testing
GET /api/v1/health is a no-credentials smoke test. The documented public pricing operations are read-only and do not reserve or charge anything, but read production data. There is no separate sandbox, self-service admin key issuance, or published CLI. Use the curl examples above.