Sign in

v1

latestOpenAPI 3.0.3Apache 2.02026-07-1372170520.1 KB
Manage Assistants

Chat with an assistant

Chat with an assistant and get back citations in structured form.

This is the recommended way to chat with an assistant, as it offers more functionality and control over the assistant's responses and references than the OpenAI-compatible chat interface.

For guidance and examples, see Chat with an assistant.

post/chat/{assistant_name}

Path parameters

assistant_namestring required

The name of the assistant to be described.

Headers

X-Pinecone-Api-Versionstring required

Required date-based version header

Request body

streamboolean

If false, the assistant returns a single JSON response. If true, the assistant returns a stream of responses.

modelstring

The large language model used to generate responses.

temperaturenumber float

Controls the randomness of the model's output: lower values make responses more deterministic, while higher values increase creativity and variability. If the model does not support a temperature parameter, the parameter will be ignored.

filterobject

Optional metadata-based filter to restrict which documents are retrieved for the assistant's response context.

json_responseboolean

If true, instructs the assistant to return a JSON-formatted response. Cannot be used together with streaming mode.

include_highlightsboolean

If true, instructs the assistant to include highlights from the referenced documents that support its response.

Example request

{
  "filter": {
    "genre": {
      "$ne": "documentary"
    }
  },
  "context_options": {
    "top_k": 20,
    "snippet_size": 4096
  }
}

Response

Search request successful.

idstring

A unique identifier for this chat response.

finish_reasonstring

Indicates why the chat response generation stopped. This signals the end of the response.

  • stop: The model finished generating the response.

  • length: Generation was cut off because the maximum number of tokens allowed was reached.

  • content_filter: Generation stopped because content was blocked by content filtering rules. (for example, content that contains hate speech or violent material).

  • tool_calls: Generation stopped because a tool call was triggered.

modelstring

The name or identifier of the model used to generate this chat response.

context_snippet_countinteger

The number of context snippets provided to the model to generate the response. This indicates how much retrieved information was available for the generation, allowing for logic to be applied if no context was found (count is 0).

Example response

{
  "citations": [
    {
      "references": [
        {
          "file": {
            "size": 1048576,
            "metadata": {
              "created_by": "Jane Doe",
              "published": "2025-10-01",
              "tags": [
                "report",
                "Q4",
                "analytics"
              ]
            },
            "created_on": "2025-10-01T12:30:00Z",
            "updated_on": "2025-10-01T12:45:00Z",
            "signed_url": "https://storage.googleapis.com/bucket/file.pdf?..."
          }
        }
      ]
    }
  ]
}