{"openapi":"3.1.0","info":{"title":"api.file.kiwi v2","version":"2.0.0","description":"Public v2 API for creating file.kiwi WebFolders."},"servers":[{"url":"https://api.file.kiwi"}],"paths":{"/v2/folders":{"post":{"operationId":"createV2Folder","summary":"Create a v2 WebFolder","description":"Creates a WebFolder through one of two v2 flows. With files[], the API registers initial files and returns presigned upload URLs. Without files[], the API returns an empty shareable folder URL. The first browser uploader becomes the folder owner in file.kiwi. If no file is uploaded within 24 hours, the ownerless empty folder is deleted.","requestBody":{"required":false,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2FolderCreateRequest"},"examples":{"emptyShareFolder":{"summary":"Empty share folder for browser upload","value":{"title":"Shared Folder","mode":"share"}},"directUploadFolder":{"summary":"Folder with initial API-uploaded files","value":{"title":"API upload","mode":"send","encryption":{"ske":"base64-encoded-encrypted-share-key"},"files":[{"filename":"encrypted-name","filesize":1048576,"mimetype":"application/octet-stream"}]}}}}}},"responses":{"200":{"description":"Folder created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2FolderCreateResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}},"/v2/folders/{folderId}/files/{fileId}/upload-status":{"get":{"operationId":"getV2UploadStatus","summary":"Check direct API upload status","description":"Checks which chunks are missing for a file registered through the direct API upload flow.","parameters":[{"name":"folderId","in":"path","required":true,"schema":{"type":"string"}},{"name":"fileId","in":"path","required":true,"schema":{"type":"string"}},{"name":"uploadAuth","in":"query","required":false,"schema":{"type":"string"},"description":"Optional token returned by POST /v2/folders for direct API uploads."}],"responses":{"200":{"description":"Upload status","content":{"application/json":{"schema":{"$ref":"#/components/schemas/V2UploadStatusResponse"}}}},"400":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"500":{"$ref":"#/components/responses/Error"}}}}},"components":{"schemas":{"V2FolderCreateRequest":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.file.kiwi/schemas/v2-folder-create-request.json","title":"file.kiwi v2 folder create request","type":"object","additionalProperties":false,"properties":{"title":{"type":["string","null"],"maxLength":200,"description":"Optional folder title. Defaults to a date-based WebFolder title."},"mode":{"type":"string","enum":["send","share","request"],"default":"send","description":"send: owner uploads and others download. share: everyone can upload/download. request: visitors upload and owner reads."},"encryption":{"type":"object","additionalProperties":false,"properties":{"keyStrategy":{"type":"string","enum":["server_generated"],"description":"For empty folders, api.file.kiwi can generate the secret key included in the returned folderUrl."},"ske":{"type":"string","description":"Encrypted share key. Required when files[] is provided. For empty folders it may be omitted."}}},"files":{"type":"array","maxItems":10,"description":"Optional initial files. Omit or pass [] to create an empty folder for browser upload.","items":{"type":"object","additionalProperties":false,"required":["filename","filesize"],"properties":{"filename":{"type":"string","minLength":1,"description":"Encrypted filename or client-selected filename value."},"filesize":{"type":"number","exclusiveMinimum":0,"maximum":1098437885952,"description":"File size in bytes. Direct API upload flow limit is 999 GiB per file."},"mimetype":{"type":"string"}}}}}},"V2FolderCreateResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.file.kiwi/schemas/v2-folder-create-response.json","title":"file.kiwi v2 folder create response","oneOf":[{"title":"Empty folder response","type":"object","required":["folderId","folderUrl","folderUrlBase","mode","uploadRequiredWithinHours","files"],"properties":{"folderId":{"type":"string"},"folderUrl":{"type":"string","format":"uri","description":"Share URL including the URL fragment secret key."},"folderUrlBase":{"type":"string","format":"uri"},"mode":{"type":"string","enum":["send","share","request"]},"uploadRequiredWithinHours":{"type":"number","const":24,"description":"The ownerless empty folder is deleted if no browser user uploads a file within this many hours."},"files":{"type":"array","maxItems":0}}},{"title":"Direct API upload response","type":"object","required":["folderId","folderUrl","mode","uploadAuth","files"],"properties":{"folderId":{"type":"string"},"folderUrl":{"type":"string","format":"uri"},"mode":{"type":"string","enum":["send","share","request"]},"uploadAuth":{"type":"string"},"files":{"type":"array","items":{"type":"object","required":["filename","fileId","chunkSize","chunks","freeDownloadHours","uploadUrls"],"properties":{"filename":{"type":"string"},"fileId":{"type":"string"},"chunkSize":{"type":"number"},"chunks":{"type":"number"},"freeDownloadHours":{"type":"number"},"uploadUrls":{"type":"object","required":["head","tail","path","signatures","headers"],"properties":{"head":{"type":"string"},"tail":{"type":"string"},"path":{"type":"string"},"signatures":{"type":"array","items":{"type":"string"}},"headers":{"type":"object","additionalProperties":{"type":"string"}}}}}}}}}]},"V2UploadStatusResponse":{"$schema":"https://json-schema.org/draft/2020-12/schema","$id":"https://api.file.kiwi/schemas/v2-upload-status-response.json","title":"file.kiwi v2 upload status response","type":"object","required":["complete","missing"],"properties":{"complete":{"type":"boolean"},"missing":{"type":"array","items":{"type":"number"},"description":"Missing one-based chunk numbers."}}},"ErrorResponse":{"type":"object","required":["error"],"properties":{"error":{"type":"string"}}}},"responses":{"Error":{"description":"Error response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}}