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

エージェントクイックスタート

ほとんどのエージェントには、イベントを探す、ソースURLからイベントを送信する、作成されたイベントを確認または更新する、という3つの作業が必要です。

公開イベント一覧または標準の町ページからイベントを探します。
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}