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

# Web search

> Search the web and get AI-synthesized answers with cited sources.

## Request

```bash theme={null}
POST https://www.ninjachat.ai/api/v1/search
Authorization: Bearer nj_sk_YOUR_API_KEY
Content-Type: application/json
```

```json theme={null}
{
  "query": "latest developments in AI safety",
  "include_answer": true,
  "max_results": 10
}
```

## Response

```json theme={null}
{
  "object": "search.results",
  "query": "latest developments in AI safety",
  "answer": "Recent developments in AI safety include...",
  "sources": [
    {
      "url": "https://example.com/article",
      "title": "AI Safety Progress in 2026",
      "content": "Summary of the article...",
      "published_date": "2026-03-01"
    }
  ],
  "images": [],
  "follow_up_questions": [
    "What are the key AI safety organizations?",
    "How does RLHF improve AI safety?"
  ],
  "provider": "...",
  "cost_usd": 0.05,
  "request_id": "req_..."
}
```

The AI answer is in `answer` (`null` when `include_answer` is `false`). Sources are in `sources[]`; `published_date` is `null` when the source has no date. `images` is a list of `{ url, description }` populated when `include_images` is `true`. `provider` names the search backend that served the request, and `cost_usd` is the flat per-query price.

## Parameters

| Parameter        | Type    | Required | Default   | Description                           |
| ---------------- | ------- | -------- | --------- | ------------------------------------- |
| `query`          | string  | **Yes**  | —         | Search query. Max 2,000 chars.        |
| `group`          | string  | No       | `web`     | `web` or `news`                       |
| `max_results`    | integer | No       | 10        | Number of sources (1–20)              |
| `search_depth`   | string  | No       | `basic`   | `basic` (fast) or `advanced` (deeper) |
| `topic`          | string  | No       | `general` | `general`, `news`, or `finance`       |
| `include_answer` | boolean | No       | true      | Generate an AI-synthesized answer     |
| `include_images` | boolean | No       | false     | Include image results                 |

## Full working example

<CodeGroup>
  ```python Python SDK theme={null}
  result = client.search.query(
      query="latest developments in AI safety",
      group="news",
      search_depth="advanced",
      include_answer=True,
      max_results=10,
  )

  print(result["answer"])
  for source in result["sources"][:3]:
      print(f"- {source['title']}: {source['url']}")
  ```

  ```typescript TypeScript SDK theme={null}
  const result = await client.search.query({
    query: "latest developments in AI safety",
    group: "news",
    search_depth: "advanced",
    include_answer: true,
    max_results: 10,
  });

  console.log(result.answer);
  for (const source of result.sources.slice(0, 3)) {
    console.log(`- ${source.title}: ${source.url}`);
  }
  ```

  ```bash cURL theme={null}
  curl https://www.ninjachat.ai/api/v1/search \
    -H "Authorization: Bearer $NINJACHAT_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "query":"latest developments in AI safety",
      "group":"news",
      "search_depth":"advanced",
      "include_answer":true,
      "max_results":10
    }'
  ```
</CodeGroup>

<Tip>
  Not ready to write code? [Try it in the Playground →](https://www.ninjachat.ai/developers/playground)
</Tip>

## Search groups

| Group  | What it searches     | Use for                          |
| ------ | -------------------- | -------------------------------- |
| `web`  | General web          | Default. Most use cases.         |
| `news` | Recent news articles | News aggregation, current events |

## Use with RAG

Combine search with chat for retrieval-augmented generation:

```python theme={null}
# 1. Search for context
results = client.search.query(query="What is quantum computing?")

# 2. Feed to a chat model with sources as context
context = "\n".join(f"- {s['title']}: {s['content']}" for s in results["sources"][:5])

response = client.responses.create(
    model="gpt-5.6-luna",
    instructions=f"Answer using these sources:\n{context}",
    input="Explain quantum computing with citations",
)
print(response["output_text"])
```