insertFile
FileWrapper insertFile(folderId, insertFile.file, insertFile.title, insertFile.createNewIfExist, insertFile.keepConvertStatus, insertFile.stream.canRead, insertFile.stream.canWrite, insertFile.stream.canSeek, insertFile.stream.canTimeout, insertFile.stream.length, insertFile.stream.position, insertFile.stream.readTimeout, insertFile.stream.writeTimeout)
POST /api/2.0/files/{folderId}/insert
Insert a file
Stores a file in the folder named by the path in a single request, taking its name from title rather than from the uploaded part, which is what separates it from POST api/2.0/files/{folderId}/upload. The content may arrive either as a multipart part or as the raw request body. The name is stripped of characters a title cannot hold and truncated, and createNewIfExist settles the clash: false adds a new version to the file that already carries the name, true keeps both by giving the new one a numeric suffix. The caller needs the right to add content to the folder, so a reader, an editor and a guest get 403, a section root and an archived room are refused as well, and an unknown folder gives 404. Formats the portal converts are converted afterwards in the background; pass keepConvertStatus to keep the outcome readable through GET api/2.0/files/file/{fileId}/checkconversion. The answer is the stored file. A large payload belongs in a chunked session instead.
Parameters
| Name | In | Type | Description | Notes |
|---|---|---|---|---|
| folderId | path | Integer (int32) | The folder that receives the file; take the id from a listing such as GET api/2.0/files/@root. A room or an ordinary folder inside one is accepted, a section root is not. | [required] [example: 1] |
| insertFile.file | form | File (binary) | The content to store, sent as a multipart/form-data part. The same content may instead be sent as the raw request body, which is what a client that cannot build a form does; when both are present the form part wins. | [optional] |
| insertFile.title | form | String | The name to store the file under, extension included. It wins over the name of the uploaded part, which is the reason to choose this operation over the plain upload, and it is the only name available when the content arrives as a raw body. Characters a title cannot hold are replaced with underscores and the name is cut to 170 characters before the file is stored. | [optional] |
| insertFile.createNewIfExist | form | Boolean | Settles the clash with a file already carrying that title: left out, the content is written as the next version of that file; set to true, both survive and the new one gets a numeric suffix in its title. | [optional] |
| insertFile.keepConvertStatus | form | Boolean | Decides whether the outcome of the background conversion outlives the conversion itself. True keeps the queue record, so GET api/2.0/files/file/{fileId}/checkconversion can still report the result or the error; left out, the record is cleared the moment the conversion ends and that call finds nothing. | [optional] |
| insertFile.stream.canRead | form | Boolean | [optional] | |
| insertFile.stream.canWrite | form | Boolean | [optional] | |
| insertFile.stream.canSeek | form | Boolean | [optional] | |
| insertFile.stream.canTimeout | form | Boolean | [optional] | |
| insertFile.stream.length | form | Long (int64) | [optional] | |
| insertFile.stream.position | form | Long (int64) | [optional] | |
| insertFile.stream.readTimeout | form | Integer (int32) | [optional] | |
| insertFile.stream.writeTimeout | form | Integer (int32) | [optional] |
Responses
| Status code | Description | Type | Response headers |
|---|---|---|---|
| 200 | The stored file with its id and the title it was actually saved under; a version above 1 means the content was added to a file that already carried this name instead of creating a new one | FileWrapper | X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset |
| 402 | The file exceeds the single-request upload limit, or storing it would exceed a storage quota or size limit | - | - |
| 403 | The caller cannot add content to this folder | - | - |
| 404 | No folder with the specified ID | - | - |
| 415 | The installation restricts uploadable formats and the file extension is not among them | - | - |
| 500 | A file that is not a PDF is stored in a form-filling room | - | - |
| 401 | Unauthorized | ErrorApiResponse | - |
| 429 | Too Many Requests. | ErrorApiResponse | Retry-After |
| 400 | Bad Request. | ErrorApiResponse | - |
| 502 | Bad Gateway. Returned by the reverse proxy, response body may be HTML and not JSON. | - | - |
| 503 | Service Unavailable. Returned by the reverse proxy, response body may be HTML and not JSON. | - | - |
Return type
Third-party storage
For a file or folder in a connected third-party storage the identifier is a string such as sbox-42, and the call differs in these parts only:
| Name | In | Type | Description | Notes |
|---|---|---|---|---|
| folderId | path | String | The folder that receives the file; take the id from a listing such as `GET api/2.0/files/@root`. A room or an ordinary folder inside one is accepted, a section root is not. | [required] [example: sbox-42] |
Return type: ThirdPartyFileWrapper
Authorization
Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId
HTTP request headers
- Content-Type: multipart/form-data
- Accept: application/json