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.
# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant
from pinecone import Pinecone
from pinecone_plugins.assistant.models.chat import Message
pc = Pinecone(api_key="YOUR_API_KEY")
assistant = pc.assistant.Assistant(assistant_name="example-assistant")
msg = Message(role="user", content="What is the inciting incident of Pride and Prejudice?")
resp = assistant.chat(messages=[msg])
print(resp)# To use the Python SDK, install the plugin:
# pip install --upgrade pinecone pinecone-plugin-assistant
from pinecone import Pinecone
from pinecone_plugins.assistant.models.chat import Message
pc = Pinecone(api_key="YOUR_API_KEY")
assistant = pc.assistant.Assistant(assistant_name="example-assistant")
msg = Message(role="user", content="What is the inciting incident of Pride and Prejudice?")
chunks = assistant.chat(messages=[msg], stream=True)
for chunk in chunks:
if chunk:
print(chunk)import { Pinecone } from '@pinecone-database/pinecone'
const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
const assistantName = 'example-assistant';
const assistant = pc.Assistant(assistantName);
const chatResp = await assistant.chat({
messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }]
});
console.log(chatResp);import { Pinecone } from '@pinecone-database/pinecone'
const pc = new Pinecone({ apiKey: 'YOUR_API_KEY' });
const assistantName = 'example-assistant';
const assistant = pc.Assistant(assistantName);
const chatResp = await assistant.chatStream({
messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }]
});
for await (const response of chatResp) {
if (response) {
console.log(response);
}
}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-01" \
-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
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?enum<string>The large language model to use for answer generation
Available options: gpt-4o, claude-3-5-sonnet
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.
Response
Section titled “Response”200 — Search request successful.
The ChatModel describes the response format of a chat request from the citation api.
id?stringfinish_reason?enum<string>Available options: stop, length, content_filter, function_call
message?objectThe MessageModel describes 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?objectAssistantFileModel is the response format to a successful file upload request.
Show child attributes
namestringrequiredidstringrequiredmetadata?object | nullcreated_on?stringupdated_on?stringstatus?enum<string>Available options: Processing, Available, Deleting, ProcessingFailed
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.
pages?integer[]highlight?objectThe HighlightModel represents 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?objectThe UsageModel describes the usage of a chat completion.
Show child attributes
prompt_tokens?integercompletion_tokens?integertotal_tokens?integer