Chat with an assistant

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

response = pc.assistants.chat(
    assistant_name="example-assistant",
    messages=[{"role": "user", "content": "What is the inciting incident of Pride and Prejudice?"}],
    model="gpt-4o",
)
print(response.message.content)

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

stream = pc.assistants.chat(
    assistant_name="example-assistant",
    messages=[{"role": "user", "content": "What is the inciting incident of Pride and Prejudice?"}],
    model="gpt-4o",
    stream=True,
)
for fragment in stream.text():
    print(fragment, end="", flush=True)

// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';

// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();

const assistant = pc.assistant({ name: 'example-assistant' });
const response = await assistant.chat({
  messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }],
  model: 'gpt-4o',
});
console.log(response.message?.content);

// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';

// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();

const assistant = pc.assistant({ name: 'example-assistant' });
const stream = await assistant.chatStream({
  messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }],
  model: 'gpt-4o',
});
for await (const chunk of stream) {
  if (chunk.type === 'content_chunk') {
    process.stdout.write(chunk.delta.content);
  }
}

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: 2026-07" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the inciting incident of Pride and Prejudice?"
    }
  ],
  "stream": true,
  "model": "gpt-4o"
}'

{
  "id": "<string>",
  "finish_reason": "<string>",
  "message": {
    "role": "<string>",
    "content": "<string>"
  },
  "model": "<string>",
  "citations": [
    {
      "position": 123,
      "references": [
        {
          "file": {
            "name": "<string>",
            "id": "<string>",
            "size": 1048576,
            "metadata": {
              "created_by": "Jane Doe",
              "published": "2025-10-01T00:00:00.000Z",
              "tags": [
                "report",
                "Q4",
                "analytics"
              ]
            },
            "created_on": "2025-10-01T12:30:00.000Z",
            "updated_on": "2025-10-01T12:45:00.000Z",
            "status": "<string>",
            "signed_url": "https://storage.googleapis.com/bucket/file.pdf?...",
            "multimodal": true
          },
          "pages": [
            123
          ],
          "highlight": {
            "type": "<string>",
            "content": "<string>"
          }
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  },
  "context_snippet_count": 123,
  "content_filter_results": {
    "spec": "<string>",
    "results": "<unknown>"
  }
}

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Uploaded file can only currently be either a pdf or txt file"
  },
  "status": 400
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assistant \"example-assistant\" not found."
  },
  "status": 404
}

{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

POST

chat

{assistant_name}

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

response = pc.assistants.chat(
    assistant_name="example-assistant",
    messages=[{"role": "user", "content": "What is the inciting incident of Pride and Prejudice?"}],
    model="gpt-4o",
)
print(response.message.content)

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

stream = pc.assistants.chat(
    assistant_name="example-assistant",
    messages=[{"role": "user", "content": "What is the inciting incident of Pride and Prejudice?"}],
    model="gpt-4o",
    stream=True,
)
for fragment in stream.text():
    print(fragment, end="", flush=True)

// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';

// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();

const assistant = pc.assistant({ name: 'example-assistant' });
const response = await assistant.chat({
  messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }],
  model: 'gpt-4o',
});
console.log(response.message?.content);

// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';

// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();

const assistant = pc.assistant({ name: 'example-assistant' });
const stream = await assistant.chatStream({
  messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }],
  model: 'gpt-4o',
});
for await (const chunk of stream) {
  if (chunk.type === 'content_chunk') {
    process.stdout.write(chunk.delta.content);
  }
}

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: 2026-07" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the inciting incident of Pride and Prejudice?"
    }
  ],
  "stream": true,
  "model": "gpt-4o"
}'

{
  "id": "<string>",
  "finish_reason": "<string>",
  "message": {
    "role": "<string>",
    "content": "<string>"
  },
  "model": "<string>",
  "citations": [
    {
      "position": 123,
      "references": [
        {
          "file": {
            "name": "<string>",
            "id": "<string>",
            "size": 1048576,
            "metadata": {
              "created_by": "Jane Doe",
              "published": "2025-10-01T00:00:00.000Z",
              "tags": [
                "report",
                "Q4",
                "analytics"
              ]
            },
            "created_on": "2025-10-01T12:30:00.000Z",
            "updated_on": "2025-10-01T12:45:00.000Z",
            "status": "<string>",
            "signed_url": "https://storage.googleapis.com/bucket/file.pdf?...",
            "multimodal": true
          },
          "pages": [
            123
          ],
          "highlight": {
            "type": "<string>",
            "content": "<string>"
          }
        }
      ]
    }
  ],
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  },
  "context_snippet_count": 123,
  "content_filter_results": {
    "spec": "<string>",
    "results": "<unknown>"
  }
}

{
  "error": {
    "code": "INVALID_ARGUMENT",
    "message": "Uploaded file can only currently be either a pdf or txt file"
  },
  "status": 400
}

{
  "error": {
    "code": "UNAUTHENTICATED",
    "message": "Invalid API key."
  },
  "status": 401
}

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Assistant \"example-assistant\" not found."
  },
  "status": 404
}

{
  "error": {
    "code": "UNKNOWN",
    "message": "Internal server error"
  },
  "status": 500
}

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

response = pc.assistants.chat(
    assistant_name="example-assistant",
    messages=[{"role": "user", "content": "What is the inciting incident of Pride and Prejudice?"}],
    model="gpt-4o",
)
print(response.message.content)

# pip install --upgrade pinecone
import os
from pinecone import Pinecone

pc = Pinecone(api_key=os.environ["PINECONE_API_KEY"])

stream = pc.assistants.chat(
    assistant_name="example-assistant",
    messages=[{"role": "user", "content": "What is the inciting incident of Pride and Prejudice?"}],
    model="gpt-4o",
    stream=True,
)
for fragment in stream.text():
    print(fragment, end="", flush=True)

// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';

// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();

const assistant = pc.assistant({ name: 'example-assistant' });
const response = await assistant.chat({
  messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }],
  model: 'gpt-4o',
});
console.log(response.message?.content);

// npm install @pinecone-database/pinecone
import { Pinecone } from '@pinecone-database/pinecone';

// Reads PINECONE_API_KEY from the environment
const pc = new Pinecone();

const assistant = pc.assistant({ name: 'example-assistant' });
const stream = await assistant.chatStream({
  messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }],
  model: 'gpt-4o',
});
for await (const chunk of stream) {
  if (chunk.type === 'content_chunk') {
    process.stdout.write(chunk.delta.content);
  }
}

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: 2026-07" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the inciting incident of Pride and Prejudice?"
    }
  ],
  "stream": true,
  "model": "gpt-4o"
}'

Authorizations

Api-Key

string

header

required

Pinecone API Key

Headers

X-Pinecone-Api-Version

string

default:2026-07

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.

Show child attributes

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.

Show child attributes

Response

Search request successful.

Describes the response format of a chat request.

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.

Show child attributes

model

string

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

citations

object[]

Citations supporting the information in the response.

Show child attributes

usage

object

Describes the token usage associated with interactions with an assistant.

Show child attributes

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.

Show child attributes

APIs

Assistants

Files

Operations

Chat

Evaluation

Context snippets

Admin

Architecture

Authorizations

Headers

Path Parameters

Body

Response