Web Search API

The Web Search API returns web pages for a query, including the text of each page. Use it to implement a web search tool for any model or agent framework. The model calls your tool, your backend calls this endpoint, and the results go back to the model.

Endpoint: POST https://api.thesys.dev/v1/search/web

The endpoint is not OpenAI compatible, so call it with fetch or another HTTP client. Server calls use the API key described in Authentication.

Make a request

export async function searchWeb(query: string) {
  const response = await fetch("https://api.thesys.dev/v1/search/web", {
    method: "POST",
    headers: {
      Authorization: `Bearer ${process.env.THESYS_API_KEY}`,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({ query, num_results: 5 }),
  });

  if (!response.ok) {
    throw new Error(`Web search failed: ${response.status}`);
  }

  return response.json();
}

Request

Read the result

results holds the matches, and can hold fewer than num_results. usage.search_units reports the searches charged, and is always 1.

A search with one result:

{
  "query": "nestjs 11 release notes",
  "results": [
    {
      "title": "NestJS 11 is now available",
      "url": "https://example.com/nestjs-11",
      "text": "NestJS 11 brings ...",
      "published_date": "2026-01-15",
      "favicon": "https://example.com/favicon.ico"
    }
  ],
  "usage": { "search_units": 1 }
}

Use as a function tool

Declare the tool in your model request. This example uses the Chat Completions format. When the model calls the tool, call searchWeb in your backend and return the results as the tool result. The loop is the same as for any other function tool. See Function tools.

export const searchWebTool = {
  type: "function",
  function: {
    name: "search_web",
    description: "Search the web for current information.",
    parameters: {
      type: "object",
      properties: { query: { type: "string", description: "What to search for" } },
      required: ["query"],
    },
  },
} as const;

text holds the full page, so trim it before the results go back to the model.

The Responses API can also run web search inside the Gateway, with no function tool. See Hosted Tools.

Data

The query you send is passed to a third-party search provider. The query and the results are not stored beyond the request logs.

Pricing

Each successful call is charged the search provider's price from your credits, with no markup, and does not use a plan API call. A call that finds no results is still charged. A failed call is free. See Pricing for the current rate.

Errors

The endpoint returns the same error shape as the Chat Completions and Responses APIs. For a 400, message is a list of every problem.