TownSpot APIとエージェント発見

TownSpotは、公開発見のための機械可読の発見文書、認証されたイベント書き込みワークフロー、スクレイプして提出するMCPツール、アクションレシートを公開しています。

発見文書

これらのよく知られたURLは、エージェントや統合クライアントがハードコーディングされた仮定なしにTownSpotサービスを発見するのに役立ちます。

/.well-known/api-catalog - https://www.townspot.co/.well-known/api-catalog
/.well-known/openid-configuration - https://www.townspot.co/.well-known/openid-configuration
/.well-known/oauth-protected-resource - https://www.townspot.co/.well-known/oauth-protected-resource
/.well-known/mcp/server-card.json - https://www.townspot.co/.well-known/mcp/server-card.json

AIアシスタント向け公開MCP

ChatGPT、Claude、またはその他のMCPクライアントを、人々がつくるローカルイベントガイドTownSpotに接続できます。街全体または特定の地域のイベントを尋ねられます。アカウントは不要で、イベントの作成や編集はできません。

https://api.townspot.co/api/mcp/events
トランスポート：リモートStreamable HTTP。
認証：不要。
利用可能なツール：都市またはタウンの解決、タウン一覧、タウン詳細、都市またはタウン別の公開イベント検索、イベント詳細、会場詳細。
イベント検索とイベント詳細の結果には、現地時刻、明示的な都市と地域、スケジュールラベル、TownSpotの正規リンク、同意で許可された場合の公開「Spotted by」クレジットが含まれます。
検索上限：1回のリクエストにつき最大20件、日付範囲は最大31日です。
この公開コネクタは検索専用です。TownSpotの別のAPIが保護された公開投稿と認証済み編集を処理し、CLIが運営者向けの取り込みチェックを追加します。
サポート： https://www.townspot.co/contact-us

最小限の接続リクエスト：

POST https://api.townspot.co/api/mcp/events
Content-Type: application/json
Accept: application/json, text/event-stream

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-06-18",
    "capabilities": {},
    "clientInfo": { "name": "your-client", "version": "1.0.0" }
  }
}

投稿・運営者API

以下の例は公開マーケットプレイスコネクタとは別です。イベント情報元の投稿は匿名ですが保護されレート制限があります。確認と編集には適切なTownSpot認証情報が必要です。

公開イベント一覧または標準の町ページからイベントを探します。
MCPツールでイベントのソースURLを送信し、安全な再試行のために冪等性キーを含めます。
レビューエンドポイントまたは認証済みMCPツールで、作成されたイベントを確認または更新します。

公開エンドポイント

これらのエンドポイントは、町、イベント、会場、MCPスクレイプして提出するフロー、アクションレシートのための主要な発見とイベント書き込みの表面を公開します。

https://api.townspot.co/api/locations/list
https://api.townspot.co/api/locations/get-by-slug
https://api.townspot.co/api/events/list
https://api.townspot.co/api/submit/event
https://api.townspot.co/api/mcp — MCP tools now include submit_event_from_url plus action receipts and idempotency support for write flows.
https://api.townspot.co/api/submit/event/{uuid}
https://api.townspot.co/api/events/{uuid}/review
https://api.townspot.co/api/p/venues/{slug}
https://api.townspot.co/api/openapi.json
https://api.townspot.co/api/healthz
https://api.townspot.co/api/venue-admin/{slug}/events/{eventUuid}

リクエストとレスポンスの例

町の公開イベントを探します。

GET https://api.townspot.co/api/events/list?zone_id=1&date=2026-05-09

{
  "results": [
    {
      "uuid": "event-uuid",
      "title": "Community market",
      "startTime": "2026-05-09T10:00:00.000Z",
      "venueName": "Town Hall",
      "zoneId": 1
    }
  ]
}

MCPを通じてソースURLからイベントを送信します。

POST https://api.townspot.co/api/mcp
Content-Type: application/json

{
  "jsonrpc": "2.0",
  "id": "submit-1",
  "method": "tools/call",
  "params": {
    "name": "submit_event_from_url",
    "arguments": {
      "url": "https://example.com/events/community-market",
      "idempotencyKey": "community-market-2026-05-09"
    }
  }
}

認証済みリクエストでイベントを確認します。

GET https://api.townspot.co/api/events/{uuid}/review
Authorization: Bearer {supabaseJwt}

{
  "event": {
    "uuid": "event-uuid",
    "title": "Community market",
    "status": "ready_for_review"
  },
  "actions": ["approve", "edit", "request_more_info"]
}

認証

保護されたTownSpot管理者および会場管理者APIは、Supabase Authによって発行されたベアラートークンを使用します。

OpenID ConnectおよびOAuthメタデータ文書を使用して、プログラム的に認証、トークン、JWKS、および保護されたリソースの詳細を発見します。公開提出ツールは、イベント編集トークン、提出者のメールリンク、またはそのフローがすでに存在する場合の会場管理トークンを使用することもできます。MCP書き込みツールには、冪等性キーを含め、エージェントがクリーンに再試行できるようにアクションレシートを返すことができます。

標準URLパターン

https://www.townspot.co/{countryCode}/{townSlug}
https://www.townspot.co/event/{eventSlug}-{eventUuid}
https://www.townspot.co/venue/{venueSlug}