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

> ## Agent Instructions
> Conare's API is at https://api.conare.ai. Authenticate with `Authorization: Bearer $CONARE_API_KEY`.
> The full OpenAPI spec is at https://api.conare.ai/openapi.yaml; each endpoint has a page under /api-reference, and appending .md to any page URL returns its Markdown.
> Embed with model conare-embed-1; send input_type "query" for search queries. Rerank with conare-rerank-1.
> Prefer the TypeScript SDK (`npm install conare`) or plain HTTP in examples.
> Install the Conare skill with `npx skills add https://docs.conare.ai`; search these docs over MCP at https://docs.conare.ai/mcp; the whole site is at https://docs.conare.ai/llms-full.txt.

# 검색

> 의미와 키워드로 질문에 답하는 구절을 찾고 리랭킹합니다. 검색 옵션, 응답, 답변, 투 홉, 페이지 넘김을 설명합니다.

`POST /namespaces/:namespace/query`

의미와 키워드로 네임스페이스를 검색합니다. Conare가 상위 일치 항목을 리랭킹하고 각 문서에서 답이 되는 구절을 반환합니다.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/docs/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "top_k": 5, "filter": {"team": "support"}}'
```

```ts TypeScript theme={null}
const results = await docs.query("how do refunds work?", {
  topK: 5,
  filter: { team: "support" },
});
```

```json Response theme={null}
{
  "results": [
    {
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3192,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "took_ms": 62
}
```

## 옵션

| 옵션 | 타입 | 기능 |
| - | - | - |
| `query` | string, 필수 | 최대 8,000자의 질문 |
| `top_k` | integer, 기본값 10 | 반환할 결과 수, 1-500 |
| `filter` | object | [메타데이터 필터](https://docs.conare.ai/ko/filters.md) |
| `user` | string | 이 [사용자](https://docs.conare.ai/ko/write.md#사용자)의 문서만 |
| `user_prefix` | string | `tenant-7:`처럼 이 값으로 시작하는 사용자만 |
| `answer` | boolean, 기본값 `false` | [답변 작성](#답변)도 함께 합니다 |
| `rerank` | boolean, 기본값 `true` | 상위 일치 항목을 리랭킹합니다. `false`가 더 빠릅니다 |
| `rerank_depth` | integer, 기본값 20 | 리랭킹할 상위 구절 수, 1-1,000 |
| `hops` | integer, 기본값 1 | `2`는 상위 결과에서 다시 검색합니다([투 홉](#투-홉)) |
| `retrievers` | array, 기본값 `["vector", "keyword"]` | `vector`(의미)와 `keyword` 중 1개 또는 2개 |
| `exclude_ids` | array | 제외할 문서 id, 최대 10,000개 |
| `max_results` | integer | 최대 1,000개의 결과를 [페이지](#페이지)로 탐색합니다. 맞춤 모델은 5,000개 |
| `cursor` | string | 이전 페이지의 `next_cursor` |

전체 스키마: [네임스페이스 쿼리](https://docs.conare.ai/ko/api-reference/query/query-a-namespace.md).

## 응답

| 필드 | 의미 |
| - | - |
| `results` | 가장 좋은 것부터, 문서당 하나 |
| `results[].id`, `metadata`, `user` | 해당 문서의 값 |
| `results[].text` | 답이 되는 구절을 가장 좋은 것부터 반환합니다. 가장 좋은 구절과 거의 비슷하게 일치하는 최대 2개이며, 각각 최대 약 3,000바이트입니다. 이어지지 않는 구절 사이에는 `…`만 있는 줄이 들어갑니다. 전체는 [문서를 가져오세요](https://docs.conare.ai/ko/documents.md) |
| `results[].score` | 높을수록 좋습니다. 같은 쿼리 안에서만 비교하세요 |
| `results[].reranked` | 리랭커가 점수를 매겼는지 여부. 리랭킹되지 않은 결과는 마지막에 옵니다 |
| `answer` | `answer: true`일 때의 답변 |
| `next_cursor` | `max_results` 사용 시 다음 페이지의 `cursor`. 마지막 페이지에서는 생략됩니다 |
| `took_ms` | 검색 시간(밀리초) |

## 답변

`"answer": true`는 상위 구절로 작성한 답변을 추가하며, 약 2초가 더 걸립니다.

```json Response theme={null}
{
  "answer": "Refunds are available for 30 days (source dated 2026-10-21). No further details on the refund process, conditions, or method were found in this search.",
  "results": [ ... ],
  "took_ms": 1546
}
```

* 찾은 구절을 바탕으로 언어 모델이 답변을 작성합니다. [개인정보 처리방침](https://conare.ai/privacy)을 참조하세요.
* 해당 모델을 사용할 수 없으면 `answer` 없이 결과만 받습니다.

## 투 홉

`"hops": 2`는 상위 결과에서 다시 검색합니다. 두 문서의 사실이 필요한 질문에 사용합니다.

```bash curl theme={null}
curl https://api.conare.ai/namespaces/films/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "where was the director of The Long Harbor born?", "hops": 2}'
```

* 약 0.3초가 추가됩니다. 사실을 연결해야 하는 질문에 사용하세요.
* `rerank: false`, `max_results`와 함께 쓰거나 맞춤 모델의 네임스페이스에서 쓰면 `400 invalid_request`를 반환합니다.

## 페이지

| 단계 | 보낼 값 |
| - | - |
| 첫 페이지 | `query`, `max_results`(한 번에 순위를 매길 개수), `top_k`(페이지 크기) |
| 다음 페이지 | `cursor`(마지막 `next_cursor`)와 `top_k`만 |
| 마지막 페이지 | `next_cursor`가 없습니다 |

커서는 15분 동안 유효합니다. SDK의 `queryPages()`는 모든 페이지를 읽습니다.

## 모든 네임스페이스 검색

`POST /query`

같은 요청을 최대 100개 네임스페이스에 걸쳐 실행하고 함께 리랭킹합니다. `prefix`는 이름이 해당 값으로 시작하는 네임스페이스로 제한합니다.

```bash curl theme={null}
curl https://api.conare.ai/query \
  -H "Authorization: Bearer $CONARE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"query": "how do refunds work?", "prefix": "acme-"}'
```

```json Response theme={null}
{
  "namespaces": ["acme-docs"],
  "results": [
    {
      "namespace": "acme-docs",
      "id": "refunds",
      "text": "Refunds are available for 30 days.",
      "score": 0.3471,
      "reranked": true,
      "metadata": { "team": "support" }
    }
  ],
  "skipped_namespaces": [],
  "took_ms": 64
}
```

| 옵션 또는 필드 | 여기서는 |
| - | - |
| `prefix` | 이름이 이 값으로 시작하는 네임스페이스만 |
| `rerank_depth` | 기본값 60, 1-1,000 |
| `exclude_ids` | `namespace/id` 형식으로 작성 |
| `results[].namespace` | 결과의 네임스페이스 |
| `namespaces`, `skipped_namespaces` | 검색된 네임스페이스와 처음 100개를 넘은 네임스페이스 |

`hops`도 여기서 작동합니다. 전체 스키마: [모든 네임스페이스 쿼리](https://docs.conare.ai/ko/api-reference/query/query-every-namespace.md).

## 저하된 결과

검색 일부가 실패해도 쿼리는 성공하며, `Conare-Degraded` 헤더가 건너뛴 부분을 알려 줍니다.

| 값 | 의미 |
| - | - |
| `rerank`, `rerank-partial` | 일부 또는 모든 결과가 리랭킹되지 않음(`reranked: false`) |
| `embed` | 키워드로만 검색함 |
| `keyword`, `keyword-terms` | 쿼리가 너무 길어 키워드 검색이 전체를 읽지 못함 |
| `embed-next` | 네임스페이스 일부를 검색할 수 없었음 |
| `cursor` | `next_cursor` 없음. 더 많은 페이지는 다시 검색하세요 |
| `embed-busy`, `embed-fallback` | 평소보다 느림. 결과에는 영향 없음 |
| `answer` | 답변 없이 결과만 |

아무것도 검색할 수 없으면 쿼리는 `503`을 반환합니다.


## Related topics

- [빠른 시작](https://docs.conare.ai/ko/quickstart.md)
- [콘솔](https://docs.conare.ai/ko/console.md)
- [문서 쓰기](https://docs.conare.ai/ko/write.md)
- [Query a namespace](https://docs.conare.ai/ko/api-reference/query/query-a-namespace.md)
- [MCP](https://docs.conare.ai/ko/mcp-server.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.