SofiaStage Agent API

# 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. - Event, venue and title queries default to scope=sofia; use scope=all for every city or city=<name> for one city. - 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. Defaults to Sofia; add scope=all or city=... for other cities. - [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. - [All-city title search example](https://sofiastage.com/api/v1/events?title=%D0%9A%D0%B0%D1%80%D0%BB%D1%81%D0%BE%D0%BD&scope=all&limit=10): Search title matches in every available city. ## Live examples (validated 2026-02-24) - [Event detail example](https://sofiastage.com/api/v1/events/sh_v1_6e1f0d4d5cf4c734b7e2d4803d5ff7a4?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; accepts scope and city. - [Titles lookup](https://sofiastage.com/api/v1/titles?limit=10): Searchable title list; accepts scope and city. - [Cities lookup](https://sofiastage.com/api/v1/cities?limit=10): Searchable city 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:// […gekürzt]