Skip to content
TellMeFirst Explore

Loading interactive API reference… The text guide is also available below.

Read the text guide

TellMeFirst Explore API

Read discoverable events through the public read-only API. No account, API key or payment is required. See the OpenAPI specification for the machine-readable contract.

AI assistants can also use the public read-only MCP server, which shares the same event data, filters and public field contract.

For an introduction to both options, see Use TellMeFirst with an AI assistant.

Versioning

The current endpoint is /api/v1/events and the API contract version is 1.0.0. The /v1 URL identifies the major contract. Future incompatible changes use a new major URL, such as /api/v2/events. The former unversioned /api/events route is unavailable and returns HTTP 404.

No v1 retirement is currently scheduled. If a version is deprecated, this guide and the OpenAPI description will announce the replacement and retirement date before removal. Deprecated endpoints will signal deprecation with the Deprecation header; when a removal date is set, a Sunset header will identify it. Current v1 responses do not advertise a deprecation or sunset.

The specification at /openapi.json describes this API. Its OpenAPI format version, 3.1.1, is separate from the API contract version.

Requests

Send GET /api/v1/events?sort=popular&page=1 or GET /api/v1/events?sort=recent&page=1 on this site's origin. The default sort is popular and the default page is 1. Each page contains up to 24 events.

Use status to select event states:

  • status=open: open events only (default).
  • status=completed: completed events only.
  • status=all: open and completed events together.

For example, GET /api/v1/events?status=completed&sort=recent&page=1 lists completed events, newest creation date first. The status filter applies to browsing, search and every pagination link.

When browsing without q, Popular ranks open events by confirmed active subscriptions and completed events by the saved subscription total at completion, highest first. It includes positive counts only; completed events with a zero or unknown saved total remain available through Recent. Recent includes zero-subscription and unknown-count events and orders by creation date, newest first. Ties use a stable event identifier. If no popular events exist, the API returns Recent within the selected status and reports recent in meta.sort.

Both views always exclude non-discoverable, deleted and suspended events, and events whose owners are blocked. Completed events require status=completed or status=all. Public profile inclusion does not make an event discoverable. The same title search is also available in Explore.

Title search

Add q to search event titles, for example GET /api/v1/events?q=iphone or GET /api/v1/events?q=iphone&status=all&page=1. Matching uses a literal substring, with surrounding whitespace trimmed. Percent, underscore and exclamation marks are literal characters rather than search wildcards. There is no fuzzy search or search within final-update text.

A nonempty q includes eligible matching titles within the selected status, even with zero subscriptions, and ranks them by subscription count regardless of the requested sort. meta.sort reports popular. Open events use their active confirmed count; completed events use their saved completion total, with unknown totals ranked as zero. The stable identifier breaks ties. Empty or whitespace-only q restores ordinary Popular/Recent browsing. q may contain up to 160 characters.

Response

The JSON response contains data, meta and links. Every event includes:

  • public_id, title and url: the stable public identifier, title and canonical event page URL.
  • status: open or completed.
  • waiting_count: confirmed active email plus Wallet subscriptions while open; null after completion. Each subscription counts separately, so a person using both channels can count twice. Unconfirmed and cancelled subscriptions do not count.
  • managed_by: the public display name in name (null if unavailable). The optional profile_url contains the canonical public profile URL only when the manager has a published public profile; otherwise that field is omitted. No private creator contact details are included.
  • created_at and completed_at: ISO 8601 creation and completion timestamps. completed_at is null while open. These are record timestamps, not scheduled occurrence dates.
  • initial_url: the safe HTTPS information link, or null.
  • completion_message and completion_url: the public final update and safe HTTPS final link. Both are null while open; an absent final link is null.
  • completed_subscription_count: the frozen subscription total recorded at completion. It is null while open or when an older completed event has no saved total. A known zero stays zero; an unknown total is never inferred from current subscriptions.

No subscriber identities, creator emails, internal account IDs or private profile drafts are returned.

meta contains sort, page, per_page, total, last_page, status and the normalized q. Follow links.next or links.prev on the same origin; each is a relative URL or null and preserves the status filter and search query. Results reflect current data on each request, so changes between requests can move events between pages.

Limits and errors

The limit is 60 requests per minute per IP address, shared across requests from that address. Responses expose X-RateLimit-Limit and X-RateLimit-Remaining so clients can track their remaining allowance. A rate-limited request returns HTTP 429 with Retry-After. Invalid sort, page, q or status parameters return HTTP 422; a page beyond the available results returns HTTP 404. An empty first page returns HTTP 200 with an empty data array. The former includeCompleted parameter is no longer supported and returns HTTP 422. Responses are JSON. Public cross-origin reading is supported without credentials.

This API does not create events, subscribe visitors, export subscribers or send announcements. These actions use the existing browser workflows and access rules.