# Search the Web

AI-powered web search for your agents

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

## Quick Example

**Axios:**
```typescript
    import { withSapiom } from "@sapiom/axios";
    import axios from "axios";

    const client = withSapiom(axios.create(), {
      apiKey: process.env.SAPIOM_API_KEY,
    });

    // Search with AI-generated answer
    const { data } = await client.post(
      "https://linkup.services.sapiom.ai/v1/search",
      {
        query: "What are the latest developments in quantum computing?",
        depth: "standard",
        outputType: "sourcedAnswer",
      }
    );

    console.log(data.answer);
    console.log("Sources:", data.sources);
    ```
  
**Fetch:**
```typescript
    import { createFetch } from "@sapiom/fetch";

    const fetch = createFetch({
      apiKey: process.env.SAPIOM_API_KEY,
    });

    // Search with AI-generated answer
    const response = await fetch(
      "https://linkup.services.sapiom.ai/v1/search",
      {
        method: "POST",
        headers: { "Content-Type": "application/json" },
        body: JSON.stringify({
          query: "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.01 - $0.08/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",
      {
        query: "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",
      {
        query: "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",
      {
        query: "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 Parameters

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `query` | 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 |
| `structuredOutputSchema` | object | Required for `structured` | JSON schema for output |
| `includeSources` | boolean | No | Include sources with structured output |

### Linkup Pricing

| Output Type | Price |
|-------------|-------|
| searchResults | $0.01 |
| sourcedAnswer | $0.08 |
| structured | $0.08 |

| Fetch Operation | Price |
|-----------------|-------|
| Standard fetch | $0.01 |
| With JS rendering | $0.02 |

---

## You.com

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

### Endpoints

| Method | Path | Description |
|--------|------|-------------|
| POST | `/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.post(
      "https://you-com.services.sapiom.ai/v1/search",
      {
        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.post(
      "https://you-com.services.sapiom.ai/v1/search",
      {
        query: "TypeScript best practices 2024",
        count: 5,
        livecrawl: "web",
        livecrawlFormat: "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",
    ],
    format: "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` |
| `livecrawlFormat` | string | No | `html` or `markdown` |

**Contents:**

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `urls` | string[] | Yes | URLs to fetch (1-10) |
| `format` | string | No | `html` or `markdown` (default: markdown) |

### You.com Pricing

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

| Contents | Price |
|----------|-------|
| Per URL | $0.01 |

---

## Error Codes

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

> **Using Python?:** See [Service Proxy](/md/service-proxy.md) for REST API access without the Node.js SDK.