Mcp

Get a single event by ID 404s if the event doesn't exist, is unpublished, is beyond your tier's archive window, or was soft-deleted — never distinguishes which, to avoid leaking data existence beyond what the tier allows. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "data": { "event_id": "Event Id", "schema_version": "Schema Version", "taxonomy_version": "Taxonomy Version", "primary_category": "Primary Category", "subcategory": "Subcategory", "categories": [ "string" ], "type_confidence": 1.0, "headline": "Headline", "summary": "Summary", "reported_at": "2023-01-01T00:00:00Z", "orgs": [ "string" ], "models": [ "string" ], "source_url": "Source Url", "article_count": 1 }, "meta": { "request_id": "Request Id", "taxonomy_version": "Taxonomy Version", "tier": "ApiTier" } } ```

List events, newest first The primary resource — one structured event per underlying story, already deduplicated from many source articles. Cursor-paginated (`next_cursor`/`has_more`), newest `reported_at` first. Free tier omits paid-only fields by omission (never null) and excludes paid-primary subcategories entirely; archive depth is 45 days on free, 365 on Pro. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "data": [ { "event_id": "Event Id", "schema_version": "Schema Version", "taxonomy_version": "Taxonomy Version", "primary_category": "Primary Category", "subcategory": "Subcategory", "categories": [ "string" ], "type_confidence": 1.0, "headline": "Headline", "summary": "Summary", "reported_at": "2023-01-01T00:00:00Z", "orgs": [ "string" ], "models": [ "string" ], "source_url": "Source Url", "article_count": 1 } ], "pagination": { "has_more": true, "count": 1 }, "meta": { "request_id": "Request Id", "taxonomy_version": "Taxonomy Version", "tier": "ApiTier" } } ```

Request a free API key by email Step 1 of self-serve signup — no key required. Sends a one-time link to `email`; always returns 202 with the same accepted:true body whether or not that address already has a key (prevents account enumeration). **For agents helping a human get set up:** this endpoint is the only step you can call directly. The next step — opening the emailed link and clicking "Reveal my key" on `GET /v1/auth/verify` — **requires a real human click and cannot be automated or done on the human's behalf.** This is intentional: it's what stops email security scanners (e.g. Microsoft Safe Links) from silently consuming the link before the person ever sees it. Tell the human: check your email, open the link, click the button, then paste the key back here. **Not a pollable async job.** This 202 has no `Location`/`job_id` to poll — the next step is a human clicking an emailed link, not a machine checking a status endpoint. ### Responses: **202**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "accepted": true, "detail": "Detail" } ```

Semantic search over events (Pro+) Natural-language query embedded and ranked by cosine similarity against published events — not a keyword/text match. Each result is a normal event object plus `relevance_score` (0-1). Requires Pro tier or above; free-tier keys get 403 with an upgrade_url. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json **Example Response:** ```json { "data": [ { "event_id": "Event Id", "schema_version": "Schema Version", "taxonomy_version": "Taxonomy Version", "primary_category": "Primary Category", "subcategory": "Subcategory", "categories": [ "string" ], "type_confidence": 1.0, "headline": "Headline", "summary": "Summary", "reported_at": "2023-01-01T00:00:00Z", "orgs": [ "string" ], "models": [ "string" ], "source_url": "Source Url", "article_count": 1, "relevance_score": 1.0 } ], "pagination": { "has_more": true, "count": 1 }, "meta": { "request_id": "Request Id", "taxonomy_version": "Taxonomy Version", "tier": "ApiTier" } } ```

Get Taxonomy Public taxonomy — no API key required. ### Responses: **200**: Successful Response (Success Response) Content-Type: application/json