Developer API

Overview

SHOWUPAT exposes read-only JSON endpoints for crawlers, widgets, and custom integrations. No API key is required for public read endpoints.

Write operations (create Activity, check-in, etc.) require authenticated sessions and are not part of the public API.

GET /api/public/platform-stats

Returns aggregate platform statistics for the landing page and external dashboards.

• Response: activitiesHosted, participants, showUpRate, and related counters.
• Cache-friendly; suitable for hourly polling.

GET /api/public/activities

Lists future OPEN PUBLIC Activities through the existing discovery engine. Search, dates, facets, modes and opaque cursor pagination share the same projection and privacy rules as the public detail reader.

• q — search query (synonyms: basket/hoops, football/soccer by locale, padel, running, etc.)
• lat, lng, radiusKm — filter and sort by distance (default radius 15 km, max 200)
• limit — integer 1–100, default 20; cursor — opaque nextCursor with unchanged filters
• lang — locale hint for synonym expansion (en, fr, de, es, ja, pt, lb, zh, ar)
• mode — PHYSICAL, DIGITAL, or HYBRID
• facet / facets — filter by facet key:value (e.g. facet=sport:basketball or facets=sport:padel,level:beginner)
• digitalProvider, digitalCategory — filter digital Activities
• from, to — ISO-8601 scheduledAt window
• Response: { ok:true, data:{ count, activities[], nextCursor, page } }; page.partial reports the existing bounded geo candidate window. Capacity, conditions, updatedAt and observedAt are explicit.

OpenAPI specification

Machine-readable OpenAPI 3.1 document at GET /api/public/openapi.json describes all public read endpoints, query parameters, and response schemas.

GET /api/public/activity

Strictly PUBLIC detail by exactly one id or shareToken. Returns the canonical public facts and historical state. Circle, Solo, draft, deleted and unknown activities return 404. The older /api/public/activities/[shareToken] is a separate gated invitation/member adapter, not the crawler-facing detail endpoint.

GET /api/public/activities/[shareToken]/ics

Separate user-triggered iCalendar export. Private activities require existing membership/owner access (401/403 otherwise); unknown/deleted activities return 404. Public exports omit secret meeting destinations. The operation records existing download statistics and is excluded from crawler discovery and native MCP read tools.

GET /api/public/places/search

Search place labels and coordinates for widgets and activity creation flows. Nominatim-backed, read-only.

• q — place query (2–120 characters, required)
• limit — max results (default 6, max 10)
• Response: { ok:true, data:{ count, places[] } } with placeId, label, address, latitude, longitude; invalid queries return 400 and provider failures return 503.

GET /api/public/places/reverse

Resolve lat/lng to a human-readable place label.

• lat, lng — required coordinates
• Response: { ok:true, data:{ place } } or a genuine unmatched place:null; provider failure returns 503.

Organizer webhooks (live)

Authenticated organizers subscribe to HTTPS webhook deliveries for their Activities. Event types: registration.confirmed, attendance.showed_up, activity.cancelled.

Subscribe with POST /api/me/webhooks { url, events, secret? }. List with GET /api/me/webhooks. Delete with DELETE /api/me/webhooks/[id].

URLs must be public HTTPS endpoints. Private IPs, localhost, and metadata hosts are rejected; DNS is re-checked on every delivery to block rebinding.

Deliveries POST JSON with X-Showupat-Signature (HMAC-SHA256), X-Showupat-Event, and X-Showupat-Delivery-Id headers. Catalog: GET /api/public/webhooks/events.

GET /api/public/countries

List or search ISO countries with localized names and flag emoji.

• q — optional search by name or code
• lang — locale for labels (en, fr, de, es, ja, pt, lb, zh, ar)
• limit — 1–300 (default 300 without q, 20 with q)
• Response: { count, countries[] } with code, name, flag

MCP manifest

POST /api/public/mcp is a native read-only Streamable HTTP MCP endpoint using the official SDK. GET /api/public/mcp.json describes its five tools, protocol versions and public documentation resources. Human guide: /docs/mcp.

GET /api/discover

Authenticated discover with facet filters, digital provider filters, and eligibility when logged in.

For anonymous integrations prefer GET /api/public/activities.

Interactive explorer

Try endpoints live at /docs/developers#openapi-explorer. OpenAPI source: GET /api/public/openapi.json.

Example requests

• curl 'https://showupat.com/api/public/platform-stats'
• curl 'https://showupat.com/api/public/activities?q=basketball&limit=10'
• curl 'https://showupat.com/api/public/activities?lat=48.8566&lng=2.3522&radiusKm=10'
• curl 'https://showupat.com/api/public/activities?facet=sport:basketball&mode=PHYSICAL'
• curl 'https://showupat.com/api/public/places/search?q=Paris'
• curl 'https://showupat.com/api/public/places/reverse?lat=48.8566&lng=2.3522'
• curl 'https://showupat.com/api/public/countries?q=fr'
• curl 'https://showupat.com/api/public/webhooks/events'
• curl 'https://showupat.com/api/public/mcp.json'
• curl 'https://showupat.com/api/public/openapi.json'

CORS and rate limits

Public read endpoints allow browser CORS for legitimate widgets. Use reasonable polling; aggressive scraping may be throttled.

See /llms.txt and /ai for machine-readable documentation index.