---
title: "Search a namespace"
method: POST
path: "/v1/namespace/{namespaceId}/search"
tags: ["Search"]
---

# Search a namespace

`POST /v1/namespace/{namespaceId}/search`

Search a namespace for a query.

## Path parameters

- `namespaceId` string, required — The id of the namespace (prefixed with ns_)

## Headers

- `x-tenant-id` string — Optional tenant id to use for the request. If not provided, the namespace will be used directly. Must be alphanumeric and up to 64 characters.

## Request body

- object
  - `query` string, required — The query to search for.
  - `topK` number — The number of results to fetch from the vector store. Defaults to `10`.
  - `rerank` boolean — Whether to rerank the results. Defaults to `true`.
  - `rerankLimit` number — The number of results to return after reranking. Defaults to `topK`.
  - `rerankModel` 'cohere:rerank-v4.0-pro' | 'cohere:rerank-v4.0-fast' | 'cohere:rerank-v3.5' | 'cohere:rerank-english-v3.0' | 'cohere:rerank-multilingual-v3.0' | 'zeroentropy:zerank-2' | 'zeroentropy:zerank-1' | 'zeroentropy:zerank-1-small' — The reranking model to use.
  - `filter` object — A filter to apply to the results.
  - `minScore` number — The minimum score to return.
  - `includeRelationships` boolean — Whether to include relationships in the results. Defaults to `false`.
  - `includeMetadata` boolean — Whether to include metadata in the results. Defaults to `true`.
  - `keywordFilter` string
  - `mode` 'semantic' | 'keyword'

## Response `200`

The retrieved namespace

- object
  - `success` true, required
  - `data` object[], required
    - `id` string, required
    - `score` number, required
    - `text` string
    - `relationships` object
    - `metadata` object

## Other responses

- `400` — The server cannot or will not process the request due to something that is perceived to be a client error (e.g., malformed request syntax, invalid request message framing, or deceptive request routing).
- `401` — Although the HTTP standard specifies "unauthorized", semantically this response means "unauthenticated". That is, the client must authenticate itself to get the requested response.
- `403` — The client does not have access rights to the content; that is, it is unauthorized, so the server is refusing to give the requested resource. Unlike 401 Unauthorized, the client's identity is known to the server.
- `404` — The server cannot find the requested resource.
- `409` — This response is sent when a request conflicts with the current state of the server.
- `410` — This response is sent when the requested content has been permanently deleted from server, with no forwarding address.
- `422` — The request was well-formed but was unable to be followed due to semantic errors.
- `429` — The user has sent too many requests in a given amount of time ("rate limiting")
- `500` — The server has encountered a situation it does not know how to handle.

---

[API](https://skmtc.net/agentset/apis/agentsetapi.md) · [All operations](https://skmtc.net/agentset/apis/agentsetapi/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/agentset/agentsetapi/versions/cc6ac802092e/schema)