Knowledge Sources - Ingest File Replacement
Starts asynchronous ingestion that replaces an existing file in a File knowledge source, processed on a Content Processor. Poll the returned operation to retrieve the updated file.
POST {endpoint}/knowledgesources('{sourceName}')/files('{fileId}'):ingest?api-version=2026-11-01-preview
URI Parameters
| Name | In | Required | Type | Description |
|---|---|---|---|---|
|
content
|
formData | True |
file |
The raw file content. |
|
metadata
|
formData | True |
string |
The JSON metadata describing the file. |
|
endpoint
|
path | True |
string (uri) |
The endpoint URL of the search service. |
|
file
|
path | True |
string |
The unique identifier of the file to update. |
|
source
|
path | True |
string |
The name of the knowledge source. |
|
api-version
|
query | True |
string minLength: 1 |
The API version to use for this operation. |
Request Header
Media Types: "multipart/form-data"
| Name | Required | Type | Description |
|---|---|---|---|
| x-ms-client-request-id |
string (uuid) |
An opaque, globally-unique, client-generated string identifier for the request. |
Responses
| Name | Type | Description |
|---|---|---|
| 202 Accepted |
The response when asynchronous file ingestion is accepted. Headers
|
|
| Other Status Codes |
An unexpected error response. |
Security
api-key
Type:
apiKey
In:
header
OAuth2Auth
Type:
oauth2
Flow:
implicit
Authorization URL:
https://login.microsoftonline.com/common/oauth2/v2.0/authorize
Scopes
| Name | Description |
|---|---|
| https://search.azure.com/.default |
Examples
SearchServiceIngestKnowledgeSourceFileReplacement
Sample request
POST https://typespecpreviewexampleservice.search.windows.net/knowledgesources('hr-files')/files('file-00000000000000000000000000000001'):ingest?api-version=2026-11-01-preview
Sample response
Operation-Id: 00000000-0000-0000-0000-000000000001
Operation-Location: https://typespecpreviewexampleservice.search.windows.net/knowledgesources('hr-files')/files/operations/00000000-0000-0000-0000-000000000001?api-version=2026-11-01-preview
Retry-After: 30
{
"id": "00000000-0000-0000-0000-000000000001",
"kind": "knowledgeSourceFileIngestion",
"status": "Running"
}
Definitions
| Name | Description |
|---|---|
|
Blob |
Represents the parsing mode for indexing from an Azure blob data source. |
|
Error |
The resource management error additional info. |
|
Error |
The error detail. |
|
Error |
Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.). |
|
File |
The extraction effort applied to an individual file. 'minimal' (the default) uses built-in extraction; 'standard' uses Content Understanding. |
|
Knowledge |
Metadata for a file uploaded to a File knowledge source. |
|
Knowledge |
The error returned by a failed file ingestion operation. |
|
Knowledge |
Tracks asynchronous upload or replacement of a file in a knowledge source. |
|
Operation |
The current state. Poll until the operation succeeds or fails. |
BlobIndexerParsingMode
Represents the parsing mode for indexing from an Azure blob data source.
| Value | Description |
|---|---|
| default |
Set to default for normal file processing. |
| text |
Set to text to improve indexing performance on plain text files in blob storage. |
| delimitedText |
Set to delimitedText when blobs are plain CSV files. |
| json |
Set to json to extract structured content from JSON files. |
| jsonArray |
Set to jsonArray to extract individual elements of a JSON array as separate documents. |
| jsonLines |
Set to jsonLines to extract individual JSON entities, separated by a new line, as separate documents. |
| markdown |
Set to markdown to extract content from markdown files. |
ErrorAdditionalInfo
The resource management error additional info.
| Name | Type | Description |
|---|---|---|
| info |
searchservice.knowledgesources.ingestfilereplacement |
The additional info. |
| type |
string |
The additional info type. |
ErrorDetail
The error detail.
| Name | Type | Description |
|---|---|---|
| additionalInfo |
The error additional info. |
|
| code |
string |
The error code. |
| details |
The error details. |
|
| message |
string |
The error message. |
| target |
string |
The error target. |
ErrorResponse
Common error response for all Azure Resource Manager APIs to return error details for failed operations. (This also follows the OData error response format.).
| Name | Type | Description |
|---|---|---|
| error |
The error object. |
FileKnowledgeSourceExtractionMode
The extraction effort applied to an individual file. 'minimal' (the default) uses built-in extraction; 'standard' uses Content Understanding.
| Value | Description |
|---|---|
| minimal |
Built-in extraction was performed. |
| standard |
Content Understanding extraction was performed. |
KnowledgeSourceFile
Metadata for a file uploaded to a File knowledge source.
| Name | Type | Description |
|---|---|---|
| createdAt |
string (date-time) |
The timestamp when the file was created. |
| errorMessage |
string |
The error message if file processing failed, null otherwise. |
| extractionMode |
The extraction mode applied to the file. |
|
| fileId |
string |
The unique identifier for the file. |
| fileName |
string |
The original file name. |
| fileSizeBytes |
integer (int64) |
The file size in bytes. |
| lastUpdatedAt |
string (date-time) |
The timestamp when the file was last updated. |
| metadata |
object |
Custom key/value metadata stored with the file. Returned but not searchable or filterable. |
| parsingMode |
The parsing mode applied to the file (auto-detected from the file). |
|
| prefix |
string |
The prefix (directory-like path) derived from the full file name. |
KnowledgeSourceFileIngestionError
The error returned by a failed file ingestion operation.
| Name | Type | Description |
|---|---|---|
| code |
string |
A machine-readable error code. |
| message |
string |
A description of the failure. |
KnowledgeSourceFileIngestionOperation
Tracks asynchronous upload or replacement of a file in a knowledge source.
| Name | Type | Description |
|---|---|---|
| error |
The failure details, present only when ingestion fails. |
|
| id |
string |
The server-generated operation identifier. |
| kind |
enum:
knowledge |
The kind of operation. |
| result |
The file metadata, present only when ingestion succeeds. |
|
| status |
The current state. Poll until the operation succeeds or fails. |
OperationState
The current state. Poll until the operation succeeds or fails.
| Value | Description |
|---|---|
| NotStarted |
The operation has not started. |
| Running |
The operation is in progress. |
| Succeeded |
The operation has completed successfully. |
| Failed |
The operation has failed. |
| Canceled |
The operation has been canceled by the user. |