> ## Documentation Index
> Fetch the complete documentation index at: https://docs.pinecone.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](https://docs.pinecone.io/guides/assistant/manage-files#upload-a-local-file).
```bash curl theme={null}
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"}'
```
```json curl theme={null}
{
"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
}
```
This example shows a `Processing` operation. The `error_message` field is present only when the operation status is `Failed`.
## OpenAPI
````yaml https://raw.githubusercontent.com/pinecone-io/pinecone-api/refs/heads/main/2026-04/assistant_data_2026-04.oas.yaml POST /files/{assistant_name}
openapi: 3.0.3
info:
title: Pinecone assistant data plane API
description: >-
Pinecone Assistant Engine is a context engine to store and retrieve relevant
knowledge from millions of documents at scale. This API supports
interactions with assistants.
contact:
name: Pinecone Support
url: https://support.pinecone.io
email: support@pinecone.io
license:
name: Apache 2.0
url: https://www.apache.org/licenses/LICENSE-2.0
version: 2026-04
servers:
- url: https://{assistant_host}
variables:
assistant_host:
default: unknown
description: The host of the created assistant
security:
- ApiKeyAuth: []
tags:
- name: Manage Assistants
description: Actions that manage Assistants
paths:
/files/{assistant_name}:
post:
tags:
- Manage Assistants
summary: Upload a file
description: >-
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](https://docs.pinecone.io/guides/assistant/manage-files#upload-a-local-file).
operationId: upload_file
parameters:
- in: header
name: X-Pinecone-Api-Version
description: Required date-based version header
required: true
schema:
default: 2026-04
type: string
style: simple
- in: path
name: assistant_name
description: The name of the assistant to upload files to.
required: true
schema:
type: string
example: test-assistant
style: simple
- in: query
name: multimodal
description: >-
Optional flag to opt in to multimodal file processing (PDFs only).
Can be either `true` or `false`. Default is `false`.
schema:
x-enum:
- 'true'
- 'false'
type: string
style: form
requestBody:
description: The desired file to be uploaded and processed into the assistant.
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/FileData'
required: true
responses:
'202':
description: File upload accepted. Processing has started.
headers:
Location:
description: URL to the operation resource for polling status.
style: simple
schema:
example: /operations/test-assistant/op-1234-abcd
type: string
content:
application/json:
schema:
$ref: '#/components/schemas/OperationModel'
'400':
description: Bad request. The request body included invalid request parameters.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
files-validation-error:
summary: Validation error on ingest.
value:
error:
code: INVALID_ARGUMENT
message: >-
Uploaded file can only currently be either a pdf or txt
file
status: 400
'401':
description: 'Unauthorized. Possible causes: Invalid API key.'
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
unauthorized:
summary: Unauthorized
value:
error:
code: UNAUTHENTICATED
message: Invalid API key.
status: 401
'404':
description: Assistant not found.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
assistant-not-found:
summary: Assistant not found.
value:
error:
code: NOT_FOUND
message: Assistant "example-assistant" not found.
status: 404
'500':
description: Internal server error.
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
internal-server-error:
summary: Internal server error
value:
error:
code: UNKNOWN
message: Internal server error
status: 500
components:
schemas:
FileData:
type: object
properties:
file:
description: The file to upload.
type: string
format: binary
metadata:
nullable: true
example:
created_by: Jane Doe
published: '2025-10-01T00:00:00.000Z'
tags:
- report
- Q4
- analytics
description: >-
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.
type: object
required:
- file
OperationModel:
description: >-
The OperationModel describes the status of an ongoing or completed
server operation.
type: object
properties:
id:
example: op-1234-abcd-5678
description: The unique identifier for the operation.
type: string
operation_type:
example: upload_file
description: >-
The kind of action represented by this operation, such as uploading
or deleting a file.
x-enum:
- upload_file
- upsert_file
- update_file_metadata
- delete_file
type: string
file_id:
nullable: true
example: my-file-id-123
description: The identifier of the file being operated on.
type: string
status:
example: Processing
description: |-
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.
x-enum:
- Processing
- Completed
- Failed
type: string
created_on:
example: '2025-10-01T12:30:00.000Z'
description: The timestamp when the operation was created, in ISO 8601 format.
type: string
format: date-time
completed_on:
nullable: true
example: '2025-10-01T12:35:00.000Z'
description: >-
The timestamp when the operation completed or failed, in ISO 8601
format. Present only when status is `Completed` or `Failed`.
type: string
format: date-time
percent_complete:
example: 42
description: The progress made by the operation, as a percentage (0-100).
type: integer
format: int32
minimum: 0
maximum: 100
error_message:
nullable: true
example: 'File processing failed: unsupported file format.'
description: |-
A message describing the error that caused the operation to fail.
Present only when status is `Failed`.
type: string
ingestion_units:
nullable: true
example: 50
description: >-
The number of ingestion units consumed by this operation.
Present only when status is `Completed` for file ingestion
operations.
type: number
format: double
required:
- id
- operation_type
- status
- created_on
ErrorResponse:
example:
error:
code: TOO_MANY_REQUESTS
message: Too many get or list assistant requests, try again later
status: 429
description: The response shape used for all error responses.
type: object
properties:
status:
example: 500
description: The HTTP status code of the error.
type: integer
error:
example:
code: INVALID_ARGUMENT
message: 'Invalid region: Valid options are us, eu'
description: Detailed information about the error that occurred.
type: object
properties:
code:
description: The status code associated with the error.
x-enum:
- OK
- UNKNOWN
- INVALID_ARGUMENT
- DEADLINE_EXCEEDED
- QUOTA_EXCEEDED
- NOT_FOUND
- ALREADY_EXISTS
- PERMISSION_DENIED
- UNAUTHENTICATED
- RESOURCE_EXHAUSTED
- FAILED_PRECONDITION
- ABORTED
- OUT_OF_RANGE
- UNIMPLEMENTED
- INTERNAL
- UNAVAILABLE
- DATA_LOSS
- FORBIDDEN
- TOO_MANY_REQUESTS
type: string
message:
example: Message content cannot be empty
description: A message providing details about the error.
type: string
details:
description: >-
Additional information about the error. This field is not
guaranteed to be present.
type: object
required:
- code
- message
required:
- status
- error
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Api-Key
description: Pinecone API Key
````