# SpecStream API

> The SpecStream API gives agents and programs data from the live web: a web search, the text of pages, and complete lists as structured rows with a source link on every value.

This is the address programs call. The website, with the full documentation, is https://specstream.ai.

## Products

- Search API: `GET https://api.specstream.ai/v1/web-search?q=<the question>`. $5 per 1,000 searches of up to 10 results, and $1 per 1,000 on the fast tier (`speed=fast`).
- Extract API: `POST https://api.specstream.ai/v1/extract` with `{"urls": ["<url>"]}`. $0.80 per 1,000 pages. A page with no text is not charged.
- Deep Search: ask in plain words and get every match on the live web as structured rows, priced per row. Each request is priced before any work runs.

## Installation

No install is needed to call the API: any HTTP client works. Clients, when you want one:

```bash
pip install specstream-client      # Python
npm install @specstream/sdk        # TypeScript and JavaScript
pip install specstream-mcp-stdio   # MCP server over stdio, for clients without remote MCP
```

In Python, import `specstream_client`. The package named `specstream` on PyPI is a different project and does not call this API. The SpecStream domain is specstream.ai; specstream.com is a different site.

## Configuration

- Base address: `https://api.specstream.ai`
- Key: send `Authorization: Bearer <key>` on every call. Keep the key in the `SPECSTREAM_API_KEY` environment variable, never in code.
- The account owner makes keys under Agents & API in the workspace at https://specstream.ai/workspace. A key that searches or reads pages needs the `finds:spend` scope and a spending limit above 0.
- MCP endpoint: `https://api.specstream.ai/mcp` (Streamable HTTP), with the same key or OAuth.
- A2A agent: `https://api.specstream.ai/a2a`, with its card at `https://api.specstream.ai/.well-known/agent-card.json`.

## Usage

Search the web:

```bash
curl -G "https://api.specstream.ai/v1/web-search" \
  -H "Authorization: Bearer $SPECSTREAM_API_KEY" \
  --data-urlencode "q=What is the population of Japan?"
```

Read pages:

```bash
curl -X POST "https://api.specstream.ai/v1/extract" \
  -H "Authorization: Bearer $SPECSTREAM_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"urls": ["https://example.com"], "format": "markdown"}'
```

In Python:

```python
import os
from specstream_client import Client

client = Client(os.environ["SPECSTREAM_API_KEY"])
search = client.web_search(q="What is the population of Japan?")
for source in search["sources"]:
    print(source["title"], source["url"], source["snippet"])
```

## Drop-in for the API you already call

SpecStream answers calls written for other search APIs at its own address, in each API's own reply shape. To switch, change the base address and the key. A search through a drop-in address is a fast search: $1 per 1,000 searches of up to 10 results.

| API you call | SpecStream address | Where the SpecStream key goes |
| --- | --- | --- |
| Tavily | `https://api.specstream.ai/tavily` | Bearer token or `api_key` |
| Exa | `https://api.specstream.ai/exa` | `x-api-key` or Bearer token |
| Brave Search API | `https://api.specstream.ai` | `X-Subscription-Token` |
| Serper | `https://api.specstream.ai/serper` | `X-API-KEY` |
| Firecrawl v2 | `https://api.specstream.ai/firecrawl` | Bearer token |

`GET https://api.specstream.ai/v1/search-dialects` lists every drop-in API with its base address, where the key goes and one curl line. It needs no key.

## Rules

- Reading or pricing a request never spends anything. Only an authorization or a payment does.
- Nothing in Deep Search runs until the person approves the quote's maximum.
- Write `q` in everyday words, in any language.
- Every value in a row carries the link of the page it was read from. Keep the link beside the value.

## Reference

- [OpenAPI description](https://api.specstream.ai/openapi.json)
- [Agent instructions](https://api.specstream.ai/AGENTS.md)
- [llms.txt](https://api.specstream.ai/llms.txt)
- [Glossary](https://api.specstream.ai/glossary.md)
- [Search API docs](https://specstream.ai/docs/search-api)
- [Extract API docs](https://specstream.ai/docs/extract-api)
- [REST API docs](https://specstream.ai/docs/api)
- [MCP docs](https://specstream.ai/docs/mcp)
- [How to get a key or an OAuth token](https://api.specstream.ai/auth.md)
- [API catalog](https://api.specstream.ai/.well-known/api-catalog)

## Pricing

- [Prices of the API](https://api.specstream.ai/pricing.md): every call with its price, in US dollars
- [Plans on the website](https://specstream.ai/pricing)
- A new account starts with $10 of credit, no card: [sign up](https://specstream.ai/signup)

## Company

- [About SpecStream](https://specstream.ai/about)
- [Security](https://specstream.ai/security)
- [Privacy](https://specstream.ai/privacy)
- [Terms](https://specstream.ai/terms)
- Contact: support@specstream.ai

## Glossary

- **Search**: one call to `GET /v1/web-search`. It returns up to 10 results from the live web, each with a title, a URL and a snippet.
- **Fast tier**: a search with `speed=fast`. It answers sooner and costs $1 per 1,000 searches.
- **Extract**: one call to `POST /v1/extract`. It returns the main text of up to 20 pages or files.
- **Drop-in address**: an address on this host that answers in another search API's request and reply shape.
- **Deep Search**: a request in plain words that returns every match as rows.
- **Row**: one match, with the facts asked for. Every value has a source link.
- **Source link**: the URL of the page a value was read from.
- **Quote**: the maximum price of a request, shown before any work runs.
- **Key**: a SpecStream API key, sent as a Bearer token. It has scopes and a spending limit.
- **Scope**: what a key may do, for example `finds:spend`.
- **MCP**: the Model Context Protocol. The endpoint is `/mcp`.
- **A2A**: the Agent2Agent protocol. The endpoint is `/a2a`.