Skip to main content
POST
/
chat
/
{assistant_name}
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the inciting incident of Pride and Prejudice?"
    }
  ],
  "stream": false,
  "model": "gpt-4o"
}'
{
  "finish_reason": "stop",
  "message": {
    "role": "assistant",
    "content": "The inciting incident of \"Pride and Prejudice\" occurs when Mrs. Bennet informs Mr. Bennet that Netherfield Park has been let at last, and she is eager to share the news about the new tenant, Mr. Bingley, who is wealthy and single. This sets the stage for the subsequent events of the story, including the introduction of Mr. Bingley and Mr. Darcy to the Bennet family and the ensuing romantic entanglements."
  },
  "id": "00000000000000004ac3add5961aa757",
  "model": "gpt-4o-2024-05-13",
  "usage": {
    "prompt_tokens": 9736,
    "completion_tokens": 105,
    "total_tokens": 9841
  },
  "citations": [
    {
      "position": 406,
      "references": [
        {
          "file": {
            "status": "Available",
            "id": "ae79e447-b89e-4994-994b-3232ca52a654",
            "name": "Pride-and-Prejudice.pdf",
            "size": 2973077,
            "metadata": null,
            "updated_on": "2024-06-14T15:01:57.385425746Z",
            "created_on": "2024-06-14T15:01:02.910452398Z",
            "signed_url": "https://storage.googleapis.com/..."
          },
          "pages": [
            1
          ]
        }
      ]
    }
  ]
}

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the inciting incident of Pride and Prejudice?"
    }
  ],
  "stream": false,
  "model": "gpt-4o"
}'
{
  "finish_reason": "stop",
  "message": {
    "role": "assistant",
    "content": "The inciting incident of \"Pride and Prejudice\" occurs when Mrs. Bennet informs Mr. Bennet that Netherfield Park has been let at last, and she is eager to share the news about the new tenant, Mr. Bingley, who is wealthy and single. This sets the stage for the subsequent events of the story, including the introduction of Mr. Bingley and Mr. Darcy to the Bennet family and the ensuing romantic entanglements."
  },
  "id": "00000000000000004ac3add5961aa757",
  "model": "gpt-4o-2024-05-13",
  "usage": {
    "prompt_tokens": 9736,
    "completion_tokens": 105,
    "total_tokens": 9841
  },
  "citations": [
    {
      "position": 406,
      "references": [
        {
          "file": {
            "status": "Available",
            "id": "ae79e447-b89e-4994-994b-3232ca52a654",
            "name": "Pride-and-Prejudice.pdf",
            "size": 2973077,
            "metadata": null,
            "updated_on": "2024-06-14T15:01:57.385425746Z",
            "created_on": "2024-06-14T15:01:02.910452398Z",
            "signed_url": "https://storage.googleapis.com/..."
          },
          "pages": [
            1
          ]
        }
      ]
    }
  ]
}

Authorizations

Api-Key
string
header
required

Pinecone API Key

Headers

X-Pinecone-Api-Version
string
default:2026-04
required

Required date-based version header

Path Parameters

assistant_name
string
required

The name of the assistant to be described.

Body

application/json

The desired configuration to chat with an assistant.

Represents a request to chat with an assistant.

messages
object[]
required

The list of messages sent to the assistant, used for context retrieval and generating response with the LLM.

stream
boolean
default:false

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

model
string
default:gpt-4o

The large language model used to generate responses.

temperature
number<float>
default:0

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.

filter
object

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

Example:
{ "genre": { "$ne": "documentary" } }
json_response
boolean
default:false

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

include_highlights
boolean
default:false

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

context_options
object

Controls the context snippets sent to the LLM.

Response

Search request successful.

Describes the response format of a chat request.

id
string

A unique identifier for this chat response.

finish_reason
string

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.

message
object

Describes the format of a message in a chat.

model
string

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

citations
object[]

Citations supporting the information in the response.

usage
object

Describes the token usage associated with interactions with an assistant.

context_snippet_count
integer

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).

content_filter_results
object

Content filter results provided by the LLM, describing safety-related classifications applied to the content. The structure may vary depending on the model and the content being filtered. The spec field identifies the provider, and determines the structure of results.