Send one POST request to the Search endpoint
Nimble Search takes a question and returns a ranked list of web pages. Each result has a title, a URL and a text excerpt from the page. The excerpt holds the parts of the page that best match the question. Your browser's model reads these excerpts and writes the answer for the user.
Get an API key
Your Nimble contact creates the account and sends the key. The samples below read it from the NIMBLE_API_KEY variable.
Send the request
Send a POST to https://sdk.nimbleway.com/v2/search with the key as a Bearer token.
Pass the results to your model
Give your model the excerpts and URLs. Show the URLs to the user as sources.
curl -X POST https://sdk.nimbleway.com/v2/search \ -H "Authorization: Bearer $NIMBLE_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "query": "오늘 서울 주요 뉴스", "search_depth": "standard", "max_results": 10, "country": "KR", "locale": "ko", "time_range": "day" }'
import os, requests resp = requests.post( "https://sdk.nimbleway.com/v2/search", headers={"Authorization": f"Bearer {os.environ['NIMBLE_API_KEY']}"}, json={ "query": user_question, # the user's words, in the user's language "search_depth": "standard", "max_results": 10, "country": "KR", # the user's market "locale": "ko", # the user's language "time_range": "day", # only for questions about today }, ) results = resp.json()["results"] context = "\n\n".join(f"[{i+1}] {r['title']} ({r['url']})\n{r['description']}" for i, r in enumerate(results))
const res = await fetch("https://sdk.nimbleway.com/v2/search", { method: "POST", headers: { Authorization: `Bearer ${process.env.NIMBLE_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ query: userQuestion, // the user's words, in the user's language search_depth: "standard", max_results: 10, country: "KR", // the user's market locale: "ko", // the user's language time_range: "day", // only for questions about today }), }); const { results } = await res.json(); const context = results .map((r, i) => `[${i + 1}] ${r.title} (${r.url})\n${r.description}`) .join("\n\n");
Full response to this request
Fields in the response
| Field | What it holds |
|---|---|
| results[].title | The page title. |
| results[].url | The page address. Show it to the user as the source. |
| results[].description | The excerpt from the page, in Markdown. Your model reads this field. |
| results[].content | The whole page. It is empty unless the request sets full_content to true. |
| results[].metadata | The rank of the result, plus the country and language of the search. |
| total_results | The number of results returned. |
| request_id | A unique ID for the request. Quote it when you contact Nimble support. |
Use standard depth, 10 results and the user's market
These settings suit a browser that answers questions as the user types them. Standard depth is the default setting, so the request can leave it out.
Settings for each search
| Field | Value | Why for the browser |
|---|---|---|
| query | The user's question as typed | Search reads full questions in any language. Send the user's own words. |
| search_depth | standard | Standard depth returns a ranked list of pages with an excerpt for each page. |
| max_results | 10 any value from 1 to 100 | In our tests, 5, 10 and 20 results produced responses of about the same size. A higher value spreads the same amount of text across more sources. The value is an upper limit, so a narrow question can return fewer pages. |
| country | "KR" the user's market | This two-letter code picks the country whose web results Nimble returns. The default is "US". |
| locale | "ko" the user's language | This code sets the language of the results. The default is "en". |
| time_range | "day" for questions about today | It keeps only pages from the last hour, day, week, month or year. With "day", the Seoul news question returned today's articles. Without it, the same question returned news site home pages. |
| include_answer | Leave it out | This option makes Nimble write a short answer. Your browser's model already writes the answer, so the option only adds a few seconds. |
| full_content | Leave it out | This option adds each whole page to the response. The response becomes several times larger, and your model reads more tokens. |
Set the country and language for each user
We sent a question about today's local news in eight markets. Each search used standard depth, 10 results and time_range: "day". The first three sources came from local publishers in each market.
| Market | country | locale | Question sent | First three sources |
|---|
The country and language can differ. An English speaker in Seoul gets Korean sources that publish in English when the request sets country: "KR" and locale: "en".
The Search endpoint accepts 15 request fields
Only query is required. Every other field has a default value. The last column says how each field behaves with standard depth.
| Field | Accepted values | Default | Use with standard depth |
|---|---|---|---|
| Question and result count | |||
| query | Text, any language | Required | Send the user's question as typed. |
| search_depth | "standard", "lite" | "standard" | Standard returns an excerpt for each page. Lite returns only a short snippet. |
| max_results | 1 to 100 | 10 | It sets the most results returned. A narrow question can return fewer. |
| Market and language | |||
| country | Two-letter country code, such as "KR" or "JP" | "US" | Set it to the user's market. |
| locale | Language code, such as "ko" or "ja" | "en" | Set it to the user's language. |
| Freshness | |||
| time_range | "hour", "day", "week", "month", "year" | None | Use it for news and other questions about recent events. |
| start_date | "YYYY-MM-DD" or "YYYY" | None | It keeps pages published after this date. Do not combine it with time_range. |
| end_date | "YYYY-MM-DD" or "YYYY" | None | It keeps pages published before this date. Do not combine it with time_range. |
| Sources | |||
| include_domains | Up to 50 domains | None | It limits results to these sites. Use it when a feature should cite only trusted sources. |
| exclude_domains | Up to 50 domains | None | It removes these sites from the results. |
| content_type | "pdf", "docx", "xlsx", "pptx", "documents", "spreadsheets", "presentations" | None | It returns only files of these types. |
| focus | "general", or a specialist source such as "news" or "shopping" | "general" | Keep "general". The specialist sources work only with lite depth. |
| Extra output | |||
| include_answer | true, false | false | Nimble writes a short answer with numbered citations to the results. It adds a few seconds. |
| full_content | true, false | false | It adds each whole page in the content field. The response becomes several times larger. |
| output_format | "markdown", "plain_text", "simplified_html" | "markdown" | It sets the text format of returned page content. |