Chat with an assistant
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.
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"
}'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" \
-H "X-Pinecone-Api-Version: 2025-10" \
-d '{
"messages": [
{
"role": "user",
"content": "What is the inciting incident of Pride and Prejudice?"
}
],
"stream": true,
"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",
"percent_done": 0,
"signed_url": "https://storage.googleapis.com/...",
"error_message": null
},
"pages": [
1
]
}
]
}
]
}
data:{
"type":"message_start",
"id":"0000000000000000111b35de85e8a8f9",
"model":"gpt-4o-2024-05-13",
"role":"assistant"
}
data:
{
"type":"content_chunk",
"id":"0000000000000000111b35de85e8a8f9",
"model":"gpt-4o-2024-05-13",
"delta":
{
"content":"The"
}
}
...
data:
{
"type":"citation",
"id":"0000000000000000111b35de85e8a8f9",
"model":"gpt-4o-2024-05-13",
"citation":
{
"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",
"percent_done":0.0,
"signed_url":"https://storage.googleapis.com/...",
"error_message":null
},
"pages":[1]
}
]
}
}
data:
{
"type":"message_end",
"id":"0000000000000000111b35de85e8a8f9",
"model":"gpt-4o-2024-05-13",
"finish_reason":"stop",
"usage":
{
"prompt_tokens":9736,
"completion_tokens":102,
"total_tokens":9838
}
}POST /chat/{assistant_name}
Authorizations
Section titled “Authorizations”Api-KeystringrequiredPinecone API Key
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Path Parameters
Section titled “Path Parameters”assistant_namestringrequiredThe name of the assistant to be described.
The desired configuration to chat an assistant.
messagesobject[]requiredShow child attributes
role?stringRole of the message such as 'user' or 'assistant'
content?stringContent of the message
stream?booleanIf false, the assistant will return a single JSON response. If true, the assistant will return a stream of responses.
model?stringThe large language model to use for answer generation
temperature?numberControls 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?objectOptionally filter which documents can be retrieved using the following metadata fields.
json_response?booleanIf true, the assistant will be instructed to return a JSON response. Cannot be used with streaming.
include_highlights?booleanIf true, the assistant will be instructed to return highlights from the referenced documents that support its response.
context_options?objectControls the context snippets sent to the LLM.
Show child attributes
top_k?integerThe maximum number of context snippets to use. Default is 16. Maximum is 64.
Example: 20
snippet_size?integerThe maximum context snippet size. Default is 2048 tokens. Minimum is 512 tokens. Maximum is 8192 tokens.
Example: 4096
multimodal?booleanWhether or not to send image-related context snippets to the LLM. If false, only text context snippets are sent.
include_binary_content?booleanIf image-related context snippets are sent to the LLM, this field determines whether or not they should include base64 image data. If false, only the image caption is sent. Only available when multimodal=true.
Response
Section titled “Response”200 — Search request successful.
Describes the response format of a chat request from the citation API.
id?stringfinish_reason?stringmessage?objectDescribes the format of a message in a chat.
Show child attributes
role?stringRole of the message such as 'user' or 'assistant'
content?stringContent of the message
model?stringcitations?object[]Show child attributes
position?integerThe index position of the citation in the complete text response.
references?object[]Show child attributes
file?objectThe response format for a successful file upload request.
Show child attributes
namestringrequiredidstringrequiredmetadata?object | nullcreated_on?stringupdated_on?stringstatus?stringThe current state of the uploaded file. Possible values: - Processing: File is being processed (parsed, chunked, embedded) - Available: Processing completed successfully; file is ready for use - Deleting: Deletion has been initiated but not yet completed - ProcessingFailed: Processing failed with an error Note: Once a file is deleted, the API returns 404 Not Found instead of a file object.
percent_done?number | nullThe percentage of the file that has been processed
signed_url?string | nullExample: https://storage.googleapis.com/bucket/file.pdf?...
A signed URL that provides temporary, read-only access to the underlying file. Anyone with the link can access the file, so treat it as sensitive data. Expires after a short time.
error_message?string | nullA message describing any error during file processing. Provided only if an error occurs.
multimodal?booleanIndicates whether the file was processed as multimodal.
pages?integer[]highlight?object | nullRepresents a portion of a referenced document that directly supports or is relevant to the response.
Show child attributes
typestringrequiredThe type of the highlight. Currently it is always text.
contentstringrequiredusage?objectDescribes the usage of a chat completion.
Show child attributes
prompt_tokens?integercompletion_tokens?integertotal_tokens?integer