Skip to main content
PUT
/
files
/
{assistant_name}
/
{assistant_file_id}
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
}

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
}
This example shows a Processing operation. The error_message field is present only when the operation status is Failed.

Authorizations

​
Api-Key
string
header
required

Pinecone API Key

Headers

​
X-Pinecone-Api-Version
string
default:2026-04
required

Required date-based version header

Path Parameters

​
assistant_name
string
required

The name of the assistant to upload files to.

​
assistant_file_id
string
required

The 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

​
multimodal
string

Optional flag to opt in to multimodal file processing (PDFs only). Can be either true or false. Default is false.

Body

multipart/form-data

The desired file to be uploaded and processed into the assistant.

​
file
file
required

The file to upload.

​
metadata
object

Optional 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.

Example:
{
  "created_by": "Jane Doe",
  "published": "2025-10-01T00:00:00.000Z",
  "tags": ["report", "Q4", "analytics"]
}

Response

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.

The OperationModel describes the status of an ongoing or completed server operation.

​
id
string
required

The unique identifier for the operation.

Example:

"op-1234-abcd-5678"

​
operation_type
string
required

The kind of action represented by this operation, such as uploading or deleting a file.

Example:

"upload_file"

​
status
string
required

The 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_on
string<date-time>
required

The timestamp when the operation was created, in ISO 8601 format.

Example:

"2025-10-01T12:30:00.000Z"

​
file_id
string | null

The identifier of the file being operated on.

Example:

"my-file-id-123"

​
completed_on
string<date-time> | null

The 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
integer<int32>

The progress made by the operation, as a percentage (0-100).

Required range: 0 <= x <= 100
Example:

42

​
error_message
string | null

A message describing the error that caused the operation to fail. Present only when status is Failed.

Example:

"File processing failed: unsupported file format."