POST /records/namespaces/{namespace}/search

Search a namespace with a query text, query vector, or record ID and return the most similar records, along with their similarity scores. Optionally, rerank the initial results based on their relevance to the query.

Searching with text is supported only for indexes with integrated embedding. Searching with a query vector or record ID is supported for all indexes.

For guidance and examples, see Search.

Servers

https://{index_host}

Path parameters

Name	Type	Required	Description
`namespace`	String	Yes	The namespace to search.

Request headers

Name Type Required Description

Name	Type	Required	Description
`Content-Type`	String	Yes	The media type of the request body. Default value: "application/json"
`X-Pinecone-Api-Version`	String	Yes	Required date-based version header Default value: "2025-10"

Content-Type

String

Yes

The media type of the request body.

Default value: "application/json"

X-Pinecone-Api-Version

String

Yes

Required date-based version header

Default value: "2025-10"

Request body fields

Name	Type	Required	Description
`query`	Object	Yes	.
`query.top_k`	Integer	Yes	The number of similar records to return.
`query.id`	String	No	The unique ID of the vector to be used as a query vector.
`query.inputs`	Object	No
`query.vector`	Object	No
`query.vector.values[]`	Array	No	This is the vector data included in the request.
`query.vector.sparse_indices[]`	Array	No	The sparse embedding indices.
`query.vector.sparse_values[]`	Array	No	The sparse embedding values.
`query.match_terms`	Object	No	Specifies which terms must be present in the text of each search hit based on the specified strategy. The match is performed against the text field specified in the integrated index `field_map` configuration. Terms are normalized and tokenized into single tokens before matching, and order does not matter. Example: `"match_terms": {"terms": ["animal", "CHARACTER", "donald Duck"], "strategy": "all"}` will tokenize to `["animal", "character", "donald", "duck"]`, and would match `"Donald F. Duck is a funny animal character"` but would not match `"A duck is a funny animal"`. Match terms filtering is supported only for sparse indexes with integrated embedding configured to use the pinecone-sparse-english-v0 model.
`query.match_terms.strategy`	String	No	The strategy for matching terms in the text. Currently, only `all` is supported, which means all specified terms must be present.
`query.match_terms.terms[]`	Array	No	A list of terms that must be present in the text of each search hit based on the specified strategy.
`query.filter`	Object	No	The filter to apply. You can use vector metadata to limit your search. See Understanding metadata.
`rerank`	Object	No	Parameters for reranking the initial search results.
`rerank.query`	String	No	The query to rerank documents against. If a specific rerank query is specified, it overwrites the query input that was provided at the top level.
`rerank.rank_fields[]`	Array	Yes	The field(s) to consider for reranking. If not provided, the default is `["text"]`. The number of fields supported is model-specific.
`rerank.parameters`	Object	No	Additional model-specific parameters. Refer to the model guide for available model parameters.
`rerank.model`	String	Yes	The name of the reranking model to use.
`rerank.top_n`	Integer	No	The number of top results to return after reranking. Defaults to top_k.
`fields[]`	Array	No	The fields to return in the search results. If not specified, the response will include all fields.

How to start integrating

Add HTTP Task to your workflow definition.
Search for the API you want to integrate with and click on the name.
- This loads the API reference documentation and prepares the Http request settings.
Click Test request to test run your request to the API and see the API's response.