PIpinecone
Manage Assistants

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.

put/files/{assistant_name}/{assistant_file_id}

Request

Path parameters

assistant_namestring required

The name of the assistant to upload files to.

assistant_file_idstring 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 (_).

Query parameters

multimodalstring

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

Headers

X-Pinecone-Api-Versionstring required

Required date-based version header

Request body multipart/form-data

filestring binary required

The file to upload.

metadataobject nullable

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 request

{
  "metadata": {
    "created_by": "Jane Doe",
    "published": "2025-10-01",
    "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.

idstring required

The unique identifier for the operation.

operation_typestring required

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

file_idstring nullable

The identifier of the file being operated on.

statusstring 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.
created_onstring date-time required

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

completed_onstring date-time nullable

The timestamp when the operation completed or failed, in ISO 8601 format. Present only when status is Completed or Failed.

percent_completeinteger

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

error_messagestring nullable

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

ingestion_unitsnumber double nullable

The number of ingestion units consumed by this operation. Present only when status is Completed for file ingestion operations.

Example response

{
  "id": "op-1234-abcd-5678",
  "operation_type": "upload_file",
  "file_id": "my-file-id-123",
  "status": "Processing",
  "created_on": "2025-10-01T12:30:00Z",
  "completed_on": "2025-10-01T12:35:00Z",
  "percent_complete": 42,
  "error_message": "File processing failed: unsupported file format.",
  "ingestion_units": 50
}

Changes

No recorded changes to this operation across all 1 revision of this API.