# SofiaStage Agent API

> Read-only index for SofiaStage cultural-event data exposed by the Cloudflare Worker API.

Use this file as a compact navigation layer for agents. Use OpenAPI for full schema and field-level details.

## Policies
- All /v1/* endpoints are read-only and do not require user authentication.
- /v1/events uses cursor pagination; cursors are valid only for the same filter set.
- Supported include values are stars and extras.
- Date format is YYYY-MM-DD and date_from must be <= date_to.
- Start-time filters: starts_after and starts_before are inclusive and support HH:mm, local YYYY-MM-DDTHH:mm with tz (default Europe/Sofia), or RFC3339 with offset/Z.
- limit values above 100 are clamped to 100.
- Rate guidance: keep automated traffic polite (about 1-3 requests/second per client) and use exponential backoff on 429/5xx responses.
- Caching guidance: respect Cache-Control headers (events: max-age=60, lookups/detail/meta: max-age=300, discovery docs: max-age=3600).
- Stability guidance: /v1/* read endpoints and response envelopes are stable integration targets; /v1/admin/sync is outside normal public read workflows.
- Attribution guidance: preserve canonical_url/info_url/ticket_url fields when redistributing results and attribute SofiaStage as the aggregator.
- Non-ASCII query values (for example Cyrillic) must be URL-encoded by the client.
- Extras content fields (article, bottom_article) are Markdown.
- Star/extra slug detail routes rely on snapshots; missing snapshot rows return 404.

## Core
- [OpenAPI schema](https://sofiastage.com/api/openapi.json): Complete machine-readable contract.
- [Health check](https://sofiastage.com/api/health): Liveness and deploy status.
- [Metadata](https://sofiastage.com/api/v1/meta): Snapshot/version metadata and record counts.
- [Events feed](https://sofiastage.com/api/v1/events): Primary collection with filtering and pagination.
- [Events example (live date range + includes)](https://sofiastage.com/api/v1/events?date_from=2026-02-23&date_to=2026-02-23&limit=25&include=stars,extras): Starter query validated on 2026-02-24.
- [Events by time window example](https://sofiastage.com/api/v1/events?date_from=2026-02-23&date_to=2026-02-23&starts_before=17:00&tz=Europe/Sofia&limit=25): Starter time-filter query validated on 2026-02-24.

## Live examples (validated 2026-02-24)
- [Event detail example](https://sofiastage.com/api/v1/events/2794069?include=stars,extras): Live play/event detail.
- [Star detail example](https://sofiastage.com/api/v1/star/%D0%91%D0%BE%D1%8F%D0%BD%20%D0%90%D1%80%D1%81%D0%BE%D0%B2): Live performer detail by slug.
- [Extra detail example](https://sofiastage.com/api/v1/extra/%D0%97%D0%BB%D0%B0%D1%82%D0%B5%D0%BD%20%D0%9A%D1%83%D0%BA%D0%B5%D1%80%D0%B8%D0%BA%D0%BE%D0%BD%202026): Live editorial detail by slug.

## Lookups
- [Venues lookup](https://sofiastage.com/api/v1/venues?limit=10): Searchable venue list.
- [Titles lookup](https://sofiastage.com/api/v1/titles?limit=10): Searchable title list.
- [Stars lookup](https://sofiastage.com/api/v1/stars?limit=10): Searchable performer list (use slug with /v1/star/{slug}).
- [Extras lookup](https://sofiastage.com/api/v1/extras?limit=10): Searchable editorial/extras list (use slug with /v1/extra/{slug}).

## Discovery
- [LLMS index](https://sofiastage.com/llms.txt): This file.
- [AI plugin manifest](https://sofiastage.com/.well-known/ai-plugin.json): Plugin discovery metadata.
- [MCP manifest](https://sofiastage.com/.well-known/mcp/manifest.json): MCP server discovery metadata.

## Optional
- [LLMS full guide](https://sofiastage.com/llms-full.txt): Expanded integration guide for agents.
- [SofiaStage website](https://sofiastage.com): Human-facing product that consumes this data.
- [Canonical production API](https://sofiastage.com/api): Public production API base URL.