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](/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") 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 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") 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 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.chat({ messages: [{ role: 'user', content: 'What is the inciting incident of Pride and Prejudice?' }] }); console.log(chatResp); ``` ```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.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); } } ``` ```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" \ -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" }' ``` ```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" \ -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" }' ``` ```json Default response theme={null} { "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 ] } ] } ] } ``` ```text Streaming response theme={null} 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}` :::code-group ```bash title="cURL" curl --request POST \ --url https://{assistant_host}/chat/{assistant_name} \ --header 'Authorization: Bearer ' \ --header 'Content-Type: application/json' \ --data '{ "messages": [ { "role": "", "content": "" } ], "stream": true, "model": "gpt-4o", "filter": { "genre": { "$ne": "documentary" } }, "json_response": true, "include_highlights": true }' ``` ```json title="200" { "id": "", "finish_reason": "stop", "message": { "role": "", "content": "" }, "model": "", "citations": [ { "position": 123, "references": [ null ] } ], "usage": { "prompt_tokens": 123, "completion_tokens": 123, "total_tokens": 123 } } ``` ::: ## Authorizations - `Authorization` (header, string, required) — Bearer authentication header of the form `Bearer `. ## 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 - `filter` (body, object) — Optionally filter which documents can be retrieved using the following metadata fields. - `json_response` (body, boolean) — If true, the assistant will be instructed to return a JSON response. Cannot be used with streaming. - `include_highlights` (body, boolean) — If true, the assistant will be instructed to return highlights from the referenced documents that support its response. ## 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.