Upsert a file
Create or replace a file in the specified assistant. If a file with the given assistant_file_id already exists, it will be replaced with the new file. If it doesn't exist, a new file will be created with that identifier.
This operation is asynchronous. The file processing will occur in the background.
For guidance and examples, see Manage files.
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
FILE_ID="my-custom-file-id"
LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"
curl -X PUT "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME/$FILE_ID" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-04" \
-F "file=@$LOCAL_FILE_PATH"{
"id": "op-1234-abcd-5678",
"operation_type": "upsert_file",
"file_id": "my-custom-file-id",
"status": "Processing",
"created_on": "2025-10-01T12:30:00Z",
"percent_complete": 0
}PUT /files/{assistant_name}/{assistant_file_id}
Authorizations
Section titled “Authorizations”Api-KeystringrequiredPinecone API Key
Headers
Section titled “Headers”X-Pinecone-Api-VersionstringrequiredRequired date-based version header
Path Parameters
Section titled “Path Parameters”assistant_namestringrequiredThe name of the assistant to upload files to.
assistant_file_idstringrequiredThe identifier of the file to be created or replaced. Must be 1-128 characters long and consist only of alphanumeric characters, hyphens (-), or underscores ().
Required string length: 1 - 128
Query Parameters
Section titled “Query Parameters”multimodal?stringOptional flag to opt in to multimodal file processing (PDFs only). Can be either true or false. Default is false.
The desired file to be uploaded and processed into the assistant.
filestringrequiredThe file to upload.
metadata?object | nullOptional metadata associated with the file. This metadata can be used to filter files when listing them or to restrict search results when querying the assistant. Maximum size is 16KB.
Response
Section titled “Response”202 — File upload has been accepted for processing. The file will be created if it doesn't exist, or replaced if it already exists. The operation will complete asynchronously.
Describes the status of an ongoing or completed server operation.
idstringrequiredThe unique identifier for the operation.
Example: op-1234-abcd-5678
operation_typestringrequiredThe kind of action represented by this operation, such as uploading or deleting a file.
Example: upload_file
file_id?string | nullThe identifier of the file being operated on.
Example: my-file-id-123
statusstringrequiredThe status of the operation. - Processing: The operation is in progress. - Completed: The operation finished successfully. - Failed: The operation failed. See error_message for details.
Example: Processing
created_onstringrequiredThe timestamp when the operation was created, in ISO 8601 format.
Example: 2025-10-01T12:30:00.000Z
completed_on?string | nullThe timestamp when the operation completed or failed, in ISO 8601 format. Present only when status is Completed or Failed.
Example: 2025-10-01T12:35:00.000Z
percent_complete?integerThe progress made by the operation, as a percentage (0-100).
Required range: 0 <= x <= 100. Example: 42
error_message?string | nullA message describing the error that caused the operation to fail. Present only when status is Failed.
Example: File processing failed: unsupported file format.
ingestion_units?number | nullThe number of ingestion units consumed by this operation. Present only when status is Completed for file ingestion operations.
Example: 50