API i descobriment per a agents de TownSpot

Documents de descobriment

Aquestes URLs well-known ajuden agents i clients d'integració a descobrir els serveis de TownSpot sense suposicions codificades manualment.

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

MCP públic per a assistents d'IA

Connecta ChatGPT, Claude o un altre client MCP a TownSpot, la guia d'esdeveniments locals creada per la gent. Pregunta què hi ha a tota una ciutat o en un barri. No cal cap compte i no pot crear ni editar esdeveniments.

• https://api.townspot.co/api/mcp/events
• Transport: Streamable HTTP remot.
• Autenticació: cap.
• Eines disponibles: resoldre una ciutat o població, llistar poblacions, obtenir una població, cercar esdeveniments publicats per ciutat o població, obtenir un esdeveniment i obtenir un espai.
• Els resultats de cerca i detall d'esdeveniments inclouen horaris locals, ciutat i barri explícits, etiquetes de programació, enllaços canònics de TownSpot i crèdit públic «Vist per» quan el consentiment ho permet.
• Límits de cerca: fins a 20 resultats i un interval màxim de 31 dies per sol·licitud.
• Aquest connector públic és només per a descobriment. Les API separades de TownSpot gestionen enviaments públics protegits i edicions autenticades; la CLI afegeix comprovacions d'ingestió per a operadors.
• Assistència: https://www.townspot.co/contact-us

Sol·licitud mínima de connexió:

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 d'enviament i d'operador

Aquests exemples són independents del connector públic del marketplace. L'enviament d'una font d'esdeveniment és anònim però protegit i limitat; la revisió i l'edició requereixen les credencials de TownSpot adequades.

1. Troba esdeveniments mitjançant la llista pública d'esdeveniments o una pàgina canònica de town.
2. Envia una URL font d'esdeveniment mitjançant l'eina MCP i inclou una idempotency key per a reintents segurs.
3. Revisa o actualitza l'esdeveniment creat amb l'endpoint de revisió o eines MCP autenticades.

Endpoints públics

Aquests endpoints exposen la superfície principal de descobriment i escriptura d'esdeveniments per a towns, esdeveniments, venues, fluxos MCP de scrape-to-submit i 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}

Exemples de request i response

Trobar esdeveniments públics per a un town.

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

Enviar un esdeveniment des d'una URL font mitjançant 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"
    }
  }
}

Revisar un esdeveniment amb una petició autenticada.

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

Autenticació

Les APIs protegides d'administració i gestió de venues de TownSpot fan servir bearer tokens emesos per Supabase Auth.

Fes servir els documents de metadades d'OpenID Connect i OAuth per descobrir programàticament els detalls d'autorització, token, JWKS i recurs protegit. Les eines públiques d'enviament també poden fer servir edit tokens d'esdeveniments, enllaços per correu del remitent o venue-manage tokens quan aquest flux ja existeix. Les eines MCP d'escriptura també poden incloure idempotency keys i tornar action receipts perquè els reintents siguin nets.

Patrons d'URL canònica

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