Search API

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

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
`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

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

Response parameters

Response body

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

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

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:

export ATEVE_API_KEY="YOUR_ATEVE_API_KEY"

Basic search

Search with a query and a maximum result count.

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.

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.

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.

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.

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.

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. To send a request in your browser, use Try it in the API Reference.

Get Started

Search

Benchmarks

Resources

Introduction

Endpoint

Request parameters

Headers

Body

Response parameters

Response body

Examples

Basic search

Recent results

Custom date range

Domain filters

Page content

Safe search

​Introduction

​Endpoint

​Request parameters

​Headers

​Body

​Response parameters

​Response body

​Examples

​Basic search

​Recent results

​Custom date range

​Domain filters

​Page content

​Safe search

Introduction

Endpoint

Request parameters

Headers

Body

Response parameters

Response body

Examples

Basic search

Recent results

Custom date range

Domain filters

Page content

Safe search