> ## Documentation Index > Fetch the complete documentation index at: https://developer.duplik.cn/llms.txt > Use this file to discover all available pages before exploring further. > Upload one document as a raw file stream (multipart/form-data) # Upload Knowledge File With Stream ## OpenAPI ````yaml post /v1/knowledge/{knowledge_id}/files/form openapi: 3.1.0 info: title: spectra-server description: The API for Spectra Backend. version: 0.1.0 servers: - url: https://api-spectra.duplik.cn security: [] paths: /v1/knowledge/{knowledge_id}/files/form: post: tags: - Knowledge summary: Upload Knowledge File With Stream description: >- Upload one document as a raw file stream. Unlike `POST /v1/knowledge/{knowledge_id}/files`, which takes URLs, the binary is posted straight to the server and forwarded to object storage — one file per call. Processing is asynchronous: the response returns the created document and parsing, chunking and indexing continue in the background. Poll `GET /v1/knowledge/document/{document_id}` until `process_status` is 200 to know the content is searchable. Pass `process_document: false` to store the file without starting that pipeline. The form fields mirror `/reupload`, with one difference: this endpoint creates a new document, so `document_metadata` has no previous document to inherit from — anything you do not pass is either generated by the model or left empty. operationId: >- upload_knowledge_file_with_stream_v1_knowledge__knowledge_id__files_form_post parameters: - name: knowledge_id in: path required: true schema: type: string title: Knowledge Id description: Knowledge base ID description: Knowledge base ID requestBody: required: true content: multipart/form-data: schema: type: object properties: file: type: string format: binary title: File description: >- File content. The type is decided by the file name extension (case-insensitive), not the Content-Type. Supported: pdf / doc / docx / ppt / pptx, xlsx / xls / csv, txt / md / markdown / html / htm / xml, png / jpg, and mp3 / mp4 / m4a / wav / webm / mpga / mpeg / mov / flv. Any other extension returns 400. folder_id: anyOf: - type: string - type: 'null' title: Folder Id description: Target folder ID. Defaults to the knowledge base root folder process_document: type: boolean title: Process Document default: true description: Whether to start the processing pipeline right away document_metadata: anyOf: - type: string - type: 'null' title: Document Metadata description: >- Document metadata as a JSON string, merged into the document's metadata_info. Common fields: title, entity_names (tags written as "key:value" that drive metadata pre-filtering at retrieval time), time_periods, and custom_data (free-form key-values that are stored, indexed and returned but never used for filtering). A non-empty entity_names skips LLM metadata generation entirely, so title and time_periods are no longer produced automatically — pass title alongside it or the title stays empty. folder_id, folder_ids, url, source_url, file_path, file_size, file_name and file_type are filled in by the server from the uploaded file and are ignored if supplied. Invalid JSON is logged server-side and treated as if the field were absent; the request still succeeds. Example: {"title":"SY500 Service Manual","entity_names":["model:SY500"]} document_setting: anyOf: - type: string - type: 'null' title: Document Setting description: >- Processing settings for this upload as a JSON string. Omit it and every setting follows the knowledge base (pdf_parsing_mode, smart_indexing_mode, smart_indexing_enabled, overall_summarize_enabled, split_media_enabled, audio_parsing_mode, audio_chunk_mode, pdf_parsing_element_types). Supplying it is all-or-nothing rather than a patch: the settings are built from your JSON alone, so any field you leave out falls back to its model default instead of the knowledge base — pass {"pdf_parsing_mode":2} on its own and smart_indexing_mode becomes 0 and overall_summarize_enabled becomes true. Chunking (chunk size, overlap, separators) is never part of this field and always comes from the knowledge base. Smart indexing runs only when smart_indexing_enabled is true AND smart_indexing_mode is 2 (advanced); leaving it off is recommended. Invalid JSON is logged and treated as absent. Example: {"pdf_parsing_mode":2,"smart_indexing_enabled":false} required: - file title: Body_upload_knowledge_file_with_stream responses: '200': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/Document' '400': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Bad Request '422': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unprocessable Entity '500': content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal Server Error security: - HTTPBearer: [] components: schemas: Document: properties: created_at: type: integer title: Created At updated_at: type: integer title: Updated At org_id: type: string maxLength: 20 title: Org Id user_id: type: string maxLength: 20 title: User Id overall_summarize_enabled: anyOf: - type: boolean - type: 'null' title: Overall Summarize Enabled description: Generate an overall summary. Boolean default: true smart_indexing_mode: anyOf: - type: integer - type: 'null' title: Smart Indexing Mode description: >- Smart indexing mode. 0: disabled (recommended), 1: standard, 2: advanced default: 0 smart_indexing_enabled: anyOf: - type: boolean - type: 'null' title: Smart Indexing Enabled description: >- Enable smart indexing. Boolean. Takes effect only together with smart_indexing_mode 2 (advanced); leaving it false is recommended unless the corpus needs it, as it adds noticeable processing time and token cost default: true split_media_enabled: anyOf: - type: boolean - type: 'null' title: Split Media Enabled description: Generate media segments. Boolean default: true pdf_parsing_mode: anyOf: - type: integer - type: 'null' title: Pdf Parsing Mode description: 'PDF parsing mode. 1: page, 2: section (recommended), 3: section v2' default: 2 pdf_parsing_element_types: anyOf: - items: type: integer type: array - type: 'null' title: Pdf Parsing Element Types description: 'pdf parsing element list, eg: [1, 2]. 1: table, 2: image, 3: formula' default: - 1 - 2 read_pdf_pages: anyOf: - type: string - type: 'null' title: Read Pdf Pages description: 'read pdf pages, Example: ''1,3,4'' or ''1,4-end'' or ''all''' audio_parsing_mode: anyOf: - type: integer - type: 'null' title: Audio Parsing Mode description: 'audio parsing mode, 1: transcript, 2: speaker diarization' audio_chunk_mode: anyOf: - type: integer - type: 'null' title: Audio Chunk Mode default: 1 dataset_id: type: string title: Dataset Id file_id: type: string title: File Id name: anyOf: - type: string maxLength: 256 - type: 'null' title: Name document_type: anyOf: - type: integer - type: 'null' title: Document Type default: 1 next_step: anyOf: - type: boolean - type: 'null' title: Next Step description: next step default: true llm: anyOf: - type: object - type: 'null' title: Llm default: {} metadata_info: type: object title: Metadata Info default: {} task_priority: anyOf: - type: integer - type: 'null' title: Task Priority description: task priority description: anyOf: - type: string maxLength: 512 - type: 'null' title: Description default: '' summary: anyOf: - type: string - type: 'null' title: Summary default: '' step_status: anyOf: - type: integer - type: 'null' title: Step Status default: 100 status: anyOf: - type: integer - type: 'null' title: Status default: 1 process_status: anyOf: - type: integer - type: 'null' title: Process Status default: 100 version: anyOf: - type: integer - type: 'null' title: Version default: 2 splitter_type: anyOf: - type: integer - type: 'null' title: Splitter Type default: 1 splitter: type: object title: Splitter default: {} sections: items: type: object type: array title: Sections default: [] content_text: anyOf: - type: string - type: 'null' title: Content Text description: '' trim_text: anyOf: - type: boolean - type: 'null' title: Trim Text description: '' default: true document_id: type: string title: Document Id type: object required: - org_id - user_id - dataset_id - file_id - document_id title: Document ErrorResponse: properties: code: type: integer title: Code message: type: string title: Message type: object required: - code - message title: ErrorResponse securitySchemes: HTTPBearer: type: http scheme: bearer ````