Pinecone Assistant Files & Chat
Ask questions of your own PDFs, docs and notes through a Pinecone Assistant and get answers with page-level citations. Upload or replace files, watch their processing status, pull raw context snippets for your own prompts, or call the OpenAI-compatible chat completions endpoint.
Connect this API to an AI agent Browse all specs
What you can do with Pinecone Assistant Files & Chat via MCP
Every endpoint below becomes a governed tool your AI agent (Claude, ChatGPT, or a customer-facing VX agent) can call — with scoped permissions, sandbox testing, and audit logs.
| Method | Path | Operation | Description |
|---|---|---|---|
| GET | /files/{assistant_name} |
listFiles | List the files uploaded to an assistant, with their processing status |
| POST | /files/{assistant_name} |
uploadFile | Upload a new file to the assistant; processing runs in the background |
| GET | /files/{assistant_name}/{assistant_file_id} |
describeFile | Get one file's status, metadata and a temporary download link |
| PUT | /files/{assistant_name}/{assistant_file_id} |
upsertFile | Create or replace a file under a file id you choose |
| GET | /operations/{assistant_name} |
listOperations | List recent file upload and replace operations and their progress |
| GET | /operations/{assistant_name}/{operation_id} |
describeOperation | Check whether one upload or replace operation has finished |
| POST | /chat/{assistant_name} |
chatWithAssistant | Ask the assistant a question and get an answer with citations to your files |
| POST | /chat/{assistant_name}/chat/completions |
chatCompletions | Chat with the assistant through an OpenAI-compatible completions call |
| POST | /chat/{assistant_name}/context |
retrieveContext | Fetch the most relevant snippets from your files for a query, without an answer |
Authentication
ApiKeyAuth
API key — sent as the Api-Key header
Pinecone API key, sent in the Api-Key header.
How to get a credential
- Sign in to the Pinecone console (https://app.pinecone.io).
- Pick the project that holds your assistant.
- Open API keys and click Create API key; give it a name and copy the value (it is shown once).
- Open Assistant, create an assistant if you have none, and note its name and region.
Permissions used
| Key permission | Operations |
|---|---|
| All (or Assistant ReadWrite) | listFiles, describeFile, listOperations, describeOperation, chatWithAssistant, chatCompletions, retrieveContext |
| All (or Assistant ReadWrite) | uploadFile, upsertFile |
Common errors
| Status | Meaning | Fix |
|---|---|---|
| 401 | Key missing or invalid | Paste the full key again; it belongs to one project. |
| 403 | Key lacks permission or the plan limit is reached | Use a key with Assistant access; check plan limits. |
| 404 | Assistant name or host is wrong | Use the exact assistant name and the host from Describe an assistant (US vs EU). |
| 400 | Bad body or version header | Keep X-Pinecone-Api-Version at 2026-07; check file type and message format. |
| 429 | Rate or token limit hit | Back off and retry later. |
Store the key as a VX Agents credential of type API key; it is sent as the Api-Key header on every call.
Usage guide
Setup
- Add your Pinecone API key as a VX Agents credential (API key, sent as
Api-Key). - Set the server variable
assistant_hostto your assistant's data-plane host, shown ashostwhen you describe the assistant in the Pinecone console or API. US assistants useprod-1-data.ke.pinecone.io(the default), EU assistants useprod-eu-data.ke.pinecone.io. - Pin
assistant_nameso the agent never guesses it. X-Pinecone-Api-Versionis fixed at2026-07; leave it as is.
Answer questions from your documents
listFilesto see which files the assistant holds and whether each isAvailable(stillProcessingfiles are not searched yet).chatWithAssistantwithmessages([{"role": "user", "content": "..."}]). Keepstreamfalse. Return the answer together with itscitations(file name and pages) so the user can check the source.- For a follow-up, send the earlier user and assistant messages again in
messages; the API keeps no chat history. - Use
filterto limit the search to files with matching metadata (for example{"department": "legal"}). - To build your own prompt instead of getting an answer, call
retrieveContextwithquery(ormessages) and optionaltop_k; it returns ranked snippets with file references. chatCompletionstakes and returns the OpenAI chat format, without structured citations; use it only when that shape is needed.
Add or replace files
- Ask the user to confirm before uploading or replacing a file: it changes what every user of the assistant sees in answers.
uploadFile(multipartfile, optionalmetadataJSON) for a new file, orupsertFilewith your ownassistant_file_idto replace one in place.- Both are asynchronous: poll
describeOperation(orlistOperations) until it has finished, thendescribeFileto confirm the file isAvailable.
Good to know
- File ids come from
listFiles(or are the id you chose on upsert); operation ids come back from upload and upsert. - Timestamps are ISO 8601 UTC. File
statusisProcessing,AvailableorProcessingFailed. describeFilewithinclude_url=trueadds a temporarysigned_urlfor downloading the original file; it expires quickly, so do not store it.- Deleting files or assistants is not in this spec; use the Pinecone console.
Source: Pinecone Assistant API reference (https://docs.pinecone.io/reference/api/2026-07/assistant/list_files), checked 2026-10-20.
How to use this spec
- Create a free VX Agents account (sandbox tools included).
- Open the marketplace and connect “Pinecone Assistant Files & Chat” to an agent.
- Expose it as an MCP server for Claude/ChatGPT, or chat with it directly.