> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nano-gpt.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Direct Web Search API

> Run direct web search requests with explicit query control, Linkup output formats, and normalized metadata

## Overview

Use `POST /api/web` when you want direct control over search requests and output formatting.

You can also call this tool through the unified [Data API](/api-reference/endpoint/data-api) at `POST /api/v1/data/web/search`. The Data API preserves this endpoint's request body, response body, billing, and provider behavior while adding discovery and dispatch metadata.

For chat-first workflows, use `POST /api/v1/chat/completions` with model suffixes like `:online`, `:online/linkup`, or `:online/linkup-deep`, including provider-specific suffixes such as `:online/exa-instant`, `:online/exa-deep-reasoning`, `:online/brave`, and `:online/valyu-web-deep`. See [Model Suffixes](/api-reference/miscellaneous/model-suffixes#web-search-suffixes).

## When to use which endpoint

| Use case                                                                                               | Endpoint                                       |
| ------------------------------------------------------------------------------------------------------ | ---------------------------------------------- |
| You want the model to answer with web context in one call                                              | `POST /api/v1/chat/completions` + `:online...` |
| You want one discoverable endpoint family for data tools                                               | `POST /api/v1/data/web/search`                 |
| You need explicit control over `query`, `outputType`, domain/date filters, or structured schema output | `POST /api/web`                                |
| You need OpenAI-native web search                                                                      | `POST /api/v1/chat/completions` only           |

## Authentication

Either auth header is supported:

<ParamField header="Authorization" type="string">
  Bearer `YOUR_API_KEY`
</ParamField>

<ParamField header="x-api-key" type="string">
  `YOUR_API_KEY`
</ParamField>

## Accountless x402 Payment

For accountless payment, prefer the public Data API path:

```bash theme={null}
curl -i https://nano-gpt.com/api/v1/data/web/search \
  -H "Content-Type: application/json" \
  -H "x-x402: true" \
  -d '{
    "query": "What happened in AI this week?",
    "provider": "linkup",
    "depth": "standard",
    "outputType": "sourcedAnswer"
  }'
```

To request an accountless x402 quote, send the API request without `Authorization` or `x-api-key`, and include `x-x402: true`. NanoGPT will return `402 Payment Required` with available payment options. This endpoint supports accountless x402 payments where listed by `GET /api/v1/x402/endpoints`, including Lightning L402 when advertised. See [Accountless x402 API Payments](/api-reference/miscellaneous/x402) for the full flow.

If you receive `401 missing_api_key` immediately, check that the initial quote request includes `x-x402: true`. Without that header, NanoGPT does not enter the x402 quote flow.

## Request body

<ParamField body="query" type="string" required>
  Search query string.
</ParamField>

<ParamField body="provider" type="string" default="linkup">
  Search provider. `openai-native` is not allowed on `/api/web`.
</ParamField>

<ParamField body="depth" type="string" default="standard">
  Search depth. For Linkup: `standard` or `deep`.
</ParamField>

<Note>
  For Linkup, `depth: "standard"` is executed as Linkup `fast` under the hood.
</Note>

<ParamField body="outputType" type="string" default="searchResults">
  Output mode. Allowed values: `searchResults`, `sourcedAnswer`, `structured`.
</ParamField>

<ParamField body="structuredOutputSchema" type="string">
  Required when `outputType` is `structured`. Pass a JSON schema string.
</ParamField>

<ParamField body="includeImages" type="boolean" default={false}>
  Include image results.
</ParamField>

<ParamField body="fromDate" type="string">
  Earliest result date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="toDate" type="string">
  Latest result date (`YYYY-MM-DD`).
</ParamField>

<ParamField body="includeDomains" type="string[]">
  Restrict results to these domains.
</ParamField>

<ParamField body="excludeDomains" type="string[]">
  Exclude these domains.
</ParamField>

<Note>
  Linkup supports `outputType: "searchResults"`, `"sourcedAnswer"`, and `"structured"`.
  Non-Linkup providers currently support only `outputType: "searchResults"`.
</Note>

## Response shape

<ResponseField name="data" type="array|object">
  Provider-formatted payload.
</ResponseField>

<ResponseField name="metadata" type="object">
  <Expandable title="metadata">
    <ResponseField name="query" type="string">
      Executed query.
    </ResponseField>

    <ResponseField name="provider" type="string">
      Resolved provider (for example, `linkup`).
    </ResponseField>

    <ResponseField name="depth" type="string">
      Resolved depth.
    </ResponseField>

    <ResponseField name="outputType" type="string">
      Resolved output type.
    </ResponseField>

    <ResponseField name="timestamp" type="string">
      ISO-8601 timestamp.
    </ResponseField>

    <ResponseField name="cost" type="number">
      Request cost in USD.
    </ResponseField>
  </Expandable>
</ResponseField>

For `searchResults`, `data` is an array of normalized results.
For `sourcedAnswer` and `structured`, `data` is the provider response object.

### Example response

```json theme={null}
{
  "data": "... provider-formatted payload ...",
  "metadata": {
    "query": "string",
    "provider": "linkup",
    "depth": "standard",
    "outputType": "sourcedAnswer",
    "timestamp": "ISO-8601",
    "cost": 0.006
  }
}
```

## Pricing (hosted key)

| Mode            | Price   |
| --------------- | ------- |
| Linkup standard | \$0.006 |
| Linkup deep     | \$0.06  |

## Error codes

| HTTP status | Meaning                           |
| ----------- | --------------------------------- |
| `400`       | Invalid parameters                |
| `401`       | Invalid session or auth           |
| `402`       | Insufficient balance or usage cap |
| `429`       | Rate limited                      |
| `503`       | Provider key missing              |
| `504`       | Search failed or timed out        |

## Examples

<CodeGroup>
  ```bash cURL (Authorization) theme={null}
  curl -X POST https://nano-gpt.com/api/web \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "What happened in AI this week?",
      "provider": "linkup",
      "depth": "standard",
      "outputType": "sourcedAnswer"
    }'
  ```

  ```bash cURL (x-api-key) theme={null}
  curl -X POST https://nano-gpt.com/api/web \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Latest OpenAI announcements",
      "provider": "linkup",
      "depth": "deep",
      "outputType": "searchResults"
    }'
  ```

  ```bash cURL (structured output) theme={null}
  curl -X POST https://nano-gpt.com/api/web \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query": "Top 5 AI coding tools in 2026 with pricing",
      "provider": "linkup",
      "depth": "standard",
      "outputType": "structured",
      "structuredOutputSchema": "{\"type\":\"object\",\"properties\":{\"tools\":{\"type\":\"array\",\"items\":{\"type\":\"object\",\"properties\":{\"name\":{\"type\":\"string\"},\"price\":{\"type\":\"string\"}},\"required\":[\"name\"]}}},\"required\":[\"tools\"]}"
    }'
  ```

  ```bash cURL (chat completions with Linkup) theme={null}
  curl -X POST https://nano-gpt.com/api/v1/chat/completions \
    -H "Authorization: Bearer YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "model": "gpt-4o:online/linkup",
      "messages": [
        { "role": "user", "content": "Summarize today'\''s top AI headlines." }
      ]
    }'
  ```
</CodeGroup>

## Related docs

* [Chat Completion](/api-reference/endpoint/chat-completion)
* [Data API](/api-reference/endpoint/data-api)
* [Web Search in Text Generation Guide](/api-reference/text-generation)
* [Model Suffixes](/api-reference/miscellaneous/model-suffixes)