Skip to main content
Pinecone Docs
current

Search documentation

Type to search this documentation.

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.

Python
# 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)
Python
# 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)
JavaScript
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);
JavaScript
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);
    }
}
curl
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"
}'
curl
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"
}'
Default
{
  "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
          ]
        }
      ]
    }
  ]
}
Streaming
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}

Api-Keystringrequired

Pinecone API Key

Typestring
assistant_namestringrequired

The name of the assistant to be described.

Typestring

The desired configuration to chat an assistant.

messagesobject[]required
Show child attributes
role?string

Role of the message such as 'user' or 'assistant'

Typestring
content?string

Content of the message

Typestring
stream?boolean

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

Typeboolean
Defaultfalse
model?enum<string>

The large language model to use for answer generation

Available options: gpt-4o, claude-3-5-sonnet

Typeenum<string>
Defaultgpt-4o
filter?object

Optionally filter which documents can be retrieved using the following metadata fields.

Typeobject
json_response?boolean

If true, the assistant will be instructed to return a JSON response. Cannot be used with streaming.

Typeboolean
Defaultfalse
include_highlights?boolean

If true, the assistant will be instructed to return highlights from the referenced documents that support its response.

Typeboolean
Defaultfalse

200 — Search request successful.

The ChatModel describes the response format of a chat request from the citation api.

id?string
finish_reason?enum<string>

Available options: stop, length, content_filter, function_call

Typeenum<string>
message?object

The MessageModel describes the format of a message in a chat.

Typeobject
Show child attributes
role?string

Role of the message such as 'user' or 'assistant'

Typestring
content?string

Content of the message

Typestring
model?string
citations?object[]
Show child attributes
position?integer

The index position of the citation in the complete text response.

Typeinteger
references?object[]
Show child attributes
file?object

AssistantFileModel is the response format to a successful file upload request.

Typeobject
Show child attributes
namestringrequired
idstringrequired
metadata?object | null
created_on?string
updated_on?string
status?enum<string>

Available options: Processing, Available, Deleting, ProcessingFailed

Typeenum<string>
percent_done?number | null

The percentage of the file that has been processed

Typenumber | null
signed_url?string | null

Example: https://storage.googleapis.com/bucket/file.pdf?...

Typestring | null

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 | null

A message describing any error during file processing, provided only if an error occurs.

Typestring | null
pages?integer[]
highlight?object

The HighlightModel represents a portion of a referenced document that directly supports or is relevant to the response.

Typeobject
Show child attributes
typestringrequired

The type of the highlight. Currently it is always text.

Typestring
contentstringrequired
usage?object

The UsageModel describes the usage of a chat completion.

Typeobject
Show child attributes
prompt_tokens?integer
completion_tokens?integer
total_tokens?integer
Suggest an edit

Propose a replacement for this page. The site team reviews it before applying any changes.

Export
Documentation menu