Upload a file
Upload a file to the specified assistant.
An identifier will be generated. To specify a file identifier or to replace file content, use the upsert endpoint (PUT /files/{assistant_name}/{assistant_file_id}).
This operation is asynchronous. The response includes an operation ID that can be used to poll for completion via the describe operation endpoint.
For guidance and examples, see Manage files.
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"
curl -X POST "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME" \
-H "Api-Key: $PINECONE_API_KEY" \
-H "X-Pinecone-Api-Version: 2026-04" \
-F "file=@$LOCAL_FILE_PATH" \
-F 'metadata={"published": "2024-01-01", "document_type": "manuscript"}'{
"id": "op-1234-abcd-5678",
"operation_type": "upload_file",
"file_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
"status": "Processing",
"created_on": "2025-10-01T12:30:00Z",
"percent_complete": 0
}POST /files/{assistant_name}
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.
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 accepted. Processing has started.
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