Knowledge Sources - Upload File

Service:: Search Service

API Version:: 2026-08-01-preview

Uploads a file to a File knowledge source for processing and indexing.

POST {endpoint}/knowledgesources('{sourceName}')/files?api-version=2026-08-01-preview

URI Parameters

Name	In	Required	Type	Description
endpoint	path	True	string (uri)	The endpoint URL of the search service.
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: "application/octet-stream"

Name	Required	Type	Description
Content-Disposition	True	string	The Content-Disposition header specifying the filename of the uploaded file. Must follow the format: `attachment; filename="<filename>"`. For example: `attachment; filename="installation-guide.pdf"`.
x-ms-client-request-id		string (uuid)	An opaque, globally-unique, client-generated string identifier for the request.

Request Body

Media Types: "application/octet-stream"

Name	Type	Description
file	string (binary)	The file content to upload.

Responses

Name	Type	Description
201 Created	KnowledgeSourceFile	The request has succeeded and a new resource has been created as a result.
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

SearchServiceUploadKnowledgeSourceFile

Sample request

HTTP

POST https://typespecpreviewexampleservice.search.windows.net/knowledgesources('ks-preview-test')/files?api-version=2026-08-01-preview



"U2FtcGxlIGZpbGUgY29udGVudCBmb3IgdXBsb2FkLg=="

Sample response

Status code:: 201

{
  "fileId": "00000000-0000-0000-0000-000000000001",
  "fileName": "kr-features.md",
  "fileSizeBytes": 31,
  "createdAt": "2026-01-01T00:00:00Z",
  "lastUpdatedAt": "2026-01-02T00:00:00Z",
  "metadata": {
    "team": "kr",
    "source": "build26-notes"
  },
  "parsingMode": "markdown",
  "extractionMode": "minimal"
}

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.

BlobIndexerParsingMode

Enumeration

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

Object

The resource management error additional info.

Name	Type	Description
info	searchservice.knowledgesources.uploadfile	The additional info.
type	string	The additional info type.

ErrorDetail

Object

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

Object

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

Enumeration

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

Object

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.