# CantonShare — Public Query API

> Anonymous read-only HTTP API for published trade shows, exhibition venues, and taxonomy.

## Documentation

- Human tools: https://cantonshare.com/tools
- Developers (API + MCP): https://cantonshare.com/developers
- Public API (query + engagement): repo `docs/PUBLIC_QUERY_API.md`
- Agent API (authenticated catalog): repo `docs/AGENT_API.md`
- OpenAPI (query): `openapi/public-query-api.yaml`
- OpenAPI (agent): `openapi/agent-api.yaml`
- MCP server: `@cantonshare/mcp-exhibitions` (`packages/mcp-exhibitions/`)
- Calendar export: https://cantonshare.com/tools/calendar/ics?slug=EVENT_SLUG
- Batch match: POST /api/public/match-events
- Watch changes: POST /api/public/watch-event (per-event or scope=all webhook)
- Embed: https://cantonshare.com/embed/events?q=&limit=5
- Optional Public API Key header: X-Api-Key: cs_… (higher rate limits)

## Base URL

```
https://cantonshare.com/api/public
```

Local development: `http://localhost:3001/api/public`

## Query endpoints (GET, no auth)

| Endpoint | Purpose |
|----------|---------|
| `/health` | Liveness check |
| `/events?q=&category=&tag=&city=&country=&from=&to=&page=&limit=&sort=` | Search published events |
| `/event?slug=` | Single event detail |
| `/venues?q=&city=&country=&page=&limit=` | Search venues |
| `/venue?slug=` | Single venue detail |
| `/categories` | Category directory |
| `/tags` | Tag directory |

## Example

```bash
curl "https://cantonshare.com/api/public/events?q=canton+fair&limit=5"
curl "https://cantonshare.com/api/public/event?slug=ces"
curl "https://cantonshare.com/api/public/venues?country=DE&q=messe"
```

## Rate limits

- Default: 60 requests/minute/IP
- Responses include `Cache-Control: public, max-age=60`

## Authenticated catalog API

`/api/agent/*` requires `Authorization: users API-Key <key>` — see `docs/AGENT_API.md`.

## Terms

Free for programmatic use. Attribute https://cantonshare.com when presenting results. Confirm critical dates against official organizer websites.