> ## 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 > Search the web and return ranked results with source URLs, snippets, and optional extracted content. ## OpenAPI ````yaml openapi.json POST /v1/search openapi: 3.0.3 info: title: Ateve Search API version: 1.0.0 description: >- Ranked web results with source URLs, snippets, and optional extracted content. Only successful new Search executions count toward usage. servers: - url: https://api.ateve.ai description: Ateve public API security: - bearerAuth: [] tags: - name: Search description: Search the web. paths: /v1/search: post: tags: - Search summary: Search the web description: Return ranked web results. Only query is required. operationId: search requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/SearchRequest' examples: minimal: summary: Quick search value: query: hybrid search versus vector search max_results: 3 content: summary: Search with page text value: query: hybrid search versus vector search max_results: 5 content: text: format: markdown max_characters: 3000 responses: '200': description: Successful search. Example content and timing are illustrative. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/SearchResponse' example: id: req_example created: 1789459200 latency_ms: 412 query: original: hybrid search versus vector search results: - id: results.#0 title: A guide to hybrid search url: https://example.com/hybrid-search display_url: https://example.com/hybrid-search published_at: null score: 0.95 snippet: Hybrid search combines lexical and semantic retrieval. images: [] is_safe: true total_estimated_matches: 125 '400': description: Request validation failed. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: invalid_parameter message: Request validation failed. type: invalid_request_error '401': description: Missing or invalid API key. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: invalid_api_key message: Missing or invalid API key. type: authentication_error '402': description: Available Search allowance and prepaid balance are insufficient. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: insufficient_credit message: >- Available Search allowance and prepaid balance are insufficient. type: invalid_request_error '403': description: >- Team access suspended or payment review required. Legacy credit failures may also return 403. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: payment_required message: >- Team access suspended or payment review required. Legacy credit failures may also return 403. type: invalid_request_error '404': description: Unknown route. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: not_found message: Unknown route. type: invalid_request_error '405': description: Use POST. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: method_not_allowed message: Use POST. type: invalid_request_error '409': description: >- Request with the same idempotency key is processing, or invalid_parameter for a key conflict. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: idempotency_in_progress message: >- Request with the same idempotency key is processing, or invalid_parameter for a key conflict. type: invalid_request_error '415': description: Missing or unsupported Content-Type. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: invalid_parameter message: Missing or unsupported Content-Type. type: invalid_request_error '429': description: A team rate window was exceeded. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string Retry-After: description: Seconds until the exceeded window resets. schema: type: integer X-Ateve-Limit-Scope: description: Exceeded rate-limit window. schema: type: string enum: - qps - qpm - qpd content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: rate_limit_exceeded message: A team rate window was exceeded. type: rate_limit_error '500': description: Internal error. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: server_error message: Internal error. type: server_error '502': description: Upstream Search unavailable. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: service_unavailable message: Upstream Search unavailable. type: server_error '504': description: Upstream Search timed out. headers: X-Request-Id: description: >- HTTP request ID. On a replay, the body retains the original response ID. schema: type: string content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: id: req_example error: code: timeout message: Upstream Search timed out. type: server_error x-codeSamples: - lang: bash label: cURL source: |- curl -X POST https://api.ateve.ai/v1/search \ -H "Authorization: Bearer $ATEVE_API_KEY" \ -H "Content-Type: application/json" \ -d '{"query":"AI news"}' - lang: python label: Python source: |- import json import os from urllib.request import Request, urlopen request = Request( "https://api.ateve.ai/v1/search", data=json.dumps({"query": "AI news"}).encode(), headers={ "Authorization": f"Bearer {os.environ['ATEVE_API_KEY']}", "Content-Type": "application/json", }, method="POST", ) with urlopen(request) as response: print(json.load(response)) - lang: javascript label: JavaScript source: |- const response = await fetch("https://api.ateve.ai/v1/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.ATEVE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: "AI news" }), }); console.log(await response.json()); components: schemas: SearchRequest: type: object properties: query: type: string description: A nonblank search query. minLength: 1 maxLength: 2000 example: hybrid search versus vector search max_results: type: integer description: Maximum results to return. Fewer results may be available. minimum: 1 maximum: 100 content: $ref: '#/components/schemas/ContentOptions' date_range: type: string description: >- UTC freshness filter: day, week, month, year; YYYY-MM-DD; YYYY-MM-DD..YYYY-MM-DD; YYYY-MM-DD..; or ..YYYY-MM-DD. Use valid calendar dates with end on or after start. example: month include_domains: type: array description: Restrict results to these host names, without schemes or paths. maxItems: 300 items: type: string example: - openai.com - claude.ai exclude_domains: type: array description: Exclude these host names. maxItems: 300 items: type: string example: - reddit.com - twitter.com safe_search: type: boolean description: Filter explicit or unsafe content. default: true required: - query SearchResponse: type: object properties: id: type: string description: Original search request ID. Replays retain this ID. example: req_example created: type: integer description: Response creation time as UTC Unix epoch seconds. format: int64 latency_ms: type: integer description: Server-side search processing time in milliseconds. query: type: object properties: original: type: string description: The submitted query. required: - original results: type: array items: $ref: '#/components/schemas/SearchResult' total_estimated_matches: type: integer description: Estimated total matches when available. Omitted when unknown. format: int64 required: - id - created - latency_ms - query - results description: JSON object containing request metadata and ranked search results. ErrorResponse: type: object properties: id: type: string description: Request ID. error: type: object properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable error description. param: type: string description: Invalid field path when applicable. type: type: string description: Error category. required: - code - message - type required: - id - error ContentOptions: type: object properties: snippet: type: boolean description: >- Include an excerpt when available. Omitted when disabled or when text or markdown is returned. default: true text: $ref: '#/components/schemas/SearchTextOptions' SearchResult: type: object properties: id: type: string description: Position anchor within this response. Not stable across requests. example: results.#0 title: type: string description: Page title. url: type: string description: Canonical source URL. May include tracking parameters. display_url: type: string description: >- Display-friendly scheme, host, and path with query parameters removed. published_at: type: string description: Publication time in UTC. Always present; null if unknown. format: date-time nullable: true score: type: number description: >- Relevance score from 0 to 1. Higher values indicate greater relevance. minimum: 0 maximum: 1 snippet: type: string description: >- Short excerpt when enabled and available. Omitted when text or markdown is returned. text: type: string description: >- Page content when content.text is requested with format set to text. Bounded by content.text.max_characters; replaces snippet. markdown: type: string description: >- Page content when content.text is requested with format set to markdown. Bounded by content.text.max_characters; replaces snippet. favicon: type: string description: Favicon URL when available. images: type: array description: Always an array, possibly empty. items: $ref: '#/components/schemas/Image' is_safe: type: boolean description: >- Safety classification for the result. Null if the source has no classification. nullable: true required: - id - url - published_at - images - is_safe SearchTextOptions: type: object description: Return extracted page content instead of snippet. properties: format: type: string description: 'Page content format and response field: text or markdown.' enum: - text - markdown default: text max_characters: type: integer description: Maximum Unicode code points per result after format conversion. default: 5000 Image: type: object properties: url: type: string description: Image URL; items without a usable URL are excluded. width: type: integer description: Width in pixels, or null if unknown. nullable: true height: type: integer description: Height in pixels, or null if unknown. nullable: true alt: type: string description: Alternative text, or null if unknown. nullable: true required: - url - width - height - alt securitySchemes: bearerAuth: type: http scheme: bearer description: API key beginning with sk_. Create a key in the Ateve Dashboard. ````