Developers

Public query API and MCP for published trade shows and venues. Anonymous read works; a Public API Key raises rate limits. Confirm critical dates against official organizer websites.

Base URL

https://cantonshare.com/api/public

Discovery: /llms.txt · Human tools: /tools

Quick examples

curl "https://cantonshare.com/api/public/events?q=canton+fair&limit=5"
curl "https://cantonshare.com/api/public/event?slug=ces"
curl -H "X-Api-Key: cs_YOUR_KEY" "https://cantonshare.com/api/public/events?q=ces"
curl -X POST "https://cantonshare.com/api/public/match-events" \
  -H "Content-Type: application/json" \
  -d '{"queries":["CES","Canton Fair"]}'

Public API Keys

Optional. Created by admins under Automation → Public API Keys. Send on every request:

Authorization: Bearer cs_…
# or
X-Api-Key: cs_…

Default keyed limit is 300 req/min (configurable per key). Anonymous IP default remains 60 req/min. These keys are not for /api/agent writes.

Endpoints

GET /health — liveness
GET /events — search (q, category, tag, city, country, from, to, pagination)
GET /event?slug= — one event
GET /venues / GET /venue?slug=
GET /categories · GET /tags
POST /match-events — batch name match ({ "queries": ["…"] }, max 40)
POST /watch-event — email-only is open; any webhookUrl (per-event or scope: "all") needs a Public API Key

Full reference in the repo: docs/PUBLIC_QUERY_API.md, openapi/public-query-api.yaml.

Rate limits

Anonymous: 60 / minute / IP. With a Public API Key: per-key limit (default 300). Headers: X-RateLimit-Limit, X-RateLimit-Remaining. Exceeded → HTTP 429.

Embed widget

iframe a minimal event list (no site chrome). Query params: q, city, country, from, to, limit (max 20).

<iframe
  src="https://cantonshare.com/embed/events?q=tech&limit=5"
  title="CantonShare events"
  style="width:100%;height:320px;border:0"
></iframe>

MCP (read-only)

Package @cantonshare/mcp-exhibitions wraps the public API for Cursor, Claude Desktop, and similar hosts.

{
  "mcpServers": {
    "cantonshare-exhibitions": {
      "command": "npx",
      "args": ["-y", "@cantonshare/mcp-exhibitions"],
      "env": {
        "CANTONSHARE_API_URL": "https://cantonshare.com"
      }
    }
  }
}

What is not public

Catalog write / verification queues (/api/agent) require a staff API key and are not open for general use. Do not expose agent credentials in client apps.

Terms

Free for programmatic use. Attribute https://cantonshare.com when presenting results. Always confirm dates and venues on the organizer's official site.