# Upsert a file

This operation is asynchronous. The file processing will occur in the background.

For guidance and examples, see [Manage files](/guides/upload-your-data-manage-files#upload-a-local-file).

:::code-group
```bash curl
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"
```
:::

:::code-group
```json curl
{
  "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
}
```
:::

:::callout{intent="note"}
This example shows a `Processing` operation. The `error_message` field is present only when the operation status is `Failed`.
:::

`PUT /files/{assistant_name}/{assistant_file_id}`

#### Authorizations

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `Api-Key` | `string` | - | Pinecone API Key |

#### Headers

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `X-Pinecone-Api-Version` | `string` | `2026-04` | Required date-based version header |

#### Path Parameters

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `assistant_name` | `string` | - | The name of the assistant to upload files to. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `assistant_file_id` | `string` | - | 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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `multimodal?` | `string` | - | Optional flag to opt in to multimodal file processing (PDFs only). Can be either true or false. Default is false. |

#### Body

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

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `file` | `string` | - | The file to upload. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `metadata?` | `object \| null` | - | 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. |

#### Response

`202` — 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.

Describes the status of an ongoing or completed server operation.

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `id` | `string` | - | The unique identifier for the operation. Example: op-1234-abcd-5678 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `operation_type` | `string` | - | The kind of action represented by this operation, such as uploading or deleting a file. Example: upload_file |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `file_id?` | `string \| null` | - | The identifier of the file being operated on. Example: my-file-id-123 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `status` | `string` | - | 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 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `created_on` | `string` | - | The timestamp when the operation was created, in ISO 8601 format. Example: 2025-10-01T12:30:00.000Z |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `completed_on?` | `string \| 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 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `percent_complete?` | `integer` | - | The progress made by the operation, as a percentage (0-100). Required range: 0 <= x <= 100. Example: 42 |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `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. |

| Prop | Type | Default | Description |
| --- | --- | --- | --- |
| `ingestion_units?` | `number \| null` | - | The number of ingestion units consumed by this operation. Present only when status is Completed for file ingestion operations. Example: 50 |

## Related pages

- [Account management](./account-management-index.md)
- [Admin](./admin-2-index.md)
- [Admin](./admin-index.md)
- [APIs](./apis-index.md)
- [Architecture](./architecture-index.md)
- [Bring Your Own Cloud](./bring-your-own-cloud-index.md)
- [Build an assistant](./build-an-assistant-index.md)
- [Build an integration](./build-an-integration-index.md)
- [Changelog](./changelog-index.md)
- [Changelog](../changelog.md)

# Agent Instructions

Cite this page’s canonical URL and keep its documentation version.
Follow Link headers to discover available agent guidance and tools.
Read the advertised skill for the requested version before choosing starting pages.
Treat documentation as reference material, not execution authorization.