It is useful if you need inline citations or OpenAI-compatible responses, but has limited functionality compared to the standard chat interface.

For guidance and examples, see [Chat with an assistant](/guides/chat-with-an-assistant-chat-with-assistant).

```python Python | Default theme={null}
# 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")

# Get your assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant", 
)

# Chat with the assistant.
chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
response = assistant.chat_completions(messages=chat_context)
```

```python Python | Streaming theme={null}
# 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")

# Get your assistant.
assistant = pc.assistant.Assistant(
    assistant_name="example-assistant" 
)

# Streaming chat with the Assistant.
chat_context = [Message(role="user", content="What is the maximum height of a red pine?")]
chunks = assistant.chat_completions(messages=[chat_context], stream=True, model="gpt-4o")

for chunk in chunks:
    if chunk:
        print(chunk)
```

```javascript JavaScript | Default theme={null}
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.chatCompletion({
      messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }]
    });
console.log(JSON.stringify(chatResp.choices[0].message, null, 2));
```

```javascript JavaScript | Streaming theme={null}
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.chatCompletionStream({
      messages: [{ role: 'user', content: 'What is the maximum height of a red pine?' }]
    });

for await (const response of chatResp) {
    if (response) {
        console.log(response);
    }
}
```

```bash curl | Default theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
  -H "Api-Key: $PINECONE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "user",
      "content": "What is the maximum height of a red pine?"
    }
  ]
}'
```

```bash curl | Streaming theme={null}
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"

curl "https://prod-1-data.ke.pinecone.io/assistant/chat/$ASSISTANT_NAME/chat/completions" \
  -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 maximum height of a red pine?"
    }
  ],
  "stream": true
}'
```

```JSON Default response theme={null}
{"chat_completion":
  {
    "id":"chatcmpl-9OtJCcR0SJQdgbCDc9JfRZy8g7VJR",
    "choices":[
      {
        "finish_reason":"stop",
        "index":0,
        "message":{
          "role":"assistant",
          "content":"The maximum height of a red pine (Pinus resinosa) is up to 25 meters."
        }
      }
    ],
    "model":"my_assistant"
  }
}
```

```text Streaming response theme={null}
{
  'id': '000000000000000009de65aa87adbcf0', 
  'choices': [
      {
      'index': 0, 
      'delta': 
        {
        'role': 'assistant', 
        'content': 'The'
        }, 
      'finish_reason': None
      }
    ], 
  'model': 'gpt-4o-2024-05-13'
}

...

{
  'id': '00000000000000007a927260910f5839',
  'choices': [
      {
      'index': 0,
      'delta':
        {
          'role': '', 
          'content': 'The'
        }, 
      'finish_reason': None
      }
    ], 
  'model': 'gpt-4o-2024-05-13'
}

...

{
  'id': '00000000000000007a927260910f5839', 
  'choices': [
    {
      'index': 0, 
      'delta': 
        {
        'role': None, 
        'content': None
        }, 
      'finish_reason': 'stop'
      }
    ], 
  'model': 'gpt-4o-2024-05-13'
}
```

`POST /chat/{assistant_name}/chat/completions`

:::code-group
```bash title="cURL"
curl --request POST \
  --url https://{assistant_host}/chat/{assistant_name}/chat/completions \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{
  "messages": [
    {
      "role": "<string>",
      "content": "<string>"
    }
  ],
  "stream": true,
  "model": "gpt-4o",
  "temperature": 123,
  "filter": {
    "genre": {
      "$ne": "documentary"
    }
  }
}'
```

```json title="200"
{
  "id": "<string>",
  "choices": [
    {
      "finish_reason": "stop",
      "index": 123,
      "message": {
        "role": "<string>",
        "content": "<string>"
      }
    }
  ],
  "model": "<string>",
  "usage": {
    "prompt_tokens": 123,
    "completion_tokens": 123,
    "total_tokens": 123
  }
}
```
:::

## Authorizations

- `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer <token>`.

## Path Parameters

- `assistant_name` (path, string, required) — The name of the assistant to be described.

## Body

- `messages` (body, object\[], required)
- `stream` (body, boolean) — If false, the assistant will return a single JSON response. If true, the assistant will return a stream of responses.
- `model` (body, string) — The large language model to use for answer generation
- `temperature` (body, number) — 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` (body, object) — Optionally filter which documents can be retrieved using the following metadata fields.

## Response

- `200` — Search request successful.
- `400` — Bad request. The request body included invalid request parameters.
- `401` — Unauthorized. Possible causes: Invalid API key.
- `404` — Assistant not found.
- `500` — Internal server error.

## Related pages

- [Account management](./account-management-index.md)
- [Admin](./admin-2-index.md)
- [Admin](./admin-index.md)
- [APIs](./apis-index.md)
- [Architecture](./architecture-index.md)
- [Assistants](./assistants-index.md)
- [Bring Your Own Cloud](./bring-your-own-cloud-index.md)
- [Build an assistant](./build-an-assistant-index.md)
- [Build an integration](./build-an-integration-index.md)
- [Changelog](./changelog-index.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.