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

Pampublikong MCP para sa mga AI assistant

Ikonekta ang ChatGPT, Claude, o ibang MCP client sa TownSpot, ang people-powered na gabay sa mga lokal na event. Itanong kung ano ang mayroon sa buong lungsod o sa isang neighbourhood. Hindi kailangan ng account at hindi ito makakagawa o makakapag-edit ng event.

• https://api.townspot.co/api/mcp/events
• Transport: remote Streamable HTTP.
• Authentication: wala.
• Mga available na tool: tukuyin ang lungsod o Bayan, ilista ang mga Bayan, kumuha ng Bayan, maghanap ng mga naka-publish na event ayon sa lungsod o Bayan, kumuha ng event, at kumuha ng venue.
• Kasama sa event search at event-detail results ang lokal na oras, malinaw na lungsod at neighbourhood, mga label ng iskedyul, canonical na TownSpot links, at pampublikong “Spotted by” credit kapag pinapayagan ng pahintulot.
• Mga limitasyon sa paghahanap: hanggang 20 resulta at pinakamaraming 31 araw bawat request.
• Para lamang sa discovery ang pampublikong connector na ito. Ang hiwalay na TownSpot APIs ang humahawak sa guarded public submissions at authenticated edits; nagdaragdag ang CLI ng operator ingestion checks.
• Suporta: https://www.townspot.co/contact-us

Pinakasimpleng connection request:

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

Submission at operator APIs

Hiwalay sa pampublikong marketplace connector ang mga halimbawang ito. Anonymous ngunit guarded at rate-limited ang event-source submission; kailangan ng angkop na TownSpot credentials para sa review at edit operations.

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}