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.

fileId
path True

string

The unique identifier of the file to update.

sourceName
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

KnowledgeSourceFileIngestionOperation

The response when asynchronous file ingestion is accepted.

Headers

  • Operation-Id: string
  • Operation-Location: string
  • Retry-After: integer
Other Status Codes

ErrorResponse

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
BlobIndexerParsingMode

Represents the parsing mode for indexing from an Azure blob data source.

ErrorAdditionalInfo

The resource management error additional info.

ErrorDetail

The error detail.

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

FileKnowledgeSourceExtractionMode

The extraction effort applied to an individual file. 'minimal' (the default) uses built-in extraction; 'standard' uses Content Understanding.

KnowledgeSourceFile

Metadata for a file uploaded to a File knowledge source.

KnowledgeSourceFileIngestionError

The error returned by a failed file ingestion operation.

KnowledgeSourceFileIngestionOperation

Tracks asynchronous upload or replacement of a file in a knowledge source.

OperationState

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

ErrorAdditionalInfo[]

The error additional info.

code

string

The error code.

details

ErrorDetail[]

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

ErrorDetail

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

FileKnowledgeSourceExtractionMode

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

BlobIndexerParsingMode

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

KnowledgeSourceFileIngestionError

The failure details, present only when ingestion fails.

id

string

The server-generated operation identifier.

kind enum:

knowledgeSourceFileIngestion

The kind of operation.

result

KnowledgeSourceFile

The file metadata, present only when ingestion succeeds.

status

OperationState

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.