PIpinecone
Manage Assistants

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.

post/files/{assistant_name}

Request

Path parameters

assistant_namestring required

The name of the assistant to upload files to.

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 accepted. Processing has started.

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.