TownSpot API and Agent Discovery

Discovery documents

These well-known URLs help agents and integration clients discover TownSpot services without 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

Public MCP for AI assistants

Connect ChatGPT, Claude, or another MCP client to TownSpot, the people-powered guide to local events. Ask what's on across a city or in a neighbourhood. It needs no account and cannot create or edit events.

• https://api.townspot.co/api/mcp/events
• Transport: remote Streamable HTTP.
• Authentication: none.
• Available tools: resolve a city or Town, list Towns, get a Town, search published events by city or Town, get an event, and get a venue.
• Event search and event-detail results include local times, explicit city and neighbourhood, schedule labels, canonical TownSpot links, and public “Spotted by” credit when consent allows.
• Search limits: up to 20 results and a maximum 31-day date range per request.
• This public connector is discovery-only. TownSpot's separate submission and operator APIs handle guarded public submissions and authenticated edits; the CLI adds operator ingestion checks.
• Support: https://www.townspot.co/contact-us

Minimal 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 and operator APIs

These examples are separate from the public marketplace connector. Event-source submission is anonymous but guarded and rate-limited; review and edit operations require the appropriate TownSpot credentials.

1. Find events through the public event list or a canonical town page.
2. Submit an event source URL through the MCP tool and include an idempotency key for safe retries.
3. Review or update the created event with the review endpoint or authenticated MCP tools.

Public endpoints

These endpoints expose the main discovery and event-write surface for towns, events, venues, MCP scrape-to-submit flows, and 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}

Request and response examples

Find public events for a 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
    }
  ]
}

Submit an event from a source URL through 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"
    }
  }
}

Review an event with an 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"]
}

Authentication

Protected TownSpot admin and venue-manager APIs use bearer tokens issued by Supabase Auth.

Use the OpenID Connect and OAuth metadata documents to discover the authorization, token, JWKS, and protected-resource details programmatically. Public submission tools can also use event edit tokens, submitter email links, or venue-manage tokens where that flow already exists. MCP write tools can include idempotency keys and return action receipts so agents can retry cleanly.

Canonical URL patterns

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