Skip to main content
POST
/
files
/
{assistant_name}
PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
ENCODED_METADATA="%7B%22published%22%3A%222024-01-01%22%2C%22document_type%22%3A%22script%22%7D" # URL encoded metadata - See w3schools.com/tags/ref_urlencode.ASP
LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

curl -X POST "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME?metadata=$ENCODED_METADATA" \
     -H "Api-Key: $PINECONE_API_KEY" \
     -F "file=@$LOCAL_FILE_PATH"

{
  "name": "example-file.txt",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "{ 'published': '2024-01-01', 'document_type': 'manuscript' }",
  "created_on": "2023-11-07T05:31:56Z",
  "updated_on": "2023-11-07T05:31:56Z",
  "status": "Processing",
  "percent_done": 50,
  "signed_url": "https://storage.googleapis.com/bucket/file.pdf",
  "error_message": "<string>"
}

PINECONE_API_KEY="YOUR_API_KEY"
ASSISTANT_NAME="example-assistant"
ENCODED_METADATA="%7B%22published%22%3A%222024-01-01%22%2C%22document_type%22%3A%22script%22%7D" # URL encoded metadata - See w3schools.com/tags/ref_urlencode.ASP
LOCAL_FILE_PATH="/Users/jdoe/Downloads/example_file.txt"

curl -X POST "https://prod-1-data.ke.pinecone.io/assistant/files/$ASSISTANT_NAME?metadata=$ENCODED_METADATA" \
     -H "Api-Key: $PINECONE_API_KEY" \
     -F "file=@$LOCAL_FILE_PATH"

{
  "name": "example-file.txt",
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "metadata": "{ 'published': '2024-01-01', 'document_type': 'manuscript' }",
  "created_on": "2023-11-07T05:31:56Z",
  "updated_on": "2023-11-07T05:31:56Z",
  "status": "Processing",
  "percent_done": 50,
  "signed_url": "https://storage.googleapis.com/bucket/file.pdf",
  "error_message": "<string>"
}

Authorizations

​
Api-Key
string
header
required

Pinecone API Key

Headers

​
X-Pinecone-Api-Version
string
default:2025-10
required

Required date-based version header

Path Parameters

​
assistant_name
string
required

The name of the assistant to upload files to.

Query Parameters

​
metadata
string<json>

Optional JSON-encoded metadata for files.

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

Response

File upload has been accepted.

The response format for a successful file upload request.

​
name
string
required
​
id
string<uuid>
required
​
metadata
object
​
created_on
string<date-time>
​
updated_on
string<date-time>
​
status
string

The current state of the uploaded file. Possible values:

  • Processing: File is being processed (parsed, chunked, embedded)
  • Available: Processing completed successfully; file is ready for use
  • Deleting: Deletion has been initiated but not yet completed
  • ProcessingFailed: Processing failed with an error

Note: Once a file is deleted, the API returns 404 Not Found instead of a file object.

​
percent_done
number<double> | null

The percentage of the file that has been processed

​
signed_url
string | null

A signed URL that provides temporary, read-only access to the underlying file. Anyone with the link can access the file, so treat it as sensitive data. Expires after a short time.

Example:

"https://storage.googleapis.com/bucket/file.pdf?..."

​
error_message
string | null

A message describing any error during file processing. Provided only if an error occurs.

​
multimodal
boolean

Indicates whether the file was processed as multimodal.