# SpecStream API: instructions for agents

> 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.

## 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)
- [Full text](https://api.specstream.ai/llms-full.txt)
- [Agent instructions for the whole product](https://specstream.ai/agents.md)