POST /v1/search

All requests require an API key. See Authentication.

POST https://api.snipex.dev/v1/search

Request body

query

string

required

The search query. This is what Snippex searches for and extracts snippets relevant to.

num_results

integer

default:"5"

Number of search results to retrieve and extract from. Range: 1–10.

max_snippets_per_result

integer

default:"3"

Maximum number of snippets to extract per result. Range: 1–5.The actual number returned may be lower if the page doesn’t contain enough relevant passages.

search_depth

string

default:"balanced"

Controls how deeply the extraction engine analyzes each page.

"precise" — fewer snippets, higher confidence, fastest
"balanced" — default, good mix of speed and coverage
"exhaustive" — maximum snippets, most thorough

See Search Depth for details.

recency

string

Filter results by publish date. One of: "day", "week", "month", "year".Omit or set to null for no filter (default).

language

string

default:"en"

Language code for results (e.g. "en", "fr", "de").

include_domains

string[]

default:"[]"

Restrict results to these domains only. Pass bare domain names: ["nature.com", "bbc.com"].

exclude_domains

string[]

default:"[]"

Exclude these domains from results. Pass bare domain names: ["reddit.com"].

Response

query

string

The query string from your request, echoed back.

results

SearchResult[]

Ranked array of search results, each containing extracted snippets.

Show SearchResult fields

rank

integer

Position in the result list, starting at 1.

url

string

URL of the source page.

title

string

Title of the source page.

snippets

Snippet[]

Extracted passages from this page.

Show Snippet fields

text

string

Verbatim passage from the source page.

relevance_score

float

How relevant this passage is to your query. Range: 0.0–1.0.

warning

string | null

Set if extraction partially failed for this result. The result is still returned for transparency.

publish_date

string | null

ISO 8601 date string if available from the source page.

last_updated

string | null

ISO 8601 date string if available from the source page.

total_latency_ms

integer

Total time taken for the request, in milliseconds.

Example

curl -X POST https://api.snipex.dev/v1/search \
  -H "Authorization: Bearer snx_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "how does CRISPR gene editing work",
    "num_results": 2,
    "search_depth": "balanced",
    "recency": "year"
  }'

{
  "query": "how does CRISPR gene editing work",
  "results": [
    {
      "rank": 1,
      "url": "https://example.com/crispr-explainer",
      "title": "CRISPR-Cas9: A Simple Guide to Gene Editing",
      "snippets": [
        {
          "text": "CRISPR-Cas9 works by using a guide RNA to direct the Cas9 protein to a specific location in the genome, where it makes a precise cut in the DNA double helix.",
          "relevance_score": 0.97
        },
        {
          "text": "Once the DNA is cut, the cell's natural repair mechanisms can be used to delete, correct, or insert genetic material at the target site.",
          "relevance_score": 0.89
        }
      ],
      "warning": null,
      "publish_date": "2024-03-12",
      "last_updated": null
    }
  ],
  "total_latency_ms": 921
}

Error codes

Status	Meaning
`400 Bad Request`	Missing or invalid `query` field
`401 Unauthorized`	Missing or invalid API key
`422 Unprocessable Entity`	Request body failed validation — check parameter types and ranges
`429 Too Many Requests`	Rate limit exceeded
`500 Internal Server Error`	Unexpected server-side error

​Request body

​Response

​Example

​Error codes

Request body

Response

Example

Error codes