Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown
Browse docs

Get Started

OverviewWhy ExpandQuickstartWays to Use Expand

Agent Quickstarts

OverviewExpand SkillClaude CodeCursorCodexOpenCodeSkill-Based AgentsOther MCP Clients

Fetch

OverviewHow Fetch WorksOutput ModelInclude OptionsBrowser BehaviorHighlightsPlayground & ReplayBatched Fetch

Reference

API ReferenceCLI CommandsMCP Tools & ResourcesTypeScript SDKPython SDK

Account & Billing

Pricing & UsageTiersFAQ

Machine-Readable Docs

start.mdllms.txtllms-full.txtDocs as Markdown

Quickstart

Run your first Fetch in seconds — from the CLI, a coding agent, the SDK, or the API.

Run Fetch in seconds.

Fetch a live page yourself, or give Expand to your coding agent. The human path starts with one command. The agent path starts with your harness integration.

Human quickstart

Run one command in your terminal. Prints agent-ready Markdown for a live page, usually in seconds.

Run once · Install globally · Use the SDK · Call the API

Agent quickstart

Give Fetch to Claude Code, Codex, Cursor, or OpenCode, then verify with one prompt.

Agent Quickstarts · Expand Skill · Verify setup

The primary human command:

npx expandai fetch
https://news.ycombinator.com

This prints agent-ready Markdown for a live page. No project, no config.

The short expandai CLI package is pending publish. Until it is live, run npx @expandai/cli fetch https://news.ycombinator.com. The npx expandai ... form above is the target command.

The primary agent prompt:

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

If your agent does not have Expand yet, point it at setup first:

Read /start.md or the Expand Agent Quickstart for your harness, install the recommended integration, then run the verification Fetch.

Human path

Run once with npx

npx expandai fetch https://news.ycombinator.com
  • No global install required.
  • Prints Markdown by default.
  • Best for trying Fetch once.

Install globally

Once expandai is published under the short name:

npm install -g expandai
expandai fetch https://news.ycombinator.com

If the package is still scoped at install time, use the scoped name with the same binary:

npm install -g @expandai/cli
expandai fetch https://news.ycombinator.com

Authenticate when needed

Log in once and the CLI reuses your local session:

expandai login
expandai whoami

For CI, servers, and non-interactive runs, set an API key instead. The CLI, SDKs, and direct API all read EXPAND_API_KEY:

export EXPAND_API_KEY="xpnd_..."

Keep API keys server-side. Raw keys are shown only once after creation.

Expected output

Markdown mode prints the readable page body. A Hacker News fetch starts like this:

# Hacker News

1. Example story title
2. Another story title
...

When you want metadata and structured signal alongside the Markdown, request JSON mode:

expandai fetch https://news.ycombinator.com --format json

Object-mode JSON carries:

  • markdown — Main Markdown for the page;
  • State JSON — included in the response when it is useful and fits, addressable by reference when it is too large;
  • meta.snapshotId — the reusable snapshot handle for replay and follow-up Highlights;
  • metadata and evidence/source handles where returned.

Markdown mode does not print a snapshotId. Use --format json or an SDK fetchJson call when you need the snapshot handle.

API and SDK paths

These are secondary to the CLI for a first run, but they are the path into application code.

Direct API

curl -X POST 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 returns Markdown.
  • POST /v1/fetch/json returns object-mode JSON with Main Markdown, State JSON, and metadata.
  • Authored cURL examples use the x-expand-api-key header. See API Reference and Output Model for exact schemas.

TypeScript SDK

Install @expandai/sdk. The client reads EXPAND_API_KEY from the environment.

import { ExpandClient } from "@expandai/sdk"

const client = new ExpandClient()

const markdown = await client.fetch({ url: "https://news.ycombinator.com" })
console.log(markdown)

Use client.fetchJson({ url }) when you need Main Markdown, State JSON, and meta.snapshotId together. See the TypeScript SDK reference.

Python SDK

Install expandai and set EXPAND_API_KEY. The client opens as a context manager.

from expandai import Expand, FetchParams, FetchJsonParams

with Expand() as expand:
    markdown = expand.fetch(FetchParams(url="https://news.ycombinator.com"))
    print(markdown)

Use expand.fetch_json(FetchJsonParams(url=...)) for Main Markdown plus State JSON and meta.snapshot_id. See the Python SDK reference.

Agent path

The fastest way to give an agent web context is its native setup, not a paste. Pick your harness, install once, then verify.

AgentFirst path
Claude CodeHook — also installs MCP
CodexSkill + MCP
CursorSkill + MCP
OpenCode

Hooks are available for Claude Code and OpenCode. Skill and MCP setup accept claude-code, cursor, opencode, and codex. Pi, Hermes, and OpenClaw are skill-based — set them up from Skill-Based Agents.

After setup, confirm the integration with one prompt:

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

Troubleshooting

  • npx expandai not found: the short package is pending publish — use npx @expandai/cli fetch ... or install globally.
  • CLI not authenticated: run expandai login, then expandai whoami to confirm.
  • API key missing: set EXPAND_API_KEY, or send the x-expand-api-key header on direct API calls.
  • Empty or blocked output: try another URL, then see Browser Behavior.
  • Need a structured response: use --format json on the CLI or POST /v1/fetch/json.
  • Need links, State JSON, or evidence: see Output Model, Include Options, and How Fetch Works.

Next steps

  • Ways to Use Expand: choose agent, CLI, SDK, API, or Playground.
  • Agent Quickstarts: configure your harness.
  • CLI Commands: learn every CLI command.
  • TypeScript SDK and Python SDK: integrate in application code.
  • How Fetch Works: learn Main Markdown, State JSON, Appendix, Highlights, and evidence.
  • API Reference: the exact endpoint contract.
PreviousWhy Expand
NextWays to Use Expand

On This Page

Run Fetch in seconds.Human pathRun once with npxInstall globallyAuthenticate when neededExpected outputAPI and SDK pathsDirect APITypeScript SDKPython SDKAgent pathTroubleshootingNext steps
Hook — also installs MCP