TownSpot API and Agent Discovery

TownSpot publishes machine-readable discovery documents for public discovery, authenticated event-write workflows, scrape-to-submit MCP tools, and action receipts.

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

Agent quickstart

Most agents need three jobs: find events, submit an event from a source URL, then review or update the created event.

Find events through the public event list or a canonical town page.
Submit an event source URL through the MCP tool and include an idempotency key for safe retries.
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}