Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get started

IntroductionWhy ExpandQuickstartAuthenticationConnect your agent (MCP)

Products

OverviewFetching a URLBatched Fetch
API reference

SDKs & tools

TypeScript SDK
MCP tools & resourcesDocs for agents

Reference

API referenceErrors & retriesPricing & UsageLimitsConcurrency tiersFAQ
Browse docs

Get started

IntroductionWhy ExpandQuickstartAuthenticationConnect your agent (MCP)

Products

OverviewFetching a URLBatched Fetch
API reference

SDKs & tools

TypeScript SDK
MCP tools & resourcesDocs for agents

Reference

API referenceErrors & retriesPricing & UsageLimitsConcurrency tiersFAQ

Quickstart

Run your first Fetch from the CLI or a coding agent in one step, then pick the surface you will build on.

A Fetch takes a URL and returns the rendered page. In Markdown Mode you get Markdown text. In JSON Mode you get a JSON object with the Main Markdown, State JSON, page metadata, and the Snapshot ID together. This page runs one Fetch, then shows the same call from a coding agent, the CLI, the TypeScript SDK, and the API.

Run Fetch in seconds

Run one command in your terminal, or paste the prompt into your coding agent.

npx expandai fetch https://news.ycombinator.com
Read https://expand.ai/start.md and set up Expand. Fetch it as raw text with curl. A summarizing web-fetch tool drops the exact commands.
Note
You can try a Fetch from the CLI before you sign in. The CLI uses an anonymous preview session, which is rate limited. Run expandai login for normal use. Your first organization starts with 10,000 free credits, and a Fetch costs 1 credit (1,000 credits are $1). See Pricing & Usage.

Ways to use Expand

You can call Fetch from a coding agent, the CLI, the TypeScript SDK, the API, or the Playground. They all call the same API, so a browser page Fetch returns the same Main Markdown, State JSON, citation links, and Snapshot whichever way you call it. Pick the one that matches where you are.

  • Inside a coding agent, set the agent up once so it fetches pages through Expand on its own.
  • Testing by hand, run one CLI command.
  • Building a product, call the TypeScript SDK or the API and hand the result to your own users.
  • Checking what a Fetch saw, open the Playground.
Recommended for agents

Agents

Coding agents, harnesses, and MCP clients that should use Fetch automatically.

Add https://api.expand.ai/v1/mcp to your agent.
Connect your agent

CLI

Terminal fetches, scripts, local checks, and repeatable workflows.

expandai fetch URL
CLI commands

TypeScript SDK

Integrating Fetch into TypeScript applications.

@expandai/sdk
TypeScript SDK
Use it fromBest forSetupAuthCanonical docs
AgentsCoding agents and MCP clientsHosted MCP server, one URLBrowser sign-in or API key/docs/mcp-server
CLITerminal fetches and scriptsnpm install --global expandaiCLI login or EXPAND_API_KEY/docs/cli-commands
TypeScript SDKTypeScript appsPackage installEXPAND_API_KEY/docs/typescript-sdk
APICustom backends and other languages

MCP is one way to connect an agent, not a separate product. Hooks, the Skill, and MCP work together. A hook routes the agent's own web-fetch tool through Expand, the Skill teaches the agent when to reach for Expand, and MCP gives the agent Fetch as tools it can call. Setup picks the right mix for each agent, so you do not have to assemble it yourself.

To hand an agent Expand's docs instead of the live site, use the routes on Docs for agents.

Agents

Paste the setup prompt from Run Fetch in seconds into your coding agent. The agent reads the guide, asks which agents on your machine to configure, and runs expandai init for the ones you pick. Each one gets the Expand Skill and the MCP server, and OpenCode also gets a web-fetch hook. Claude Code, Codex, Cursor, OpenCode, and fx are supported today. What each piece does, and the per-agent commands, are on CLI: Skill & hooks.

To add only the hosted MCP server, with nothing installed, see Connect your agent (MCP).

Note
Agents read hook and MCP configuration when they start, so setup takes effect in a new session.

After setup, confirm it with one prompt:

Use Expand to fetch https://news.ycombinator.com. Show me the first 10 lines of Markdown and confirm the Fetch succeeded.

CLI

Install

Run it once with npx expandai, or install it globally:

npm install -g expandai

Sign in

Sign in once and the CLI keeps the session on your machine:

expandai login

The browser opens so you can sign in or create an account. For CI, servers, and scripts, set EXPAND_API_KEY instead. Where to create a key, and how each surface sends it, is on Authentication.

Fetch a page

expandai fetch https://news.ycombinator.com

Markdown Mode is the default. The CLI prints the page as Markdown text.

To get the JSON object instead, with the Main Markdown, State JSON, page metadata, and meta.snapshotId together, pass --format json:

expandai fetch https://news.ycombinator.com --format json
Note
Use JSON Mode when you need the Snapshot ID, for replay or for Snapshot Highlights.

Every field in the response is on Fetching a URL.

TypeScript SDK and API

The TypeScript SDK and the API are the path into application code. Install the SDK with npm install @expandai/sdk. The API needs nothing installed. Both read your API key from EXPAND_API_KEY:

export EXPAND_API_KEY="xpnd_..."

Create the key in the dashboard after signing in. How each surface sends it is on Authentication. Then run the first Fetch:

import { ExpandClient } from '@expandai/sdk'

const expand = new ExpandClient()

const markdown = await expand.fetch({ url: 'https://news.ycombinator.com' })
console.log(markdown)
curl https://api.expand.ai/v1/fetch \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"url":"https://news.ycombinator.com"}'

POST /v1/fetch, and expand.fetch() in the SDK, is Markdown Mode and returns Markdown text. POST /v1/fetch/json, and expand.fetchJson(), is JSON Mode and returns a JSON object with the Main Markdown, State JSON, page metadata, and meta.snapshotId. The exact schemas are in the API reference, and the full client is on TypeScript SDK.

Troubleshooting

  • The CLI says you are not signed in. Run expandai login, then expandai whoami to confirm.
  • A request is refused for a missing key. Set EXPAND_API_KEY, or send the x-expand-api-key header on direct API calls.
  • EXPAND_API_KEY is set but the CLI uses another account. A stored sign-in takes precedence over the environment variable. Run expandai logout to use the key.
  • The page comes back empty or blocked. Try another URL, then see Browser-rendered pages.
  • You need the Snapshot ID. Use --format json on the CLI, or POST /v1/fetch/json.
  • You got an error code. Errors & retries says what it means and whether to retry.

Next steps

  • Connect your agent (MCP): add the hosted MCP server by hand.
  • CLI: Commands: every CLI command and flag.
  • TypeScript SDK: the full client.
  • Fetch: How Fetch works: Main Markdown, State JSON, Appendix, and the Snapshot.
PreviousWhy Expand
NextAuthentication

On This Page

Run Fetch in secondsWays to use ExpandAgentsCLIInstallSign inFetch a pageTypeScript SDK and APITroubleshootingNext steps

API

Custom backends, other languages, and direct HTTP integrations.

POST /v1/fetch
API reference

Playground

Inspecting a Fetch, its evidence, and a replayed page.

Open a Snapshot in your browser.
Playground & Replay
HTTP client
x-expand-api-key
/api-reference
PlaygroundVisual inspection and ReplayDashboardSigned-in account/docs/wayback-machine/playground-and-replay