TownSpot API at Agent Discovery

Mga dokumento ng pagtuklas

Ang mga kilalang URL na ito ay tumutulong sa mga ahente at integration clients na matuklasan ang mga serbisyo ng TownSpot nang walang hardcoded assumptions.

• /.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

Agent quickstart

Karamihan sa mga ahente ay nangangailangan ng tatlong gawain: maghanap ng mga kaganapan, magsumite ng isang kaganapan mula sa source URL, pagkatapos ay suriin o i-update ang nilikhang kaganapan.

1. Maghanap ng mga kaganapan sa pamamagitan ng pampublikong listahan ng kaganapan o canonical town page.
2. Magsumite ng source URL ng kaganapan sa pamamagitan ng MCP tool at isama ang idempotency key para sa ligtas na pag-retry.
3. Suriin o i-update ang nilikhang kaganapan gamit ang review endpoint o authenticated MCP tools.

Mga pampublikong endpoint

Ipinapakita ng mga endpoint na ito ang pangunahing discovery at event-write surface para sa mga bayan, kaganapan, lugar, MCP scrape-to-submit flows, at action receipts.

• 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}

Mga halimbawa ng request at response

Maghanap ng mga pampublikong kaganapan para sa isang bayan.

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
    }
  ]
}

Magsumite ng kaganapan mula sa source URL sa pamamagitan ng MCP.

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"
    }
  }
}

Suriin ang isang kaganapan gamit ang authenticated request.

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"]
}

Pagpapatunay

Ang mga protektadong TownSpot admin at venue-manager APIs ay gumagamit ng bearer tokens na inilalabas ng Supabase Auth.

Gamitin ang OpenID Connect at OAuth metadata documents upang programmatically matuklasan ang authorization, token, JWKS, at protected-resource na mga detalye. Maaari ring gamitin ng mga pampublikong submission tools ang event edit tokens, submitter email links, o venue-manage tokens kung saan umiiral na ang daloy na iyon. Maaaring isama ng MCP write tools ang idempotency keys at magbalik ng action receipts upang makapag-retry nang maayos ang mga ahente.

Mga pattern ng Canonical URL

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