mcp

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" } ```

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "format": "email",
      "title": "email",
      "description": "Email to receive the magic link"
    }
  },
  "required": [
    "email"
  ],
  "title": "request_magic_linkArguments"
}

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" } } ```

{
  "type": "object",
  "properties": {
    "cursor": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Opaque cursor from a previous response's next_cursor",
      "title": "cursor",
      "type": "string"
    },
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "default": 50,
      "title": "limit"
    },
    "category": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Exact primary_category id, e.g. MODEL_RELEASE",
      "title": "category",
      "type": "string"
    },
    "subcategory": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "description": "Exact subcategory id, e.g. MODEL_RELEASE.NEW_MODEL_RELEASE",
      "title": "subcategory",
      "type": "string"
    },
    "since": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only events reported_at >= this ISO 8601 timestamp",
      "title": "since",
      "type": "string"
    },
    "until": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "description": "Only events reported_at <= this ISO 8601 timestamp",
      "title": "until",
      "type": "string"
    }
  },
  "title": "list_eventsArguments"
}

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" } } ```

{
  "type": "object",
  "properties": {
    "event_id": {
      "type": "string",
      "title": "event_id"
    }
  },
  "required": [
    "event_id"
  ],
  "title": "get_eventArguments"
}

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" } } ```

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "minLength": 1,
      "description": "Natural-language search query",
      "title": "q"
    },
    "limit": {
      "type": "integer",
      "maximum": 100,
      "minimum": 1,
      "default": 20,
      "title": "limit"
    }
  },
  "required": [
    "q"
  ],
  "title": "searchArguments"
}

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

{
  "type": "object",
  "properties": {},
  "title": "taxonomyArguments"
}