# Search the Web

AI-powered web search for your agents

## Navigation

**Getting Started:** [All You Need](/index.md) | [Getting Started](/introduction.md) | [How Sapiom Works](/how-it-works.md) | [Quick Start](/quick-start.md) | [Using Services](/using-services.md) | [For AI Tools](/for-agents.md)  
**Capabilities:** [Overview](/capabilities.md) | [Verify Users](/capabilities/verify.md) | **Search the Web** | [AI Model Access](/capabilities/ai-models.md) | [Generate Images](/capabilities/images.md) | [Audio Services](/capabilities/audio.md) | [Browser Automation](/capabilities/browser.md)  
**Integration / Agent Frameworks:** [Overview](/integration/agent-frameworks.md) | [LangChain](/integration/agent-frameworks/langchain.md) | [LangChain Classic](/integration/agent-frameworks/langchain-classic.md)  
**Integration / HTTP Clients:** [Overview](/integration/http-clients.md) | [Axios](/integration/http-clients/axios.md) | [Fetch](/integration/http-clients/fetch.md) | [Node.js HTTP](/integration/http-clients/node-http.md)  
**Governance:** [Overview](/governance.md) | [Setting Up Rules](/governance/rules.md) | [Agents & Identity](/governance/agents.md) | [Activity](/governance/activity.md)  
**Reference / API Reference:** [Introduction](/api-reference/introduction.md)  
**Reference / API Reference / Endpoints:** [Agents Endpoints](/api-reference/endpoints/agents.md) | [Get agent by ID](/api-reference/endpoints/agents/v1-agents-by-id-get.md) | [Update agent](/api-reference/endpoints/agents/v1-agents-by-id-patch.md) | [List all agents](/api-reference/endpoints/agents/v1-agents-get.md) | [Create a new agent](/api-reference/endpoints/agents/v1-agents-post.md) | [API Endpoints](/api-reference/endpoints.md) | [Get Sapiom payment JWKS](/api-reference/endpoints/other/.well-known-sapiom-jwks.json-get.md) | [Analytics Endpoints](/api-reference/endpoints/other.md) | [Get analytics chart](/api-reference/endpoints/other/v1-analytics-chart-get.md) | [Get analytics leaderboards](/api-reference/endpoints/other/v1-analytics-leaderboards-get.md) | [Get analytics summary](/api-reference/endpoints/other/v1-analytics-summary-get.md) | [Rules Endpoints](/api-reference/endpoints/rules.md) | [Get rule by ID](/api-reference/endpoints/rules/v1-spending-rules-by-id-get.md) | [Update a rule](/api-reference/endpoints/rules/v1-spending-rules-by-ruleId-put.md) | [List all rules](/api-reference/endpoints/rules/v1-spending-rules-get.md) | [Create a new rule](/api-reference/endpoints/rules/v1-spending-rules-post.md) | [Transactions Endpoints](/api-reference/endpoints/transactions.md) | [Complete a transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-complete-post.md) | [List transaction costs](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-get.md) | [Add cost to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-costs-post.md) | [Add facts to transaction](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-facts-post.md) | [Get transaction details](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-get.md) | [Reauthorize a transaction with x402 payment data](/api-reference/endpoints/transactions/v1-transactions-by-transactionId-reauthorize-post.md) | [List transactions](/api-reference/endpoints/transactions/v1-transactions-get.md) | [Create a new transaction](/api-reference/endpoints/transactions/v1-transactions-post.md) | [Verification Endpoints](/api-reference/endpoints/verification.md) | [Check verification code](/api-reference/endpoints/verification/v1-services-verify-check-post.md) | [Send verification code](/api-reference/endpoints/verification/v1-services-verify-send-post.md)  
**Reference / SDK Reference:** [@sapiom/axios](/reference/sdk/axios.md) | [@sapiom/fetch](/reference/sdk/fetch.md) | [SDK Reference](/reference/sdk.md) | [@sapiom/langchain-classic](/reference/sdk/langchain-classic.md) | [@sapiom/langchain](/reference/sdk/langchain.md) | [@sapiom/node-http](/reference/sdk/node-http.md)  
**Reference:** [Concepts](/reference/concepts.md)

---

Give your agents real-time information from the web — raw search results, AI-generated answers with citations, or structured data extraction.

## Quick Example

```typescript

const sapiomFetch = createFetch({
  apiKey: process.env.SAPIOM_API_KEY,
  agentName: "my-agent",
});

// Search with AI-generated answer
const response = await sapiomFetch(
  "https://linkup.services.sapiom.ai/v1/search",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      q: "What are the latest developments in quantum computing?",
      depth: "standard",
      outputType: "sourcedAnswer",
    }),
  }
);

const data = await response.json();
console.log(data.answer);
console.log("Sources:", data.sources);
```

## How It Works

Sapiom provides access to two web search providers: **Linkup** and **You.com**. Both support AI-powered search with different strengths:

- **Linkup** excels at structured data extraction and sourced answers
- **You.com** excels at live crawling and freshness filters

Choose the provider that fits your use case. Both use the same SDK pattern — just point to the different endpoint.

## Providers

| Provider | Best For | Pricing |
|----------|----------|---------|
| [Linkup](#linkup) | Structured extraction, sourced answers | $0.006 - $0.055/search |
| [You.com](#youcom) | Live crawling, freshness filters | $0.006 - $0.01/search |

---

## Linkup

Linkup provides three output modes:

- **Search Results** — Raw search results with titles, URLs, and snippets
- **Sourced Answer** — AI-generated answer with source citations
- **Structured** — Extract data into a custom JSON schema

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/v1/search` | Web search |
| POST | `/v1/search/price` | Get price estimate (free) |
| POST | `/v1/fetch` | Fetch URL as markdown |
| POST | `/v1/fetch/price` | Get fetch price estimate (free) |

**Base URL:** `https://linkup.services.sapiom.ai`

### Search

**Search Results:**
```typescript
    const { data } = await client.post(
      "https://linkup.services.sapiom.ai/v1/search",
      {
        q: "TypeScript best practices 2024",
        depth: "standard",
        outputType: "searchResults",
      }
    );

    for (const result of data.results) {
      console.log(`${result.title} - ${result.url}`);
    }
    ```
  
**Sourced Answer:**
```typescript
    const { data } = await client.post(
      "https://linkup.services.sapiom.ai/v1/search",
      {
        q: "What are the benefits of TypeScript?",
        depth: "standard",
        outputType: "sourcedAnswer",
      }
    );

    console.log(data.answer);
    console.log("Sources:", data.sources);
    ```
  
**Structured:**
```typescript
    const { data } = await client.post(
      "https://linkup.services.sapiom.ai/v1/search",
      {
        q: "Top 5 programming languages in 2024",
        depth: "deep",
        outputType: "structured",
        structuredOutputSchema: {
          type: "object",
          properties: {
            languages: {
              type: "array",
              items: {
                type: "object",
                properties: {
                  name: { type: "string" },
                  rank: { type: "number" },
                  useCase: { type: "string" },
                },
              },
            },
          },
        },
        includeSources: true,
      }
    );

    console.log(data.languages);
    ```
  
### Fetch URL

Fetch and convert a web page to clean markdown:

```typescript
const { data } = await client.post(
  "https://linkup.services.sapiom.ai/v1/fetch",
  {
    url: "https://example.com/article",
    renderJs: false,
  }
);

console.log(data.markdown);
```

### Linkup Fetch Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `url` | string | Yes | URL to fetch |
| `renderJs` | boolean | No | Render JavaScript before extraction (default: `false`) |
| `includeRawHtml` | boolean | No | Include raw HTML in response (default: `false`) |
| `extractImages` | boolean | No | Extract image URLs from the page (default: `false`) |

### Linkup Search Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `q` | string | Yes | Search query |
| `depth` | string | Yes | `standard` or `deep` |
| `outputType` | string | No | `searchResults`, `sourcedAnswer`, or `structured` |
| `maxResults` | number | No | Maximum results (1-100) |
| `includeImages` | boolean | No | Include images in results |
| `includeDomains` | string[] | No | Only include these domains |
| `excludeDomains` | string[] | No | Exclude these domains |
| `fromDate` | date | No | Results from this date |
| `toDate` | date | No | Results until this date |
| `includeInlineCitations` | boolean | No | Include inline citations (only for `sourcedAnswer`) |
| `structuredOutputSchema` | object | Required for `structured` | JSON schema for output |
| `includeSources` | boolean | No | Include sources with structured output |

### Linkup Pricing

| Depth | Price |
|-------|-------|
| standard | $0.006 |
| deep | $0.055 |

| Fetch Operation | Price |
|-----------------|-------|
| Standard fetch | $0.001 |
| With JS rendering | $0.006 |

---

## You.com

You.com provides fast web search with optional live crawling to fetch full page content from search results.

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| GET | `/v1/search` | Web search |
| POST | `/v1/search/price` | Get price estimate (free) |
| POST | `/v1/contents` | Fetch URL contents |
| POST | `/v1/contents/price` | Get contents price estimate (free) |

**Base URL:** `https://you-com.services.sapiom.ai`

### Search

**Basic Search:**
```typescript
    const { data } = await client.get(
      "https://you-com.services.sapiom.ai/v1/search",
      {
        params: {
          query: "Best practices for building AI agents",
          count: 10,
        },
      }
    );

    for (const result of data.results.web) {
      console.log(`${result.title} - ${result.url}`);
    }
    ```
  
**With Live Crawling:**
```typescript
    const { data } = await client.get(
      "https://you-com.services.sapiom.ai/v1/search",
      {
        params: {
          query: "TypeScript best practices 2024",
          count: 5,
          livecrawl: "web",
          livecrawl_formats: "markdown",
        },
      }
    );

    for (const result of data.results.web) {
      console.log(`Title: ${result.title}`);
      console.log(`Content: ${result.content}`); // Full page markdown
    }
    ```
  
### Fetch Contents

Fetch content from specific URLs:

```typescript
const { data } = await client.post(
  "https://you-com.services.sapiom.ai/v1/contents",
  {
    urls: [
      "https://example.com/article1",
      "https://example.com/article2",
    ],
    formats: ["markdown"],
  }
);

for (const content of data.contents) {
  console.log(content.markdown);
}
```

### You.com Parameters

**Search:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | string | Yes | Search query |
| `count` | number | No | Results count (1-100, default: 10) |
| `freshness` | string | No | `day`, `week`, `month`, or `year` |
| `country` | string | No | ISO 3166-2 country code |
| `language` | string | No | BCP 47 language code |
| `offset` | number | No | Result offset for pagination (0-9) |
| `safesearch` | string | No | `off`, `moderate`, or `strict` |
| `livecrawl` | string | No | `web`, `news`, or `all` |
| `livecrawl_formats` | string | No | `html` or `markdown` |

**Contents:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `urls` | string[] | Yes | URLs to fetch (1-10) |
| `formats` | string[] | No | `html`, `markdown`, or `metadata` (default: `["markdown"]`) |
| `crawl_timeout` | number | No | Timeout in seconds per URL, 1-60 (default: 10) |

### You.com Pricing

| Result Count | Price |
|--------------|-------|
| 1-50 (Standard) | $0.006 |
| 51-100 (Extended) | $0.008 |

| Contents | Price |
|----------|-------|
| Per request (1-10 URLs) | $0.01 |

---

## Error Codes

| Code | Description |
|------|-------------|
| 400 | Invalid request parameters |
| 402 | Payment required — ensure you're using the Sapiom SDK |
| 429 | Rate limit exceeded |