> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ateve.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Search API

> Search the web with filters, content options, and structured results.

## Introduction

The Search API returns ranked web results with source URLs, snippets, and optional page content. Use the results as context in your application, and retain the source URLs for citations.

## Endpoint

```http theme={null}
POST https://api.ateve.ai/v1/search
```

## Request parameters

### Headers

| Header          | Required | Description                                                                         |
| --------------- | -------- | ----------------------------------------------------------------------------------- |
| `Authorization` | Yes      | `Bearer YOUR_ATEVE_API_KEY`. Create a key in the [Dashboard](https://ateve.ai/keys) |
| `Content-Type`  | Yes      | `application/json`                                                                  |

### Body

Only `query` is required.

| Parameter         | Type      | Description                                                                                                                        |
| ----------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `query`           | string    | Search query, 1–2,000 characters after trimming                                                                                    |
| `max_results`     | integer   | Maximum ranked results to return, up to 100                                                                                        |
| `date_range`      | string    | Filter by `day`, `week`, `month`, `year`, `YYYY-MM-DD`, `YYYY-MM-DD..YYYY-MM-DD`, `YYYY-MM-DD..`, or `..YYYY-MM-DD`. Dates use UTC |
| `include_domains` | string\[] | Only search these domains, up to 300. Use host names such as `openai.com` and `claude.ai`                                          |
| `exclude_domains` | string\[] | Exclude these domains, up to 300. For example, `reddit.com` and `twitter.com`                                                      |
| `content`         | object    | Choose returned content fields and format. See below                                                                               |
| `safe_search`     | boolean   | Filter unsafe content. Default: `true`                                                                                             |

**Content options**

<div className="ateve-content-options">
  | Field                         | Type    | Default | Description                                                      |
  | ----------------------------- | ------- | ------- | ---------------------------------------------------------------- |
  | `content.snippet`             | boolean | `true`  | Include a short excerpt                                          |
  | `content.text`                | object  | —       | Return page content as `text` or `markdown` instead of `snippet` |
  | `content.text.format`         | string  | `text`  | `text` or `markdown`; determines the returned page content field |
  | `content.text.max_characters` | integer | `5000`  | Positive character limit per extracted page, after formatting    |
</div>

## Response parameters

### Response body

The API returns a JSON object with request metadata and a `results` array.

<div className="ateve-response-fields">
  | Field                     | Type      | Description                                        |
  | ------------------------- | --------- | -------------------------------------------------- |
  | `id`                      | string    | Search request identifier                          |
  | `created`                 | integer   | Creation time in Unix seconds                      |
  | `latency_ms`              | integer   | Server processing time in milliseconds             |
  | `query.original`          | string    | Submitted query                                    |
  | `results`                 | object\[] | Ranked results. An empty array is a valid response |
  | `total_estimated_matches` | integer   | Estimated total matches when available             |
</div>

**Result fields**

| Field          | Type      | Description                                                             |
| -------------- | --------- | ----------------------------------------------------------------------- |
| `id`           | string    | Result position within this response                                    |
| `title`        | string    | Page title                                                              |
| `url`          | string    | Source URL to use for citations                                         |
| `display_url`  | string    | Display-friendly URL                                                    |
| `published_at` | string    | UTC publication time; `null` if unknown                                 |
| `score`        | number    | Relevance score from 0 to 1; higher values indicate greater relevance   |
| `snippet`      | string    | Short excerpt; omitted when `text` or `markdown` is returned            |
| `text`         | string    | Page content when `content.text` is requested with `format: "text"`     |
| `markdown`     | string    | Page content when `content.text` is requested with `format: "markdown"` |
| `favicon`      | string    | Favicon URL, when available                                             |
| `images`       | object\[] | Images with `url`, `width`, `height`, and `alt`. Can be empty           |
| `is_safe`      | boolean   | Safety classification; may be `null`                                    |

## Examples

Set your API key before running the examples:

```bash theme={null}
export ATEVE_API_KEY="YOUR_ATEVE_API_KEY"
```

### Basic search

Search with a query and a maximum result count.

```bash theme={null}
curl -X POST https://api.ateve.ai/v1/search \
  -H "Authorization: Bearer $ATEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI news",
    "max_results": 5
  }'
```

### Recent results

Find results from the past week.

```bash theme={null}
curl -X POST https://api.ateve.ai/v1/search \
  -H "Authorization: Bearer $ATEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "web platform updates",
    "date_range": "week",
    "max_results": 5
  }'
```

### Custom date range

Search within a specific period. You can also use a single date or an open range such as `2026-08-01..` or `..2026-08-31`.

```bash theme={null}
curl -X POST https://api.ateve.ai/v1/search \
  -H "Authorization: Bearer $ATEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI research announcements",
    "date_range": "2026-08-01..2026-08-31",
    "max_results": 5
  }'
```

### Domain filters

Include results from selected domains and exclude results from unwanted domains.

```bash theme={null}
curl -X POST https://api.ateve.ai/v1/search \
  -H "Authorization: Bearer $ATEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "AI model updates",
    "include_domains": ["openai.com", "claude.ai"],
    "exclude_domains": ["reddit.com", "twitter.com"],
    "max_results": 5
  }'
```

### Page content

Retrieve page content in the `markdown` field, up to 3,000 characters per result. When `markdown` is returned, the `snippet` field is omitted. Set `format` to `"text"` to return page content in the `text` field instead.

```bash theme={null}
curl -X POST https://api.ateve.ai/v1/search \
  -H "Authorization: Bearer $ATEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "hybrid search versus vector search",
    "max_results": 5,
    "content": {
      "text": {
        "format": "markdown",
        "max_characters": 3000
      }
    }
  }'
```

### Safe search

Disable safe search when your application requires unfiltered results.

```bash theme={null}
curl -X POST https://api.ateve.ai/v1/search \
  -H "Authorization: Bearer $ATEVE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "art history",
    "safe_search": false,
    "max_results": 5
  }'
```

For Python and Node.js examples, see [SDKs](/get-started/sdks). To send a request in your browser, use **Try it** in the [API Reference](/api-reference/search).