POST /v1/search

All requests require an API key. See Authentication.

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

Request body

string

required

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

integer

default:"5"

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

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.

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.

string

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

string

default:"en"

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

string[]

default:"[]"

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

string[]

default:"[]"

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

Response

string

The query string from your request, echoed back.

SearchResult[]

Ranked array of search results, each containing extracted snippets.

Show SearchResult fields

integer

Position in the result list, starting at 1.

string

URL of the source page.

string

Title of the source page.

Snippet[]

Extracted passages from this page.

Show Snippet fields

string

Verbatim passage from the source page.

float

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

string | null

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

string | null

ISO 8601 date string if available from the source page.

string | null

ISO 8601 date string if available from the source page.

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