Search the web within a token budget
One call runs search → fetch → chunk → rerank → pack, and returns the passages that fit max_tokens — not a result count. Every passage carries character offsets back into a document you can rehydrate for free with GET /v1/docs/{id}.
Enforces the calling key’s scopes, depth ceiling and budget, and charges the workspace’s credit balance.
curl https://api.siftsearch.si/v1/search \
-H "Authorization: Bearer $SIFT_KEY" \
-H 'Content-Type: application/json' \
-d '{
"query": "changes to EU AI Act GPAI obligations",
"max_tokens": 4000,
"depth": "auto"
}'Request body
- query stringrequired≤ 2000 chars
The search query. Instruction-style prompts need
standardordeep.- depth "auto" | "fast" | "standard" | "deep"default "standard"
Also governs how many sources are fetched in full:
fastfetches none and ranks the search snippets alone,standardfetches up to 5,deepup to 8. Deeper means better passages, more upstream calls and higher latency. Requesting a depth above the key’s ceiling is refused withdepth_ceiling_exceededrather than silently downgraded.autopicks the cheapest depth that can answer the query and *is* clamped to the ceiling silently — the response’sdepthblock reports what actually ran and why. The default staysstandard, so omitting this field never adds a routing call.- max_tokens integer500–32000
The context budget.
passages[]is packed to fit inside it and never exceeds it. Defaults to the calling key’s configured context budget.- max_results integer1–100
Upper bound on how many results the upstream search returns.
max_tokensis what bounds the response.- include_domains string[]
- exclude_domains string[]
- source_scripts "latin" | "any"default "latin"
Which writing systems a source may be in.
latin, the default, drops sources whose title and snippet are predominantly not written in the Latin alphabet — Chinese, Japanese, Korean, Cyrillic, Arabic, Hebrew, Devanagari, Thai — and drops them *before* the fetch fan-out, so an agent that asked in English is never handed, or charged for, a page it cannot read.anyturns the check off. This is script detection, not language identification: a French or German source is Latin script and always passes. If every source found is non-Latin the response comes back with no passages rather than quietly ignoring the setting.- from_date string
Inclusive lower bound,
YYYY-MM-DD. Set dates here, never insidequery.- to_date string
- freshness "any" | "last_24_hours" | "last_7_days" | "last_30_days" | "last_90_days" | "last_year"
How recent a source must be.
last_7_daysand friends resolve to a date bound, and sources the *content itself* dates outside it are withheld asstale— the upstream search has no date field of its own, so its date filter is a guess until someone reads the page. A source whose date could not be read is kept, carryingas_of: null.This corrects precision, not recall: it removes stale pages the upstream filter let through, and cannot recover fresh pages it wrongly excluded.
Mutually exclusive with
from_dateandto_date— sending both isinvalid_request, because silently preferring one is exactly the guess this field exists to remove.- agent_tag string≤ 64 chars
Free-form label for the calling agent. Drives per-agent spend reporting.
- session_id string≤ 64 chars
The agent run this call belongs to, from
POST /v1/sessions. A question the run has already asked is answered from what it returned, at no charge and with no upstream call. Requires thesessionsscope.- deltas_only booleandefault false
Withhold sources this run has already been given the text of, as bare
doc_ids. The fetch budget goes to pages the run has not read instead. Requiressession_id.- verify booleandefault false
Score every returned passage for how strongly it supports the query, and report it as
supporton each one. Adds one model call to the request — it is charged and it appears inupstream_calls— which is why it is opt-in rather than always on. A passage whose support could not be measured returnssupport: null, never a guessed number.
Response · 200
- request_id stringrequired
- passages object[]required
- withheld object[]required
Sources found but not returned, as bare ids. Costs no tokens; fetch any of them by id if the agent actually needs the text.
- usage objectrequired
- depth objectrequired
- session object
Errors
- 400invalid_request
- 401invalid_api_key
- 402insufficient_credits (top up) or budget_exhausted (a self-imposed cap was reached). 402 rather than 429 on purpose: a 429 invites a retry loop, a 402 does not.
- 403scope_missing or depth_ceiling_exceeded
- 429rate_limited. Carries `Retry-After` and `details.retry_after_ms`.
- 502upstream_unavailable