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

# Unified search

> One endpoint across unstructured documents and structured connector data — Memic routes the query for you.

Memic's search endpoint is a **unified retrieval layer**. You pass it a
query, and Memic classifies the intent and routes it to the right
backend — semantic search over your indexed documents for
natural-language questions, or structured queries against connector-backed
data sources for filters and lookups. You don't maintain two different
retrieval pipelines; your agent just calls `client.search(...)` and gets
back the right answer.

## The basics

```python theme={null}
results = client.search("what is our refund policy")

for hit in results.semantic:
    print(f"[{hit.score:.2f}] {hit.text[:200]}...")
    print(f"   from {hit.source.file_name}")
```

Or via HTTP:

```bash theme={null}
curl https://api.memic.ai/api/v1/search \
  -H "X-API-Key: $MEMIC_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "what is our refund policy", "top_k": 5}'
```

## How routing works

Memic classifies every query along one axis: **semantic** or **structured**.

* **Semantic queries** — natural-language questions best answered from
  document content ("what is our refund policy", "summarize Q3 earnings",
  "how do I reset my password"). These hit the semantic index over your
  uploaded files.
* **Structured queries** — filters, aggregations, lookups, or anything
  that reads more like a database query ("orders from Q3 2025 over
  \$500", "customers in the Enterprise tier", "open tickets assigned to
  me"). These hit connectors you've attached to the environment
  (Postgres, Notion, Google Sheets, Salesforce, custom connectors).

The `routing` field on every response shows exactly which path was taken
and why:

```json theme={null}
{
  "query": "what is our refund policy",
  "results": {
    "semantic": [ ... ],
    "structured": null
  },
  "total_results": 3,
  "routing": {
    "route": "semantic",
    "reasoning": "Natural-language query over document content.",
    "connector_id": null
  }
}
```

For a structured query you'd see `route: "structured"`, a non-null
`connector_id`, and the results in `results.structured` instead of
`results.semantic`.

## Response shape

```json theme={null}
{
  "query": "...",
  "results": {
    "semantic": [
      {
        "text": "Customers may request a refund within 30 days...",
        "score": 0.87,
        "source": {
          "file_id": "...",
          "file_name": "policies.pdf",
          "page": 4
        }
      }
    ],
    "structured": null
  },
  "total_results": 3,
  "routing": {
    "route": "semantic",
    "reasoning": "...",
    "connector_id": null
  }
}
```

Both `semantic` and `structured` are present on every response — one will
be populated, the other will be `null`. Your agent code can inspect
`routing.route` to decide how to format the answer.

## When to use which

You don't normally pick. Memic picks for you based on the query. But if
you want to influence routing, the easiest lever is phrasing:

* **Push toward semantic**: use natural-language phrasing.
  *"What does our refund policy say about digital products?"*
* **Push toward structured**: use explicit filters and comparisons.
  *"Orders from 2025 where total > \$500 in the eu-west region"*

For the Application API's perspective both feel identical — same
endpoint, same response shape, same auth.

## Tuning `top_k`

`top_k` controls how many results come back. Defaults:

* **Default**: `5`
* **For RAG prompts** feeding an LLM: `5`–`10`
* **For search UIs** with a ranked list: `20`–`50`

Higher values cost more latency because more vectors are compared and
more passage text is returned over the wire.

## Filtering

Scope searches to specific folders or file types via the `filters` field:

```python theme={null}
results = client.search(
    query="refund policy",
    filters={"folder": "legal", "file_types": ["pdf"]}
)
```

Filters apply to the semantic side. Structured queries use their own
filters embedded in the query text.

## Debugging results

If search isn't returning what you expect:

1. **Check the routing.** Did Memic take the route you expected? If a
   natural-language query got routed to `structured`, rephrase it to be
   less filter-like. If a filter query got routed to `semantic`, be more
   explicit about the comparison.
2. **Verify the file is `ready`.** `GET /files/{id}/status`. If it's
   still `processing`, passages aren't indexed yet.
3. **Inspect `total_results`.** If it's `0`, no content matched. Try a
   broader query or verify the content is in the right environment.
4. **Confirm the environment.** `GET /me` returns which environment your
   key is bound to. If it's not the one your files live in, swap keys.
5. **Check connectors.** If you expected a structured result and got
   nothing, verify the connector is attached and synced in the
   dashboard.

## Related

<CardGroup cols={2}>
  <Card title="Chat guide" icon="comments" href="/guides/chat">
    Use search results to power grounded LLM answers.
  </Card>

  <Card title="API reference" icon="code" href="/api-reference/introduction">
    Full search endpoint reference.
  </Card>
</CardGroup>