API y descubrimiento para agentes de TownSpot

Documentos de descubrimiento

Estas URLs well-known ayudan a agentes y clientes de integración a descubrir los servicios de TownSpot sin suposiciones codificadas a mano.

• /.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úblico para asistentes de IA

Conecta ChatGPT, Claude u otro cliente MCP a TownSpot, la guía de eventos locales creada por la gente. Pregunta qué hay en toda una ciudad o en un barrio. No requiere una cuenta y no puede crear ni editar eventos.

• https://api.townspot.co/api/mcp/events
• Transporte: Streamable HTTP remoto.
• Autenticación: ninguna.
• Herramientas disponibles: resolver una ciudad o localidad, listar localidades, obtener una localidad, buscar eventos publicados por ciudad o localidad, obtener un evento y obtener un espacio.
• Los resultados de búsqueda y detalle de eventos incluyen horarios locales, ciudad y barrio explícitos, etiquetas de programación, enlaces canónicos de TownSpot y crédito público «Visto por» cuando el consentimiento lo permite.
• Límites de búsqueda: hasta 20 resultados y un intervalo máximo de 31 días por solicitud.
• Este conector público es solo para descubrimiento. Las API separadas de TownSpot gestionan envíos públicos protegidos y ediciones autenticadas; la CLI añade controles de ingesta para operadores.
• Soporte: https://www.townspot.co/contact-us

Solicitud mínima de conexión:

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 de envío y de operador

Estos ejemplos son independientes del conector público del marketplace. El envío de una fuente de evento es anónimo pero protegido y limitado; la revisión y la edición requieren las credenciales de TownSpot adecuadas.

1. Encuentra eventos mediante la lista pública de eventos o una página canónica de town.
2. Envía una URL fuente de evento mediante la herramienta MCP e incluye una idempotency key para reintentos seguros.
3. Revisa o actualiza el evento creado con el endpoint de revisión o herramientas MCP autenticadas.

Endpoints públicos

Estos endpoints exponen la principal superficie de descubrimiento y escritura de eventos para towns, eventos, venues, flujos MCP de scrape-to-submit y 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}

Ejemplos de request y response

Encontrar eventos públicos para 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 evento desde una URL fuente mediante 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 evento con una petición 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ón

Las APIs protegidas de administración y gestión de venues de TownSpot usan bearer tokens emitidos por Supabase Auth.

Usa los documentos de metadatos de OpenID Connect y OAuth para descubrir de forma programática los detalles de autorización, token, JWKS y recurso protegido. Las herramientas públicas de envío también pueden usar edit tokens de eventos, enlaces por email del remitente o venue-manage tokens cuando ese flujo ya existe. Las herramientas MCP de escritura también pueden incluir idempotency keys y devolver action receipts para que los reintentos sean limpios.

Patrones de URL canónica

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