Expand AI logo
DocsDocs
Glow Active
API Reference
Login

Documentation

Get started

IntroductionWhy ExpandQuickstartAuthenticationConnect your agent (MCP)

Products

OverviewFetching a URLBatched Fetch
API reference
OverviewTwo ways to highlightWorking with snippetsAPI 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
OverviewTwo ways to highlightWorking with snippetsAPI reference

SDKs & tools

TypeScript SDK
MCP tools & resourcesDocs for agents

Reference

API referenceErrors & retriesPricing & UsageLimitsConcurrency tiersFAQ

Two ways to highlight

Highlights can be used on new Fetch requests, as well as on existing Snapshots. We call them Fetch Highlights and Snapshot Highlights, respectively.

Highlights runs in two places. Fetch Highlights runs as part of a Fetch, and Snapshot Highlights runs later, on a page you fetched before.

Fetch Highlights

Add a query to a Fetch to get matching snippets from the whole page.

Note
Fetch Highlights reads the layers your Fetch includes: the Main Markdown and State JSON by default. The Appendix is highlighted only if you include it. To choose the layers, see Fetching a URL: Include options.

The MCP fetch tool always includes Main Markdown when searching a new page. It can turn State JSON off or the Appendix on, but it has no includeMarkdown argument. The MCP get_snapshot tool can choose all three layers when searching an existing Snapshot.

import { ExpandClient } from '@expandai/sdk'

const expand = new ExpandClient()

const page = await expand.fetchJson({
  url: 'https://docs.stripe.com/webhooks',
  highlights: { query: 'signature verification', maxResults: 5 },
})
expandai fetch https://docs.stripe.com/webhooks --highlights "signature verification" --max-results 5





{
  "meta": {
    "url": "https://docs.stripe.com/webhooks",
    "snapshotId": "019...",
    "playground": "https://expand.land/s/019...",
    "markdown": { "url":
Note
In the JSON object, snippets come back under data.highlights, and the usual layers are left out: the full Markdown, State JSON, Appendix, and screenshot. meta.markdown.url links to the full Markdown if you need it. In Markdown text, the response is the snippets themselves.

Snapshot Highlights

Add highlights to a Snapshot read to highlight an existing Snapshot with a new question, using the meta.snapshotId from a prior Fetch response. It doesn't create a new Fetch, so it costs only the 1 Highlights credit.

A Fetch response carries two IDs, and Snapshot Highlights takes meta.snapshotId, the capture's own ID. Snapshot Highlights always answers with a JSON object, and Batched Fetch doesn't support it.

The include options select the layers to highlight:

  • include.markdown highlights the Main Markdown.
  • include.json highlights the State JSON.
  • include.appendix highlights the Appendix when Appendix text exists.
  • When include isn't provided, Highlights uses the Main Markdown and State JSON. The Appendix is opt-in.
Opt-in
import { ExpandClient } from '@expandai/sdk'

const expand = new ExpandClient()

const result = await expand.snapshots.get({
  snapshotId: '<snapshotId>',
  highlights: { query: 'retry policy', maxResults: 5 },
})
# The CLI always highlights Markdown and State JSON. Use the SDK or cURL to change that.
expandai snapshots get <snapshotId> --highlights "retry policy" --max-results 5
// Arguments for the get_snapshot tool
{
  "snapshotId": "<snapshotId>",
  "highlights": { "query": "retry policy", "maxResults": 5 }
}
curl "https://api.expand.ai/v1/snapshots/<snapshotId>/highlights" \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "highlights": { "query": "retry policy", "maxResults": 5 }
  }'
{
  "snapshotId": "019...",
  "response": { "url": "https://docs.stripe.com/webhooks", "originStatusCode": 200 },
  "highlights": {
    "query": "retry policy",
    "snippets": [
      {
        "source": "markdown",
        "text": "Stripe retries failed deliveries for up to three days, with an exponential backoff.",
        "score": 0.9,
        "location": { "evidenceId": 640 }
      },
      {
        "source": "statejson",
        "text": "webhooks.retries.window: 3 days",
        "json": { "window": "3 days", "backoff": "exponential" },
        "score": 0.84,
        "location": { "evidenceId": 9, "jsonPath": "$.webhooks.retries" }
      }
    ]
  },
  "durationMs": 107
}
Warning
A request with nothing to highlight is rejected with 400 BadRequest.

Tuning the results

When you highlight, you can control the minScore, the minimum relevance score, and the maxResults, the most snippets you can receive that score above the minScore. minScore defaults to 0.6 (or 0 in MCP) and can be set from 0 to 1. maxResults defaults to 5 and can be set from 1 to 50.

Note
Zero snippets is not an error. The layers were valid, but nothing scored above minScore. Lower minScore, or include more layers.
10
150
0.75
01

For Fetch Highlights

Set how many snippets come back, and how relevant they must be, in the same request that fetches the page.

import { ExpandClient } from '@expandai/sdk'

const expand = new ExpandClient()

const page = await expand.fetchJson({
  url: 'https://docs.stripe.com/webhooks',
  highlights: { query: 'signature verification', maxResults: 10, minScore: 0.75 },
})
expandai fetch https://docs.stripe.com/webhooks --highlights "signature verification" --max-results 10 --min-score 0.75
// Arguments for the fetch tool
{
  "url": "https://docs.stripe.com/webhooks",
  "highlights": { "query": "signature verification", "maxResults": 10, "minScore": 0.75 }
}
curl https://api.expand.ai/v1/fetch/json \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.stripe.com/webhooks",
    "highlights": { "query": "signature verification", "maxResults": 10, "minScore": 0.75 }
  }'

For Snapshot Highlights

Set the same limits when you highlight a Snapshot you already have, to get only the matching snippets you want from it.

import { ExpandClient } from '@expandai/sdk'

const expand = new ExpandClient()

const result = await expand.snapshots.get({
  snapshotId: '<snapshotId>',
  highlights: { query: 'retry policy', maxResults: 10, minScore: 0.75 },
})
expandai snapshots get <snapshotId> --highlights "retry policy" --max-results 10 --min-score 0.75
// Arguments for the get_snapshot tool
{
  "snapshotId": "<snapshotId>",
  "highlights": { "query": "retry policy", "maxResults": 10, "minScore": 0.75 }
}
curl "https://api.expand.ai/v1/snapshots/<snapshotId>/highlights" \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "highlights": { "query": "retry policy", "maxResults": 10, "minScore": 0.75 }
  }'

Highlights errors

On top of the standard Fetch errors, Highlights can return two more errors. Their full payloads are in the API reference.

_tagCodeRetryable
BadRequest400No
FetchSnapshotHighlightsNotFound404No

BadRequest

The Highlights request has nothing to highlight.

HTTP 400Not retryable
{
  "_tag": "BadRequest",
  "message": "Highlights requires at least one included corpus: markdown, json, or appendix."
}

Turn at least one layer back on. See Snapshot Highlights.

FetchSnapshotHighlightsNotFound

No Snapshot with that snapshotId exists for your organization.

HTTP 404Not retryable
{
  "_tag": "FetchSnapshotHighlightsNotFound",
  "snapshotId": "019..."
}
Recommendation
Check the snapshotId. It is meta.snapshotId from the Fetch, not the public meta.resources.snapshotId.

Next steps

  • Working with snippets: what a snippet contains, how to cite it, and how to read beyond it.
  • Fetching a URL: Include options: choose which layers a Fetch includes, and so which Fetch Highlights searches.
  • Errors & retries: what to do when a request fails.
PreviousHighlights: Overview
NextWorking with snippets

On This Page

Fetch HighlightsSnapshot HighlightsTuning the resultsFor Fetch HighlightsFor Snapshot HighlightsHighlights errorsBadRequestFetchSnapshotHighlightsNotFoundNext steps
// Arguments for the fetch tool
{
"url": "https://docs.stripe.com/webhooks",
"highlights": { "query": "signature verification", "maxResults": 5 }
}
curl https://api.expand.ai/v1/fetch/json \
  -H "x-expand-api-key: $EXPAND_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://docs.stripe.com/webhooks",
    "highlights": { "query": "signature verification", "maxResults": 5 }
  }'
"https://expand.land/s/019.../content"
}
},
"markdown": "",
"json": [],
"data": {
"highlights": {
"query": "signature verification",
"snippets": [
{
"source": "markdown",
"text": "Verify the event's signature with the endpoint's signing secret before you process it.",
"score": 0.93,
"location": { "evidenceId": 512 }
},
{
"source": "statejson",
"text": "webhooks.signing.header: Stripe-Signature",
"json": { "header": "Stripe-Signature", "tolerance": 300 },
"score": 0.87,
"location": { "evidenceId": 7, "jsonPath": "$.webhooks.signing" }
}
]
}
}
}
---
url: "https://docs.stripe.com/webhooks"
query: "signature verification"
more: "https://api.expand.ai/v1/public/snapshots/01JPUBLIC01?format=markdown"
---

# Highlights

## 1. Markdown

Verify the event's signature with the endpoint's signing secret before you process it.

## 2. State JSON: $.webhooks.signing

```json
{
  "header": "Stripe-Signature",
  "tolerance": 300
}
```