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 提交事件，然后查看或更新创建的事件。

通过公共活动列表或规范城镇页面查找活动。
通过 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}