---
name: typesearch
description: "Search recent news from outlets worldwide, read what an article says, find how other outlets covered a story, search a live site or your own URLs, and turn a question or your own data into a chart card — every result with a calibrated relevance score and a link to cite. Use it when a user asks what happened, the latest on a company, person, market, country or topic, coverage from a country or in a language, to check a claim against recent reporting, or for a chart of what the news reports."
---

# typesearch

typesearch is a search API for AI agents, built on its own continuously refreshed news index: outlets in
130+ countries and 30+ languages, every article judged by a calibrated relevance model. Send a
topic, get back ranked articles, each with a relevance score, a link to cite, and — when you ask — typed
answers, tone, grouped duplicates and short verbatim excerpts. Never the full text of an article.

- Base URL: `https://api.typesearch.ai`
- Every request and response field, with types and defaults: [/openapi.json](https://typesearch.ai/openapi.json) — it is
  generated from the same models the API validates, so it is the authority when this guide is shorter.
- All the docs as one file: [/llms-full.txt](https://typesearch.ai/llms-full.txt) · Index: [/llms.txt](https://typesearch.ai/llms.txt)

---

## Get a key

1. Create an account at https://app.typesearch.ai (email code, Google or GitHub). New accounts get $5 of free credit,
   valid for 30 days. Keys live at https://app.typesearch.ai/api-keys.
2. Send the key on every request, in either header:

```http
Authorization: Bearer ts_live_…
x-api-key: ts_live_…
```

Pay as you go, per request, from prepaid credit: no seats, no minimums. Keep the key on the server.

---

## What typesearch covers

| Source | What you get |
| --- | --- |
| **News index** | Recent articles from outlets in 130+ countries and 30+ languages, filterable by date, country, language, domain and section. |
| **Any live site** | A site read right now, even one outside the index (`/v1/search/site`). |
| **Your own URLs** | A custom index of your URLs, sitemaps or feeds, re-read daily and searched with the same judge (`/v1/indexes`). |
| **Charts** | A chart card from a question in plain words — figures, standings, polls, coverage, tone, timelines — or from your own data (`/v1/charts`). |

---

## Choose the right endpoint

| I want to… | Endpoint | Cost |
| --- | --- | --- |
| Find news on a topic, or up to 5 topics at once | `POST /v1/search` | $1.00–$5.60 per 1,000, by mode |
| Get typed answers, tone or grouped duplicates on every result | `POST /v1/search` with `questions`, `tone`, `dedupe` | same as the search |
| Know what an article says, or the passage about something | `POST /v1/contents` | $0.20 / 1,000 pages ($0.40 with `query`) |
| See how other outlets covered a story | `POST /v1/similar` | $2.20 / 1,000 requests |
| Search a site right now, even one outside the index | `POST /v1/search/site` | $2.40 / 1,000 requests |
| Search my own URLs, sitemaps or feeds | `/v1/indexes`, then `POST /v1/search` with `index` | $2.00 / 1,000 URLs per month, searches at the mode’s price |
| Turn a question into a chart | `POST /v1/charts` with `query` | its search + $0.50 per 1,000 (from $1.50 in ultra, $1.90 in fast) |
| Chart my own numbers | `POST /v1/charts` with `data` | $0.30 / 1,000 charts |
| Check my usage and limits | `GET /v1/usage` | free |
| Get a webhook when a topic moves | Monitors — **coming soon, not available yet** | — |

**Decision guide:**

- **“What happened with X today?”** — `search`, `mode: "fast"`, `days: 1`. Escalate to `normal` only if you need the passage.
- **“Is this claim true?”** — `search` in `normal` with a `questions` boolean, then `contents` with `query` for the quote.
- **“What does this link say?”** — `contents` with the URL and a `query`.
- **“Who else reported this?”** — `similar` with the article URL.
- **“What is this site publishing about Y?”** — `search/site`.
- **“Chart the coverage / the figures / the standings”** — `charts` with `query`: it works out what to show and says how close it got.

---

## Search modes

Pick the cheapest that answers. Each query in a multi-query request is one search of its mode.

| Mode | Per 1,000 | What it does | When |
| --- | --- | --- | --- |
| `ultra` | $1.00 | Judges headlines only. The cheapest, about a second. | Many searches where the headline says it all: alerts, classification, coverage counts. |
| `fast` (start here) | $1.40 | Judges headlines and standfirsts. About a second. | The default choice: current events, quick checks, loops over many topics. |
| `normal` | $2.20 | Also opens and reads the best matches (the top 4). A few seconds. | When a wrong result is expensive, or you need the passage and not just the headline. |
| `deep` | $5.60 | More headlines, the topic also in other words, reads 8 and returns highlights. 10–15 seconds. | Research, reports, “find everything”, or when fast came back thin. |

---

## Available endpoints

| Method | Path | Price (USD) | Type | Description |
| --- | --- | --- | --- | --- |
| `POST` | `/v1/search` | $1.00–$5.60 / 1,000 by mode, per query | sync or SSE | Search the news index (or your custom index) for one topic, or up to 5 judged together |
| `POST` | `/v1/contents` | $0.20 / 1,000 pages; $0.40 with a query | sync | Metadata and short verbatim excerpts for up to 10 URLs |
| `POST` | `/v1/similar` | $2.20 / 1,000; $4.60 in deep | sync | Other articles about the same story as a URL |
| `POST` | `/v1/search/site` | $2.40 / 1,000 requests | sync, 202 job or SSE | Search a live site right now, even one outside the index |
| `GET` | `/v1/jobs/{id}` | free | sync | Poll a live site search that answered 202 |
| `POST` | `/v1/charts` | from a query: its search + $0.50 / 1,000; from your data: $0.30 / 1,000 | sync or SSE | A chart card from a question in plain words, or from your own data |
| `GET` | `/v1/charts` | free | sync | List your charts |
| `GET` | `/v1/charts/{id}` | free | sync | Get a chart (poll it while `improving`) |
| `PATCH` | `/v1/charts/{id}` | free | sync | Change a chart’s type, theme, title or language |
| `DELETE` | `/v1/charts/{id}` | free | sync | Delete a chart |
| `GET` | `/embed/{file}` | free, no key | public | A chart’s embeddable page, PNG or SVG |
| `POST` | `/v1/indexes` | free (its URLs are billed) | sync | Create a custom index |
| `GET` | `/v1/indexes` | free | sync | List your custom indexes |
| `GET` | `/v1/indexes/{id}` | free | sync | Get a custom index |
| `DELETE` | `/v1/indexes/{id}` | free | sync | Delete a custom index and its URLs |
| `POST` | `/v1/indexes/{id}/urls` | $2.00 / 1,000 URLs per month, billed daily | 202, indexed in the background | Add URLs, a sitemap or a feed |
| `GET` | `/v1/indexes/{id}/urls` | free | sync | List the URLs of a custom index |
| `DELETE` | `/v1/indexes/{id}/urls` | free | sync | Remove URLs or sources |
| `GET` | `/v1/usage` | free | sync | This key’s usage and limits |

**Free:** cached repeats (the same search within its cache window, `cached_at` set), failed requests, a
chart repeated within 10 minutes (`cached: true`), `422 insufficient_data`, `plan_only`, every embed view,
and every `GET`, `PATCH` and `DELETE`. Every response carries `usage.cost_usd` with what it cost.

---

## Search results

`POST /v1/search` answers with `results`, and each result carries:

| Field | What it contains |
| --- | --- |
| `url`, `title`, `source`, `published_at` | The article and outlet — cite the `url` of every fact you use |
| `score` | Calibrated probability that the article is about the query. 0.9 is clearly on topic; **0.35–0.65 is undecided** — treat those as leads, not facts |
| `snippet` | The standfirst, as the outlet published it |
| `highlights` | Very short verbatim excerpts from the articles that were read (normal and deep) |
| `answers` | Your `questions`, answered per result: a probability, a choice or a score |
| `tone` | Positive, neutral or negative toward the query, with probabilities (`tone: true`) |
| `duplicates` | The same story from other outlets (`dedupe: true`) |
| `country`, `language`, `section` | Where it comes from |

The response also has `near_misses` (the closest articles when nothing matched — never present them as
answers), `warnings` (for example a filter with nothing indexed), `incomplete` (the time or token budget ran
out) and `usage`.

---

## Requests

```bash
curl -X POST https://api.typesearch.ai/v1/search \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "Chile lithium royalties",
    "mode": "fast",
    "days": 7,
    "countries": ["CL"],
    "max_results": 10,
    "dedupe": true
  }'
```

- `query`: a topic, not a sentence (“Chile lithium royalties”), in the language the coverage is likely in. Up
  to 5 queries in an array, judged together.
- `days` (default 7, `null` for the whole index) or `published_after` / `published_before` (`YYYY-MM-DD`).
- `countries` (ISO 3166-1 alpha-2) and `languages` (ISO 639-1) are the outlet’s, not the story’s.
- `include_domains`, `exclude_domains`, `sections`, `max_results` (up to 50), `stream: true` for SSE.

**Typed answers, tone and several queries at once:**

```bash
curl -X POST https://api.typesearch.ai/v1/search \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": ["Acme recall", "Acme lawsuit"],
    "mode": "normal",
    "days": 3,
    "tone": true,
    "questions": {
      "confirmed": {
        "type": "boolean",
        "instructions": "Does the article report a confirmed fact, not a rumor?"
      },
      "impact": {
        "type": "score",
        "instructions": "How serious is it for Acme?",
        "criteria": ["None", "Low", "Moderate", "High", "Very high"]
      }
    }
  }'
```

Up to 8 questions per request: `boolean`, `choice` (options in `criteria`) or `score` (the scale in `criteria`).

### `POST /v1/contents`

```bash
curl -X POST https://api.typesearch.ai/v1/contents \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "urls": ["https://wire.example/business/acme-recall"],
    "query": "how many units are recalled"
  }'
```

Up to 10 URLs. Each comes back with title, standfirst, date, source and a short verbatim excerpt (up to 25
words); with `query`, the excerpt about it and how much the article covers it. A URL that fails has its own
`error` and is not billed.

### `POST /v1/similar`

```bash
curl -X POST https://api.typesearch.ai/v1/similar \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://wire.example/business/acme-recall",
    "days": 7,
    "max_results": 20
  }'
```

### `POST /v1/search/site`

```bash
curl -X POST https://api.typesearch.ai/v1/search/site \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "site": "diarioejemplo.example",
    "query": "central bank rates",
    "mode": "normal"
  }'
```

It may answer `202` with a job: poll `GET /v1/jobs/{id}` every couple of seconds until `status` is
`succeeded` or `failed`. Jobs last one day and are visible only to the key that created them.

### Custom index

```bash
curl -X POST https://api.typesearch.ai/v1/indexes \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Competitor blogs"
  }'
```

```bash
curl -X POST https://api.typesearch.ai/v1/indexes/idx_3k9q2m7x/urls \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "sitemap": "https://blog.acme.example/sitemap.xml"
  }'
```

```bash
curl -X POST https://api.typesearch.ai/v1/search \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "price increases",
    "index": "idx_3k9q2m7x",
    "mode": "fast"
  }'
```

Up to 100 URLs (3 indexes) pay as you go, 10,000 (50 indexes) with the monthly plan. Every URL is
re-read daily; sitemaps and feeds are checked hourly.

### `POST /v1/charts`

From a question in plain words:

```bash
curl -X POST https://api.typesearch.ai/v1/charts \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "which outlets cover lithium",
    "theme": "editorial"
  }'
```

It answers `201` with the chart: `type` (12 types, picked for you unless you set one), `chart` (series, key
figures, annotations and the source of every value), `interpretation` (what it understood you want to see,
with other readings), `rung` (how close it got: `exact`, `partial`, `related`, `coverage` or `stories`),
`improving` (a stored chart that keeps looking and updates itself), and `embed_url`, `image_url` and
`svg_url` — public, free to view, no key. Show the `image_url` in chat, or embed the `embed_url` in an iframe.
`plan_only: true` returns the plan without building it; `stream: true` sends `step`, `result` and
`improved` events.

From your own data:

```bash
curl -X POST https://api.typesearch.ai/v1/charts \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Signups per week",
    "data": {
      "series": [
        {
          "name": "Signups",
          "points": [
            {
              "x": "2026-09-01",
              "y": 120
            },
            {
              "x": "2026-09-08",
              "y": 164
            },
            {
              "x": "2026-09-15",
              "y": 201
            }
          ]
        }
      ],
      "x": {
        "kind": "time",
        "granularity": "week"
      }
    }
  }'
```

Change it later (free):

```bash
curl -X PATCH https://api.typesearch.ai/v1/charts/chart_3v7n1q8m2k5x9w4p \
  -H "Authorization: Bearer $TYPESEARCH_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "bar",
    "theme": "dark"
  }'
```

---

## Errors

Errors are RFC 9457 problem documents (`application/problem+json`) with a stable `code`, a human
`detail` and a `request_id`. Use `code` in your logic.

| Status | `code` | What to do |
| --- | --- | --- |
| 400 | `invalid_json`, `invalid_request` | Fix the body: `errors` names each invalid field. Unknown fields are rejected. |
| 400 | `invalid_url`, `invalid_site`, `site_not_found`, `unsupported` | Fix the URL or site. |
| 401 | `missing_api_key`, `invalid_api_key`, `revoked_api_key` | Send a valid key. Tell the user where to get one: https://app.typesearch.ai/api-keys |
| 402 | `insufficient_credits` | The account has no credit. Tell the user; do not retry. |
| 402 | `spend_limit_reached` | The key reached its monthly spend limit. Tell the user; do not retry. |
| 403 | `robots_disallowed`, `source_unavailable` | That site or source can’t be read. Try another. |
| 404 | `job_not_found` | The job expired (one day) or belongs to another key. |
| 422 | `insufficient_data` | No articles about the chart’s topic at all. Not billed; rephrase or widen it. |
| 429 | `rate_limited` | Wait `Retry-After` seconds, then retry. |
| 429 | `quota_exceeded` | Daily quota used; it resets at 00:00 UTC. Do not retry. |
| 5xx | `internal_error`, `timeout`, `upstream_unavailable`, … | Retry with backoff (twice), honouring `Retry-After`. |

Warnings that don’t stop a request come back in `warnings`, each with a `code` and a `message`.

---

## Rate limits

Every key has a limit per minute and a token quota per day, both depending on the plan (`GET /v1/usage` says
which). Every response carries `X-RateLimit-Limit`, `X-RateLimit-Remaining` and `X-Request-Id`; a `429`
carries `Retry-After`. Retry connection errors, timeouts, `429 rate_limited` and `5xx` twice with
exponential backoff and jitter; never retry `quota_exceeded`, `insufficient_credits` or `spend_limit_reached`.

---

## Other ways in

**MCP server** — https://api.typesearch.ai/mcp (Streamable HTTP; the key as `Authorization: Bearer` or `x-api-key`). Tools:
`search_news`, `get_contents`, `find_similar`, `create_chart`. Claude Code:

```bash
claude mcp add --transport http typesearch https://api.typesearch.ai/mcp --header "Authorization: Bearer $TYPESEARCH_API_KEY"
```

More clients: https://typesearch.ai/mcp

**Drop-in for Exa, Tako and Perplexity** — keep the official SDK and change the base URL and the key:
`https://api.typesearch.ai/compat/exa`, `https://api.typesearch.ai/compat/tako`, `https://api.typesearch.ai/compat/perplexity`. See https://typesearch.ai/docs/migration/exa.

**Integrations** — https://typesearch.ai/integrations · **Open-source apps built on it** — https://typesearch.ai/open-source

---

## Answering with typesearch

- Lead with what happened, then the evidence: outlet, date and link for each fact.
- Quote only excerpts the API returned, verbatim and short. Never reconstruct article text.
- Prefer several outlets for contested claims; `similar` finds them.
- Say when coverage is thin, and when you escalated to a more expensive mode.
- Compute exact dates from today before filtering (“last week” → `published_after` / `published_before`).

Docs: https://typesearch.ai/docs · Pricing: https://typesearch.ai/pricing · Support: support@typesearch.ai