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

Inici ràpid per a agents

La majoria d'agents necessiten tres tasques: trobar esdeveniments, enviar un esdeveniment des d'una URL font i després revisar o actualitzar l'esdeveniment creat.

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}