> For the complete documentation index, see [llms.txt](https://docs.otari.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.otari.ai/otari/for-integrators/api-reference/search.md). # Search ## Create Search > Run a search against a configured search tool.\ > \ > The tool is taken from \`\`search\_tool\_name\`\`, which may be omitted when the\ > deployment's \`\`web\_search\_default\_tool\`\` names one, or when exactly one\ > tool is configured. Such a call runs on the workspace's organization search\ > key when it has one.\ > \ > Authentication modes:\ > \- Master key: the \`\`user\`\` field is required and may name any existing user.\ > \- API key: usage and spend bind to the key's own user. A \`\`user\`\` field\ > naming a different user is rejected with 403 (or ignored, when the key's\ > own \`\`reject\_user\_mismatch\`\` is false, or the deployment-wide setting is\ > disabled and the key does not override it); it is never billed to that\ > user.\ > \- Service key: a \`\`user\`\` field names one of the key owner's end users,\ > created on first use on the budget \`\`Otari-End-User-Budget\`\` names (or\ > the key's default), and is billed and rate limited as that end user, as\ > on chat completions. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"SearchRequest":{"description":"A direct search request: LiteLLM's ``/v1/search`` body, plus ``include_raw`` and ``provider_options``.","properties":{"country":{"anyOf":[{"maxLength":2,"minLength":2,"type":"string"},{"type":"null"}],"description":"Two-letter ISO country code to localize results to","title":"Country"},"include_raw":{"default":false,"description":"Also return the provider's whole response, as raw.","title":"Include Raw","type":"boolean"},"max_results":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"Maximum number of results to return; 10 when unset. Lowered to the workspace's ceiling when it sets one, and to the provider's own maximum.","title":"Max Results"},"max_tokens_per_page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"Approximate cap on the page content returned per result","title":"Max Tokens Per Page"},"provider_options":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Native options for the provider that serves the call, under the provider's own names, as GET /api/v1/search-tools/providers lists them. An option the provider does not take from a request is refused with a 400. On a call that names no tool they go to whichever provider serves it, so name the tool when they are meant for one provider.","title":"Provider Options"},"query":{"description":"The search query","minLength":1,"title":"Query","type":"string"},"search_domain_filter":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"null"}],"description":"Restrict results to these domains; prefix a domain with '-' to exclude it instead","title":"Search Domain Filter"},"search_tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Configured search tool to run against. Optional when the deployment names a default (web_search_default_tool) or has exactly one tool, and ignored on POST /api/v1/search/{search_tool_name}.","title":"Search Tool Name"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User ID for usage attribution","title":"User"}},"required":["query"],"title":"SearchRequest","type":"object"},"SearchResponse":{"description":"A completed direct search.","properties":{"object":{"const":"search","default":"search","title":"Object","type":"string"},"raw":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"The provider's whole response, untouched; only when the request set include_raw.","title":"Raw"},"results":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"title":"Results","type":"array"},"search_tool":{"description":"The configured search tool that served the request","title":"Search Tool","type":"string"}},"required":["search_tool","results"],"title":"SearchResponse","type":"object"},"SearchResultItem":{"description":"One search result, shaped as LiteLLM's ``SearchResult``.","properties":{"date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The page's date, as the provider gave it.","title":"Date"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Always null: no provider reports it.","title":"Last Updated"},"snippet":{"description":"The page text the provider returned, else its excerpt, cut to the page budget.","title":"Snippet","type":"string"},"title":{"description":"The page's title; empty when the provider gave none.","title":"Title","type":"string"},"url":{"title":"Url","type":"string"}},"required":["title","url","snippet"],"title":"SearchResultItem","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/search":{"post":{"description":"Run a search against a configured search tool.\n\nThe tool is taken from ``search_tool_name``, which may be omitted when the\ndeployment's ``web_search_default_tool`` names one, or when exactly one\ntool is configured. Such a call runs on the workspace's organization search\nkey when it has one.\n\nAuthentication modes:\n- Master key: the ``user`` field is required and may name any existing user.\n- API key: usage and spend bind to the key's own user. A ``user`` field\n naming a different user is rejected with 403 (or ignored, when the key's\n own ``reject_user_mismatch`` is false, or the deployment-wide setting is\n disabled and the key does not override it); it is never billed to that\n user.\n- Service key: a ``user`` field names one of the key owner's end users,\n created on first use on the budget ``Otari-End-User-Budget`` names (or\n the key's default), and is billed and rate limited as that end user, as\n on chat completions.","operationId":"search-create_search","requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create Search","tags":["search"]}}}} ``` ## Create Search For Tool > Run a search against the search tool named in the path.\ > \ > Identical to \`\`POST /api/v1/search\`\` except that the path names the tool, which\ > is the form LiteLLM clients use. Any \`\`search\_tool\_name\`\` in the body is\ > ignored.\ > \ > Authentication modes:\ > \- Master key: the \`\`user\`\` field is required and may name any existing user.\ > \- API key: usage and spend bind to the key's own user. A \`\`user\`\` field\ > naming a different user is rejected with 403 (or ignored, when the key's\ > own \`\`reject\_user\_mismatch\`\` is false, or the deployment-wide setting is\ > disabled and the key does not override it); it is never billed to that\ > user.\ > \- Service key: a \`\`user\`\` field names one of the key owner's end users,\ > created on first use on the budget \`\`Otari-End-User-Budget\`\` names (or\ > the key's default), and is billed and rate limited as that end user, as\ > on chat completions. ```json {"openapi":"3.1.0","info":{"title":"otari","version":"0.33.0"},"security":[{"ApiKeyAuth":[]},{"XApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"description":"Enter your API key here (sent as Otari-Key header).","in":"header","name":"Otari-Key","type":"apiKey"},"XApiKeyAuth":{"description":"Anthropic-native clients send credentials here (no Bearer prefix).","in":"header","name":"x-api-key","type":"apiKey"}},"schemas":{"SearchRequest":{"description":"A direct search request: LiteLLM's ``/v1/search`` body, plus ``include_raw`` and ``provider_options``.","properties":{"country":{"anyOf":[{"maxLength":2,"minLength":2,"type":"string"},{"type":"null"}],"description":"Two-letter ISO country code to localize results to","title":"Country"},"include_raw":{"default":false,"description":"Also return the provider's whole response, as raw.","title":"Include Raw","type":"boolean"},"max_results":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"Maximum number of results to return; 10 when unset. Lowered to the workspace's ceiling when it sets one, and to the provider's own maximum.","title":"Max Results"},"max_tokens_per_page":{"anyOf":[{"minimum":1,"type":"integer"},{"type":"null"}],"description":"Approximate cap on the page content returned per result","title":"Max Tokens Per Page"},"provider_options":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"Native options for the provider that serves the call, under the provider's own names, as GET /api/v1/search-tools/providers lists them. An option the provider does not take from a request is refused with a 400. On a call that names no tool they go to whichever provider serves it, so name the tool when they are meant for one provider.","title":"Provider Options"},"query":{"description":"The search query","minLength":1,"title":"Query","type":"string"},"search_domain_filter":{"anyOf":[{"items":{"type":"string"},"maxItems":20,"type":"array"},{"type":"null"}],"description":"Restrict results to these domains; prefix a domain with '-' to exclude it instead","title":"Search Domain Filter"},"search_tool_name":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Configured search tool to run against. Optional when the deployment names a default (web_search_default_tool) or has exactly one tool, and ignored on POST /api/v1/search/{search_tool_name}.","title":"Search Tool Name"},"user":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"User ID for usage attribution","title":"User"}},"required":["query"],"title":"SearchRequest","type":"object"},"SearchResponse":{"description":"A completed direct search.","properties":{"object":{"const":"search","default":"search","title":"Object","type":"string"},"raw":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"description":"The provider's whole response, untouched; only when the request set include_raw.","title":"Raw"},"results":{"items":{"$ref":"#/components/schemas/SearchResultItem"},"title":"Results","type":"array"},"search_tool":{"description":"The configured search tool that served the request","title":"Search Tool","type":"string"}},"required":["search_tool","results"],"title":"SearchResponse","type":"object"},"SearchResultItem":{"description":"One search result, shaped as LiteLLM's ``SearchResult``.","properties":{"date":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"The page's date, as the provider gave it.","title":"Date"},"last_updated":{"anyOf":[{"type":"string"},{"type":"null"}],"description":"Always null: no provider reports it.","title":"Last Updated"},"snippet":{"description":"The page text the provider returned, else its excerpt, cut to the page budget.","title":"Snippet","type":"string"},"title":{"description":"The page's title; empty when the provider gave none.","title":"Title","type":"string"},"url":{"title":"Url","type":"string"}},"required":["title","url","snippet"],"title":"SearchResultItem","type":"object"},"HTTPValidationError":{"properties":{"code":{"const":"invalid_request","description":"Stable error code, also sent as the Otari-Error-Code header.","title":"Code","type":"string"},"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"title":"Detail","type":"array"}},"title":"HTTPValidationError","type":"object"},"ValidationError":{"properties":{"ctx":{"title":"Context","type":"object"},"input":{"title":"Input"},"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"title":"Location","type":"array"},"msg":{"title":"Message","type":"string"},"type":{"title":"Error Type","type":"string"}},"required":["loc","msg","type"],"title":"ValidationError","type":"object"}}},"paths":{"/api/v1/search/{search_tool_name}":{"post":{"description":"Run a search against the search tool named in the path.\n\nIdentical to ``POST /api/v1/search`` except that the path names the tool, which\nis the form LiteLLM clients use. Any ``search_tool_name`` in the body is\nignored.\n\nAuthentication modes:\n- Master key: the ``user`` field is required and may name any existing user.\n- API key: usage and spend bind to the key's own user. A ``user`` field\n naming a different user is rejected with 403 (or ignored, when the key's\n own ``reject_user_mismatch`` is false, or the deployment-wide setting is\n disabled and the key does not override it); it is never billed to that\n user.\n- Service key: a ``user`` field names one of the key owner's end users,\n created on first use on the budget ``Otari-End-User-Budget`` names (or\n the key's default), and is billed and rate limited as that end user, as\n on chat completions.","operationId":"search-create_search_for_tool","parameters":[{"description":"Configured search tool to run against","in":"path","name":"search_tool_name","required":true,"schema":{"description":"Configured search tool to run against","title":"Search Tool Name","type":"string"}}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchRequest"}}},"required":true},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchResponse"}}},"description":"Successful Response"},"422":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}},"description":"Validation Error"}},"summary":"Create Search For Tool","tags":["search"]}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.otari.ai/otari/for-integrators/api-reference/search.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.