# 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 public GET /v1/* endpoints are read-only and do not require user authentication; POST /v1/admin/sync is disabled and returns 410.
- /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 and stale-while-revalidate headers (meta: 30s, events: 60s, lookups/details: 300s, discovery docs: 3600s).
- 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 (upcoming + includes)](https://sofiastage.com/api/v1/events?limit=25&include=stars,extras): Starter query that remains current as snapshots advance.
- Date/time-window recipe: set date_from and date_to to the same current YYYY-MM-DD, then add starts_after and/or starts_before with tz=Europe/Sofia.
- [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.

## Detail workflows
- Event detail: request https://sofiastage.com/api/v1/events?scope=all&limit=1, then use data[0].id with https://sofiastage.com/api/v1/events/{id}?include=stars,extras.
- Star detail: query https://sofiastage.com/api/v1/stars?q=...&limit=1, then URL-encode data[0].name for https://sofiastage.com/api/v1/star/{slug}; data[0].profile_url is the corresponding human-facing page.
- Extra detail: query https://sofiastage.com/api/v1/extras?q=...&limit=1, then URL-encode data[0].title for https://sofiastage.com/api/v1/extra/{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&view=summary): Searchable compact performer list (omit view for the full card payload).
- [Extras lookup](https://sofiastage.com/api/v1/extras?limit=10&view=summary): Searchable compact editorial/extras list (omit view for full articles).

## 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 in the same ecosystem; it uses this API for city lookup while its main UI payloads come from separate bulk snapshot endpoints.
- [Canonical production API](https://sofiastage.com/api): Public production API base URL.