ONLYOFFICE DocSpace Files API

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

addTemplates

BooleanWrapper addTemplates(TemplatesRequestDto)

POST /api/2.0/files/templates

Add template files

Adds the listed files to the personal template list of the calling account, the set the portal offers when a new document is started from an existing one. The list belongs to the account and no other member sees it. Every authenticated member type may manage their own list, a guest is refused, and read access to each file is required. Only formats the portal treats as template documents survive: the accepted extensions arrive in extsWebTemplate of GET api/2.0/files/settings, and a file of any other format is dropped silently. Only numeric ids are accepted, so a file on a connected third-party account cannot become a template. The answer is true whenever the request was understood, which an empty list, an id that does not exist and an unreadable file all achieve, so it confirms nothing about what was added; no operation of this document reads the list back. Repeating the call is safe. Use DELETE api/2.0/files/templates to drop a file again.

Parameters

Name	In	Type	Description	Notes
TemplatesRequestDto	body	TemplatesRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always true: the request was understood, which does not mean that anything was added	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeVersionHistory

FileIntegerArrayWrapper changeVersionHistory(fileId, ChangeHistory)

PUT /api/2.0/files/file/{fileId}/history

Change version history

Closes or reopens a revision group in the version history of a file and answers with every stored version of that file, newest first. With continueVersion=false the named version is completed: its content is stored again as a fresh version that opens a new revision group, so the editing that follows no longer extends the previous one. With continueVersion=true the last revision group is folded back into the group before it, so the next save continues that revision instead of becoming a version of its own; a file that has only one group is left as it is. A version of 0 means the current version. The caller needs the right to edit the history of the file, which the room admin, a DocSpace admin acting as room manager and a member with content-creator rights have; plain editing access is refused with 403, as are a guest and a member without access to the room. The call is mutating and not idempotent. A file that is locked, lies in Trash, is open in an editing session or is kept in a connected third-party storage is refused.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose version history is changed.	[required] [example: `1`]
ChangeHistory	body	ChangeHistory	The change to make to the revision group.	[required]

Responses

Status code	Description	Type	Response headers
200	The versions of the file after the change	FileIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not change the version history of the file	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

checkFillFormDraft

StringWrapper checkFillFormDraft(fileId, CheckFillFormDraft)

POST /api/2.0/files/masterform/{fileId}/checkfillformdraft

Open a form draft for filling

Resolves the editor address the caller must open to fill out the given PDF form, and provisions the personal draft that filling needs. The form has to live in a form-filling room and filling has to be started for it with PUT api/2.0/files/file/{fileId}/manageformfilling; a caller who may edit the form, a form whose filling has not started, and a request naming view or embedded as the action are all sent straight to the form itself. Read access to the form is enough to get an address, fill-forms access is what puts the caller into the filling flow, and a holder of an external link may call it without signing in, while a caller with neither a session nor a link key is rejected. In the filling case the call is not read-only: it copies the form into the room's in-progress folder under the caller's name, clears the new-item badge, closes the editing session of the original, and answers with the address of that copy. A repeated call reuses that copy, and a call naming an existing draft adds a discard notice when that draft is no longer valid. The answer is one URL string that may carry a #message/... fragment the editor renders as a notice. For the full editor configuration use GET api/2.0/files/file/{fileId}/openedit. A form the caller cannot open is refused with 403, and one that does not exist is answered as missing.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The identifier of the PDF form to open, as it is returned by a room listing such as `GET api/2.0/files/{folderId}`. The identifier of an already created draft is accepted here as well.	[required] [example: `1`]
CheckFillFormDraft	body	CheckFillFormDraft	The revision of the form to open and what the caller intends to do with it.	[required]

Responses

Status code	Description	Type	Response headers
200	The editor address to open, with an optional notice fragment	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot open the form, or asked for a past revision without history access	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

ChunkedUploadSessionResponseWrapperIntegerWrapper

HTTP request headers

Content-Type: application/json
Accept: application/json

copyFileAs

FileEntryBaseWrapper copyFileAs(fileId, CopyAsJsonElement)

POST /api/2.0/files/file/{fileId}/copyas

Copy a file

Copies one file into another folder under a new title, converting its content when the new title names a different format, and answers with the copy that was created. The extension of destTitle decides what happens: the same extension as the source copies the bytes as they are, a different one has the document service convert them first, and toForm=true converts a document into a PDF form. password unlocks a source file that is protected by one. destFolderId is read as a number for a folder inside the portal and as a string for a folder in a connected third-party storage; anything else is answered with an empty body and nothing is copied. The caller needs read access to the source file and the right to create files in the destination folder, and is otherwise refused with 403; a missing file or folder is answered with 404, and a format that cannot be converted with 400. The call is mutating and not idempotent - each call adds another copy. To copy many items at once, and without converting, use PUT api/2.0/files/fileops/copy.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to copy.	[required] [example: `1`]
CopyAsJsonElement	body	CopyAsJsonElement	The title, the destination and the conversion options of the copy.	[required]

Responses

Status code	Description	Type	Response headers
200	The copy that was created	FileEntryBaseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The content cannot be converted into the format of the new title	-	-
403	The caller may not read the file or may not create files in the destination folder	-	-
404	The file or the destination folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

FileEntryBaseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createEditSession

ChunkedUploadSessionResponseWrapperIntegerWrapper createEditSession(fileId, fileSize)

POST /api/2.0/files/file/{fileId}/edit_session

Create the editing session

Opens a chunked session that replaces the content of an existing file, which is how WebDAV clients save over a document. The answer carries the session id the later calls quote, the address of the standalone chunk handler, the expiry and the reserved size, and nothing is written until the parts reach POST api/2.0/files/{folderId}/session/{sessionId}/upload and the session is closed with PUT api/2.0/files/{folderId}/session/{sessionId}/finalize, where folderId is the folder the file lives in. Unlike an upload into a folder, the finished content does not become a new version: it overwrites the current one, and the file loses its encrypted flag and its stored conversion result in the process. The caller must be allowed to edit the file, as the owner, a room manager and a member invited with editing rights are; a reader and a guest get 403. A file that does not exist is answered as missing, and a payload above the portal limit for chunked uploads is refused before the session is created.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose content the session will replace; take the id from a folder listing or from the file itself.	[required] [example: `1`]
fileSize	query	Long (int64)	The number of bytes the new content will take. It is checked against the portal limit for chunked uploads before the session opens, and a session left at 0 takes the whole content in a single part.	[optional] [example: `1024`]

Responses

Status code	Description	Type	Response headers
200	The created editing session, wrapped in the success envelope	ChunkedUploadSessionResponseWrapperIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot edit this file	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

createFile

FileIntegerWrapper createFile(folderId, CreateFileJsonElement)

POST /api/2.0/files/{folderId}/file

Create a file

Creates a file in the folder named in the route and answers with the stored file. The extension in the title decides the format: an extension of a known text, spreadsheet or presentation format is rewritten to the portal's own DOCX, XLSX or PPTX, a title with no extension at all gets DOCX added, while an unknown extension and the few formats the portal keeps as they are stay untouched; enableExternalExt=true stores the title verbatim and skips that rewriting. The content comes from one of three sources, tried in this order: formId copies a ready form out of the form gallery, templateId copies an existing file the caller can read - a number for a file in the portal, a string for one in a connected third-party storage - and with neither of them the portal's blank template for that format and the caller's language is used. The caller needs the right to create files in the folder, and the room roots, Archive and the template sections are refused even to an admin. The call is mutating and not idempotent. To create the file in the caller's own section use POST api/2.0/files/@my/file.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the file is created in.	[required] [example: `1`]
CreateFileJsonElement	body	CreateFileJsonElement	The title of the new file and the source of its content.	[required]

Responses

Status code	Description	Type	Response headers
200	The created file	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createFileInMyDocuments

FileIntegerWrapper createFileInMyDocuments(CreateFileJsonElement)

POST /api/2.0/files/@my/file

Create a file in My documents

Creates a file in the caller's own My documents section and answers with the stored file. The extension in the title decides the format: an extension of a known text, spreadsheet or presentation format is rewritten to the portal's own DOCX, XLSX or PPTX, a title with no extension at all gets DOCX added, while an unknown extension and the few formats the portal keeps as they are stay untouched; enableExternalExt=true stores the title verbatim and skips that rewriting. The content comes from one of three sources, tried in this order: formId copies a ready form out of the form gallery, templateId copies an existing file the caller can read - a number for a file in the portal, a string for one in a connected third-party storage - and with neither of them the portal's blank template for that format and the caller's language is used. The call is mutating and not idempotent: each call adds another file. A guest has no My documents section of their own, so a guest cannot use this operation at all, and a template the caller cannot read is refused. To create a file in a room or any other folder use POST api/2.0/files/{folderId}/file.

Parameters

Name	In	Type	Description	Notes
CreateFileJsonElement	body	CreateFileJsonElement		[optional]

Responses

Status code	Description	Type	Response headers
200	The created file	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createFilePrimaryExternalLink

FileShareWrapper createFilePrimaryExternalLink(id, FileLinkRequest)

POST /api/2.0/files/file/{id}/link

Create the file primary external link

Answers with the primary external link of a file, creating it on the first call and returning the one that already exists afterwards, so the operation is idempotent in effect: a second call with other parameters does not reconfigure the existing link, and changing one is the business of PUT api/2.0/files/file/{id}/links. The parameters therefore only shape the link at the moment it is born - access its rights, expirationDate its lifetime, which for a file in a personal section is unlimited here rather than the default of a few days, internal whether only signed-in members may follow it, denyDownload whether the content may only be viewed, and password a secret to be asked for. A PDF form gets the rights it needs for filling out whatever was asked for, and a form in a form-filling room is answered with the link of the room instead. The caller needs the right to share the file and is otherwise refused with 403; a link that was deliberately revoked is not recreated but answered with 404. Read the address from sharedTo.shareLink.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file the link points at.	[required] [example: `1`]
FileLinkRequest	body	FileLinkRequest	The settings of the link. They are applied in full, so a field left out is reset rather than kept.	[required]

Responses

Status code	Description	Type	Response headers
200	The primary external link of the file	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not share the file	-	-
404	The file does not exist, or its primary link was revoked	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createHtmlFile

FileIntegerWrapper createHtmlFile(folderId, CreateTextOrHtmlFile)

POST /api/2.0/files/{folderId}/html

Create an HTML file

Creates an HTML file in the folder named in the route out of the markup passed as the content, and answers with the stored file. The .html extension is added to the title unless the title already ends with it, and a request carrying no content is rejected as an invalid request. createNewIfExist acts the other way round than its name reads: with true the file that already carries this title is updated, the markup replacing its content and a version appearing in its history, while with false, which is also the default, another file is created and its title made unique, as in Notes (1).html. Updating needs the existing file to be editable by the caller, so one that is locked, open in an editing session, encrypted or in Trash is left alone and a new file appears beside it instead. The caller needs the right to create files in the folder and is otherwise refused with 403. The call is mutating. To create the file in the caller's own section use POST api/2.0/files/@my/html.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the file is created in.	[required] [example: `1`]
CreateTextOrHtmlFile	body	CreateTextOrHtmlFile	The title, the content and the collision behaviour of the new file.	[required]

Responses

Status code	Description	Type	Response headers
200	The created or updated HTML file	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not create files in this folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createHtmlFileInMyDocuments

FileIntegerWrapper createHtmlFileInMyDocuments(CreateTextOrHtmlFile)

POST /api/2.0/files/@my/html

Create an HTML file in My documents

Creates an HTML file in the caller's own My documents section out of the markup passed as the content, and answers with the stored file. The .html extension is added to the title unless the title already ends with it, and a request carrying no content is rejected as invalid. createNewIfExist acts the other way round than its name reads: with true the file that already carries this title is updated, the markup replacing its content and a version appearing in its history, while with false, which is also the default, another file is created and its title made unique, as in Notes (1).html. Updating needs the existing file to be editable by the caller, so one that is locked, open in an editing session, encrypted or in Trash is left alone and a new file appears beside it instead. The call is mutating: repeating it with true keeps a single file and grows its history, repeating it with false fills the section with numbered copies. A guest has no My documents section and is refused. To create the file in a room or another folder use POST api/2.0/files/{folderId}/html.

Parameters

Name	In	Type	Description	Notes
CreateTextOrHtmlFile	body	CreateTextOrHtmlFile		[optional]

Responses

Status code	Description	Type	Response headers
200	The created or updated HTML file	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not create a file in this section	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createTextFile

FileIntegerWrapper createTextFile(folderId, CreateTextOrHtmlFile)

POST /api/2.0/files/{folderId}/text

Create a text file

Creates a text file in the folder named in the route out of the text passed as the content, and answers with the stored file. The extension follows the content rather than the request: .txt normally, but .html as soon as the text contains something shaped like an HTML tag, so a snippet of markup sent here ends up as an HTML file; the extension is added to the title unless the title already ends with it. A request carrying no content is rejected as an invalid request. createNewIfExist acts the other way round than its name reads: with true the file that already carries this title is updated and a version appears in its history, while with false, which is also the default, another file is created and its title made unique, as in Notes (1).txt. A file that is locked, open in an editing session, encrypted or in Trash is not updated - a new file appears beside it instead. The caller needs the right to create files in the folder. The call is mutating. To create the file in the caller's own section use POST api/2.0/files/@my/text.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the file is created in.	[required] [example: `1`]
CreateTextOrHtmlFile	body	CreateTextOrHtmlFile	The title, the content and the collision behaviour of the new file.	[required]

Responses

Status code	Description	Type	Response headers
200	The created or updated text file	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createTextFileInMyDocuments

FileIntegerWrapper createTextFileInMyDocuments(CreateTextOrHtmlFile)

POST /api/2.0/files/@my/text

Create a text file in My documents

Creates a text file in the caller's own My documents section out of the text passed as the content, and answers with the stored file. The extension follows the content rather than the request: .txt normally, but .html as soon as the text contains something shaped like an HTML tag, so a snippet of markup sent here ends up as an HTML file; the extension is added to the title unless the title already ends with it. A request carrying no content is rejected as invalid. createNewIfExist acts the other way round than its name reads: with true the file that already carries this title is updated and a version appears in its history, while with false, which is also the default, another file is created and its title made unique, as in Notes (1).txt. A file that is locked, open in an editing session, encrypted or in Trash is not updated - a new file appears beside it instead. The call is mutating. A guest has no My documents section and is refused. To create the file in a room or another folder use POST api/2.0/files/{folderId}/text.

Parameters

Name	In	Type	Description	Notes
CreateTextOrHtmlFile	body	CreateTextOrHtmlFile		[optional]

Responses

Status code	Description	Type	Response headers
200	The created or updated text file	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createThumbnails

ObjectArrayWrapper createThumbnails(BaseBatchRequestDto)

POST /api/2.0/files/thumbnails

Queue file thumbnails

Asks the portal to build preview thumbnails for the listed files, and answers at once with the same file ids that were sent. That answer echoes the request and does not confirm that anything was queued: the work is handed over to a background worker, and a failure on the way there is written to the log rather than reported to the caller. Only the file ids of the body are read - the folder ids are ignored, and a request naming no files at all is answered with an empty list. Ids of files kept in a connected third-party storage are dropped as well, because the worker handles portal storage only. Access to the individual files is not checked here; the caller has to be signed in or to reach the portal through an external share link, and an anonymous caller without such a link is refused. The call is asynchronous and safe to repeat. The thumbnails themselves are not in the answer: read thumbnailStatus and thumbnailUrl of the file, for instance with GET api/2.0/files/file/{fileId}, until the status reports the thumbnail as created.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The file ids from the request, echoed back	ObjectArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ObjectArrayWrapper

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteFile

FileOperationArrayWrapper deleteFile(fileId, Delete, ReturnSingleOperation)

DELETE /api/2.0/files/file/{fileId}

Delete a file

Queues the deletion of one file and answers with the caller's file operations, the one just created among them. The file is not gone when the response arrives: poll GET api/2.0/files/fileops until the operation reports finished, and read its error to learn whether the deletion succeeded. By default the file is moved to Trash, from where it can be restored; immediately=true deletes it for good instead, and inside a room, where there is no Trash, deletion is always final. deleteAfter=true postpones the deletion until the editing session on the file has ended, so a file somebody is working on is not pulled away. returnSingleOperation=true narrows the answer to this deletion instead of listing every active operation of the caller. The caller needs the right to delete the file, which the room admin, a DocSpace admin acting as room manager and a content creator acting on their own file have; editing access alone, read access, a guest and a member without access to the room are all refused. The call is destructive. To delete several items at once use PUT api/2.0/files/fileops/delete.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to delete.	[required] [example: `1`]
Delete	body	Delete	When and how the file is deleted.	[required]
ReturnSingleOperation	query	Boolean	Which operations the answer carries: `true` returns the operation this call started and nothing else, `false` returns every operation of the same kind that the caller has running or unread. When nothing was queued, which happens for an empty selection, `true` falls back to the full list.	[optional] [example: `false`]

Responses

Status code	Description	Type	Response headers
200	The file operations of the caller, including the deletion just queued	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteRecent

deleteRecent(BaseBatchRequestDto)

DELETE /api/2.0/files/recent

Delete recent files

Removes the listed entries from the Recent section of the calling account, the history of opened files that GET api/2.0/files/recent returns. Nothing is deleted from storage and no other member's history is touched; access to the entries is not checked at all, so a file the caller can no longer read can still be cleared from their own history. Only numeric file ids are honoured, so a file on a connected third-party account cannot be cleared this way, and folder ids are accepted but change nothing because the section lists files only. The answer carries no body and reports nothing about how many entries were found: an empty request and an id that was never in the section are accepted alike. Repeating the call is safe, but an entry returns the next time the file is opened or POST api/2.0/files/file/{fileId}/recent is called for it. To hide the whole section instead, call PUT api/2.0/files/displayrecent.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Empty answer: the listed entries no longer appear in the Recent section	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteTemplates

BooleanWrapper deleteTemplates(request_body)

DELETE /api/2.0/files/templates

Delete template files

Takes the listed files off the personal template list of the calling account, leaving the files themselves untouched: only the template mark is dropped. The body of this request is a bare JSON array of numeric file ids rather than an object with a field, and a request that carries no array at all is rejected as an invalid request. Every authenticated member type may manage their own list, a guest is refused, and read access to a file is required for its mark to be dropped. The answer is true whenever the array was understood, which an empty array, an id that does not exist and a file that was never a template all achieve, so it confirms nothing about what was removed. Repeating the call is safe. Use POST api/2.0/files/templates to put a file back on the list; that operation expects an object with a fileIds field, so the two bodies are not interchangeable.

Parameters

Name	In	Type	Description	Notes
request_body	body	List	The files to take off the template list, by id; this array is the whole request body. Only a file stored in the portal itself can be a template, which is why an id here is always numeric.	[optional]

Responses

Status code	Description	Type	Response headers
200	Always true: the files named in the array are no longer templates of the caller	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

XlsxReportResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

generateXlsx

XlsxReportResponseWrapper generateXlsx(fileId)

POST /api/2.0/files/file/{fileId}/xlsx

Generate a form answers report

Queues generation of the spreadsheet that collects every answer submitted for a PDF form in a form-filling room, and answers at once with the queued task, the original form and a flag telling whether the report file is being created now or an existing one refreshed in place. Either identifier works: the id of the original form, or the id of an XLSX or CSV result file inside the room's Complete folder, from which the portal resolves the form behind it. The form must already have been opened for filling with PUT api/2.0/files/file/{fileId}/startfilling and must still live in the form-filling room that started it. The caller must be allowed to update that form's report. The call is mutating and asynchronous: the spreadsheet is not ready when the response arrives, so poll GET api/2.0/files/file/{fileId}/xlsx with the original form's id until the task reports completion, then take the produced file from the task. Calling it again while a run is still going answers with that run instead of starting a second one.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The generation task, the original form and the new-file flag	XlsxReportResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not update the report, or the file is not a started form of a form-filling room	-	-
404	The file id, or the original form behind a result file, resolves to nothing	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAllFormRoles

FormRoleArrayWrapper getAllFormRoles(fileId)

GET /api/2.0/files/file/{fileId}/formroles

Get form roles

Returns the roles of a PDF form together with the state each of them is in, which is how a client shows who is expected to fill the form next. Every entry carries the name of the role, the account holding it, the sequence number that decides the turn and a status: the roles of earlier turns are reported as complete, those of later turns as waiting, and the role whose turn it is as either yours to fill or already in progress, depending on whether that person has opened the form; when the filling has been stopped, the role it was interrupted at is reported as stopped instead. A form whose filling was never started answers with an empty list. The file has to be a PDF form, or the completed copy of one, and anything else is refused. Read access to the form is enough, so every member of the room sees the roles, while a caller without access to the room and a guest outside it are refused with 403 and an unknown file is answered with 404. The operation is read-only. The assignment itself is written by POST api/2.0/files/file/{fileId}/formrolemapping.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The roles of the form with the state of each	FormRoleArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller has no read access to the form	-	-
404	No file with this identifier exists	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FormRoleArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getEditDiffUrl

EditHistoryDataWrapper getEditDiffUrl(fileId, version)

GET /api/2.0/files/file/{fileId}/edit/diff

Get changes URL

Answers with everything an editor needs in order to show what changed in one version of a file: the address of the version itself, its document key and format, the address of the recorded changes, the same trio for the version it is compared against, and a token that signs the whole answer for the document service. version picks the version, and 0, the default, means the current one. changesUrl and previous are filled in only when the portal has stored the changes of that version, which is the case for versions written by an editing session; for a version uploaded as a whole they stay empty and only the file itself can be shown. The addresses are meant for the document service and carry their own time-limited keys. The caller needs the right to read the history of the file, which editing access and above grant: read-only access, commenting access, a guest and an anonymous caller are all refused, as is a file kept in a connected third-party storage. The operation is read-only. For the list of versions themselves use GET api/2.0/files/file/{fileId}/edit/history.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose changes are read.	[required] [example: `1`]
version	query	Integer (int32)	The version to show the changes of, as reported by `GET api/2.0/files/file/{fileId}/edit/history`; 0 means the current version.	[optional] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The addresses and keys the editor needs to show the changes	EditHistoryDataWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

EditHistoryDataWrapper

Authorization

EditHistoryArrayWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getEditHistory

EditHistoryArrayWrapper getEditHistory(fileId)

GET /api/2.0/files/file/{fileId}/edit/history

Get version history

Returns the editing revisions of a file, oldest first, as the document service understands them: each entry carries the version and the revision group it belongs to, the account that saved it, when it was saved, the comment left on it, the document key of that revision and, where the portal stored them, the changes it introduced. Only the revisions a person saved are listed - the autosaves an editing session writes in between are left out, which is what separates this list from the plain version list of GET api/2.0/files/file/{fileId}/history. The caller needs the right to read the history of the file, which editing access and above grant: commenting access, read-only access, a guest, a member without access to the room and an anonymous caller are all refused, and so is a file kept in a connected third-party storage, which keeps no history in the portal. The operation is read-only. Take one entry to GET api/2.0/files/file/{fileId}/edit/diff to show its changes, or to POST api/2.0/files/file/{fileId}/restoreversion to bring it back.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The editing revisions of the file, oldest first	EditHistoryArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

FileEncryptionInfoWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getEncryptionInfo

FileEncryptionInfoWrapper getEncryptionInfo(fileId)

GET /api/2.0/files/{fileId}/access

Get file encryption information

Returns what the caller needs in order to decrypt one file of an end-to-end encrypted private room: userKeys holds the key pairs of the calling account, the private half of each of them encrypted with that person's own password, and fileKeys holds the file keys that were issued to this account for this file, each naming the public key it was encrypted for. Only the keys of the calling account are ever returned, never those of the other people in the room. An account that holds no key pair yet, and a file no key was issued for, answer with empty lists rather than with an error, so an empty fileKeys means the caller cannot open that file rather than that the file is unencrypted. The caller needs read access to the file; a caller without it, and a file that does not exist, are both refused with 403. The operation is read-only. Keys are issued by PUT api/2.0/files/{fileId}/access, and the personal key pairs are managed under api/2.0/privacyroom/keys.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose encryption keys are read. Only a file in an end-to-end encrypted private room has any.	[required]

Responses

Status code	Description	Type	Response headers
200	The key pairs of the caller and the file keys issued to them	FileEncryptionInfoWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The file cannot carry encryption keys	-	-
403	The caller has no read access to the file	-	-
404	The file does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFileHistory

HistoryArrayWrapper getFileHistory(fileId, fromDate, toDate, count, startIndex)

GET /api/2.0/files/file/{fileId}/log

Get file history

Returns the activity log of a single file - who renamed, moved, shared, converted, locked or edited it, and when - as the portal recorded it in its audit trail. Entries arrive newest first, and the events that belong to one action are folded into a single entry whose related list carries the rest of them. fromDate and toDate are read in the portal's time zone and narrow the range; startIndex and count page through the result, and the number of matching entries is reported in the response headers rather than in the body. The caller needs read access to the file, so a member of the room it lies in, the admin of that room and a DocSpace admin all see the same log, while a caller without access to the room is refused with 403 and an unknown id is answered with 404. The operation is read-only. Only files stored in the portal itself have a log here - a file kept in a connected third-party storage has none. For the log of a folder or a room use GET api/2.0/files/folder/{folderId}/log.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose activity log is read; only files stored in the portal itself have one.	[required] [example: `1`]
fromDate	query	Date (date-time)	The earliest moment an entry may have, read in the time zone of the portal; left out, the log starts at the oldest entry the portal still keeps.	[optional] [example: `2025-01-01T00:00:00.0000000Z`]
toDate	query	Date (date-time)	The latest moment an entry may have, read in the time zone of the portal; left out, the log ends at the newest entry.	[optional] [example: `2025-12-31T23:59:59.0000000Z`]
count	query	Integer (int32)	How many entries one page holds. The number of entries that match the query is reported in the response headers, not in the body.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries to skip before the page begins, counted from the newest one, so pages are taken by adding the page size to it.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	The activity entries of the file, newest first	HistoryArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller has no read access to the file	-	-
404	No file with this identifier exists	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

HistoryArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFileInfo

FileIntegerWrapper getFileInfo(fileId, version)

GET /api/2.0/files/file/{fileId}

Get file information

Returns one file as the portal stores it, together with the state it has for the caller: the title, the folder it lies in, the size, the current version and revision group, the addresses for viewing and editing it, the actions the caller is allowed to perform on it, the sharing rights it was reached through, and the thumbnail state. version picks an older version instead of the current one; the default of -1 means the current version. When the file belongs to another person's own section and the caller cannot read the folder holding it, the answer reports the Shared with me section as its folder, so that a client can show it in a place the caller can actually open. The caller needs read access to the file, which any member of the room it lies in has; a caller without access to the room is refused and an anonymous caller without an external share link is rejected. The operation is read-only. For every version at once use GET api/2.0/files/file/{fileId}/history.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to read.	[required] [example: `1`]
version	query	Integer (int32)	The version to read, as reported by `GET api/2.0/files/file/{fileId}/history`; -1, the default, reads the current version.	[optional] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The file as it is stored, with the state it has for the caller	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFileLinks

FileShareArrayWrapper getFileLinks(id, count, startIndex)

GET /api/2.0/files/file/{id}/links

Get file external links

Lists the external links of a file, each with its identifier, title, address, rights, expiration date and download restriction. startIndex and count page through the list, and the total number of links is reported in the response headers rather than in the body. A file that has never been shared by link answers with an empty list; the primary link is part of this list once it exists, and it is the only one that is created on demand, by GET api/2.0/files/file/{id}/link. For a PDF form kept in a form-filling room the link of the room is appended to the answer, because that is the address through which the form is filled out. The caller needs the right to share the file, which its creator, the room admin and a DocSpace admin acting as room manager have; a caller without access to the file is refused and an anonymous caller is rejected. The operation is read-only. Take an identifier from here to PUT api/2.0/files/file/{id}/links to change or remove that link.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
count	query	Integer (int32)	How many entries at most to answer with, in the operations of this file that return a list; an operation that answers with a single object is not affected by it.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries of such a list to skip before answering, used together with `count` to walk through it page by page.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	The external links of the file	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFilePrimaryExternalLink

FileShareWrapper getFilePrimaryExternalLink(id, count, startIndex)

GET /api/2.0/files/file/{id}/link

Get the file primary external link

Answers with the primary external link of a file - the one the Copy link action of a client hands out - with its address in sharedTo.shareLink, its rights in access, and its expiration date, password flag and download restriction beside them. The link is created on the first read if the file has none, with read rights, no password and no expiry, so this operation mutates on that first call and is a plain read afterwards; repeated calls answer with the same link identifier. A PDF form in a form-filling room is answered with the link of that room, carried over to the form. The caller needs the right to share the file, which its creator, the room admin and a DocSpace admin acting as room manager have; a caller without access to the file is refused with 403 and an anonymous caller is rejected, while a link that was deliberately revoked is answered with 404 rather than being recreated. The custom links of the same file, the primary one excepted, are listed by GET api/2.0/files/file/{id}/links.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
count	query	Integer (int32)	How many entries at most to answer with, in the operations of this file that return a list; an operation that answers with a single object is not affected by it.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries of such a list to skip before answering, used together with `count` to walk through it page by page.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	The primary external link of the file	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not share the file	-	-
404	The file does not exist, or its primary link was revoked	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFileVersionInfo

FileIntegerArrayWrapper getFileVersionInfo(fileId)

GET /api/2.0/files/file/{fileId}/history

Get file versions

Returns every stored version of a file, newest first, each of them shaped like the file itself - the version and the revision group it belongs to, the size, the comment saved with it, the addresses for viewing it, and the thumbnail and lock state. Unlike the editing revisions of GET api/2.0/files/file/{fileId}/edit/history, this list also holds the autosave revisions an editing session writes, so it is the fuller of the two, and it is the shape a client already knows how to render. The caller needs the right to read the history of the file, which is a stricter rule than reading the file: in a room only its managers and content creators may read the history, and in a personal section editing access is enough, so a member with read access to somebody else's file, and even a DocSpace admin in that position, are refused, as is an anonymous caller. The operation is read-only. To restore one of the versions use POST api/2.0/files/file/{fileId}/restoreversion, and to close or reopen a revision group PUT api/2.0/files/file/{fileId}/history.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	Every stored version of the file, newest first	FileIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

FillingFormResultIntegerWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFillResult

FillingFormResultIntegerWrapper getFillResult(fillingSessionId)

GET /api/2.0/files/file/fillresult

Get form-filling result

Answers with the outcome of one completed form-filling session: the filled copy of the form, the original form it was made from, the number this submission was given inside the room, the identifier of the room and the account that started the filling. isRoomMember says whether the caller is a member of that room, which a client uses to decide whether the room can be offered for opening. The session is named by fillingSessionId, the value the document service reports when the filling ends; the portal remembers it only for a while after that, so a session that was never completed, one already forgotten and a value of the wrong shape are all answered as not found, while omitting the parameter is rejected as an invalid request. The operation is read-only and needs no sign-in: it is meant for the caller that has just finished filling the form through an external link, and the session identifier is the only secret involved. The filled copy itself is an ordinary file - read it with GET api/2.0/files/file/{fileId}.

Parameters

Name	In	Type	Description	Notes
fillingSessionId	query	String	The identifier of the finished filling session, the value the document service reports when the filling ends. The portal remembers it only for a while afterwards, so an older session is answered as not found.	[optional] [example: `11111111-2222-3333-4444-555555555555`]

Responses

Status code	Description	Type	Response headers
200	The result of the completed form-filling session	FillingFormResultIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

FormSubmissionsWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFormSubmissions

FormSubmissionsWrapper getFormSubmissions(fileId)

GET /api/2.0/files/file/{fileId}/submissions

Get form submission results

Returns everything that has been submitted against one PDF form: metadata describes the fields of the form, in the order they are laid out, and submissions carries one record per completed copy, each of them holding the values that were entered. It is the data behind the results table a client shows for a form, and the same data the spreadsheet report of POST api/2.0/files/file/{fileId}/xlsx is built from. Only the submissions of the version that is currently being filled are reported. The form has to be a PDF form whose filling has been started and which is still the original form of its room; a form that was never started, a copy of a form and a form whose room has been moved away are all refused. Read access to the form is enough, so every member of the room can read the results, while a caller without access to it is refused with 403. The operation is read-only. The list of roles and whose turn it is comes from GET api/2.0/files/file/{fileId}/formroles instead.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The submissions collected for the form, with the description of its fields	FormSubmissionsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller has no read access to the form	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPresignedFileUri

FileLinkWrapper getPresignedFileUri(fileId)

GET /api/2.0/files/file/{fileId}/presigned

Get a signed download address

Returns a direct download address for the current content of the file together with the signature token that the document service validates, which is what the portal hands over when the editors have to fetch the document themselves. The address points at the portal's file stream endpoint and is rewritten to the host the document service can reach, so on a deployment where the editors sit behind a private address it is not the address a browser should follow. The answer also carries the extension of the stored document, leading dot included. The caller needs read access to the file, and an unknown file id is reported as missing. The call only reads, and each call mints a fresh address and token rather than reusing the previous one, so the value is worth requesting again once a token has expired. For a link meant for a person, a plain address with no token to put behind a download button, use GET api/2.0/files/file/{fileId}/presigneduri instead.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The download address of the file with its signature token	FileLinkWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileLinkWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPresignedUri

StringWrapper getPresignedUri(fileId)

GET /api/2.0/files/file/{fileId}/presigneduri

Get file download link

Builds a download address for the current version of a file and answers with it as a plain string. The address points at the portal's own file handler and carries the file identifier, the version it was built for and a time-limited authentication key, so it can be handed to a downloader that cannot sign in to the portal itself; it stops working once that key has expired, and it keeps naming the version that was current when it was built rather than following later edits. The caller needs read access to the file: a member of the room it lies in gets an address, a caller without access to the room is refused, an unknown identifier is answered as not found and an anonymous caller is rejected. The operation is read-only and safe to repeat, though every call mints a new key. Nothing is downloaded here - follow the address to fetch the bytes. For the variant the document service signs, which comes back as an object with the file type and a token, use GET api/2.0/files/file/{fileId}/presigned.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The download address of the current file version	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

MentionWrapperArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getProtectedFileUsers

MentionWrapperArrayWrapper getProtectedFileUsers(fileId)

GET /api/2.0/files/file/{fileId}/protectusers

Get users for document protection

Lists the users the file is shared with, which is what a client offers when the author protects a document and picks who may still edit it. The list is built from the whole access list of the file: every entry that is not an explicit denial, with groups expanded into their members, the caller themselves and deleted accounts left out, ordered by display name. Access inherited from the room counts, so a member who never received a share on the file itself is listed too. A file kept in the legacy project storage always answers with an empty list rather than with its team. The call only reads. A guest is refused, an anonymous caller is answered with nothing, and a file id that resolves to nothing is refused as well instead of being reported as missing. For the readers to offer as mentions inside the editor use GET api/2.0/files/file/{fileId}/sharedusers.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The users the file is shared with, ordered by display name	MentionWrapperArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getReferenceData

FileReferenceWrapper getReferenceData(GetReferenceDataDtoInteger)

POST /api/2.0/files/file/referencedata

Resolve a spreadsheet reference

Resolves a reference that a formula in one spreadsheet makes to another document, and answers with the descriptor the document service needs in order to read it: the title, the download address, the file type, the document key of the co-editing session, the web editor link and the signature token. Three ways of naming the target are tried in order, and the first that resolves wins: fileKey as a file id inside the portal named by instanceId, then path looked up among the files sitting next to sourceFileId, then link, short links included, from which the file id is read out. A link that points outside this portal is not resolved at all and comes back unchanged as the address to follow. The caller needs read access to the source file and to its folder, otherwise the call is refused. The call only reads. A reference that resolves to nothing is still answered with 200, with the error text filled in and the rest of the descriptor empty, so read the error before using any other field.

Parameters

Name	In	Type	Description	Notes
GetReferenceDataDtoInteger	body	GetReferenceDataDtoInteger		[optional]

Responses

Status code	Description	Type	Response headers
200	The reference descriptor, or the same object with the error text set when nothing resolved	FileReferenceWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileReferenceWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getXlsx

DocumentBuilderTaskWrapper getXlsx(fileId)

GET /api/2.0/files/file/{fileId}/xlsx

Get form report generation status

Reports how far the spreadsheet of submitted form answers has got, the one queued by POST api/2.0/files/file/{fileId}/xlsx. A run is kept per portal, per caller and per form, so this reports the caller's own run and not one started by another member of the room; address it with the id of the original form rather than with the id of the produced spreadsheet. The answer carries the completion flag, the progress percentage, the error text when the run failed, and the id, name and address of the produced file once it is there. Nothing at all comes back when no run is on record for this caller and form, which is the normal answer before the first run and not an error. The call only reads and is meant to be polled until completion is reported. Any authenticated caller may ask; whether the report may be built is decided when the run is queued, not here.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The state of the report generation task, or nothing when no run is on record	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

isFormPDF

BooleanWrapper isFormPDF(fileId)

GET /api/2.0/files/file/{fileId}/isformpdf

Check the PDF file

Tells whether a file is a PDF form that can be filled out in the portal, and answers with a single boolean. The check is by content, not by extension: the beginning of the file is read and the answer is true only when it carries the marker the editors write into the forms they produce, so an ordinary PDF, and a PDF form made in other software, both answer false. A file whose name is not a PDF at all answers false without being read. Use it before offering the form-filling operations on a file, because a document that answers false cannot be started for filling. The caller needs read access to the file, and read access is enough - a member of the room with read-only rights gets the answer; a caller without access to the room is refused and an anonymous caller is rejected. The operation is read-only and idempotent. It says nothing about the state of the filling - for that read GET api/2.0/files/file/{fileId}/formroles.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	True when the file is a PDF form made in the editors, false otherwise	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

lockFile

FileIntegerWrapper lockFile(fileId, LockFileParameters)

PUT /api/2.0/files/file/{fileId}/lock

Lock a file

Locks a file so that nobody else can change it, or releases that lock, and answers with the file as it now stands. With lockFile=true the lock is put on the file and everybody else who is editing it at that moment is dropped out of the session, the caller excepted; the lock then blocks editing, renaming and deleting for everybody but the account that set it and the room admins. With lockFile=false the lock is removed and a note about the unlocking is appended to the current version comment, unless the file lives in a connected third-party storage. Locking a file that is already locked, or unlocking one that is not, changes nothing and still answers with the file, so the call is idempotent in effect while remaining a mutating one. The caller needs the right to lock the file, which the room admin, a DocSpace admin acting as room manager and a member with content-creator rights have; a member without access to the room and a guest are refused, and so is a file in Trash. A lock set by somebody else can only be released by a room manager.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to lock or unlock.	[required] [example: `1`]
LockFileParameters	body	LockFileParameters	The lock state to reach.	[required]

Responses

Status code	Description	Type	Response headers
200	The file with its lock state as it now stands	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ConfigurationIntegerWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

manageFormFilling

manageFormFilling(fileId, ManageFormFillingDtoInteger)

PUT /api/2.0/files/file/{fileId}/manageformfilling

Perform form filling action

Drives the filling of a PDF form through its states, the action deciding which way. Action 2 starts the filling: in a form-filling room the form is opened for filling, the members whose rights are limited to filling forms are let in, and a form that has been changed since it was last started has the drafts of its previous round dropped. Action 0 stops it, which in a virtual data room records who interrupted it and at which role and notifies the people who held the other roles, and in a form-filling room closes the form for filling. Action 1 resumes a filling that was stopped, clearing that record. Action 3 puts the form back into editing, closing it for filling and remembering the version it was edited from. The file has to be a PDF form lying in a room. Starting needs the right to start the filling, which the room admin and a member with content-creator rights have, while stopping a filling that somebody else started belongs to room managers alone, so a content creator is refused with 403 there. The call is mutating; the state that resulted is read with GET api/2.0/files/file/{fileId}/formroles.

Parameters

Name	In	Type	Description	Notes
fileId	path	String	The form the action applies to. Send the same value as the `formId` of the request body, which is the one the handler reads.	[required]
ManageFormFillingDtoInteger	body	ManageFormFillingDtoInteger		[optional]

Responses

Status code	Description	Type	Response headers
200	The action was applied to the form	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not start, stop or resume the filling of this form	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

openEditFile

ConfigurationIntegerWrapper openEditFile(fileId, version, view, editorType, edit, fill)

GET /api/2.0/files/file/{fileId}/openedit

Get the editor configuration

Builds everything an editor client needs to open the file: the document descriptor with its download address, title, type and document key, the editor configuration with the mode, the caller's permissions, the user and the customization, the callback the editors report back to, and the signature token the document service validates. version opens one entry of the file history and requires access to that history; left out, the current revision is opened. view, edit and fill say what the client intends to do, and editorType picks the desktop, mobile or embedded layout. For a PDF form the room decides the outcome and may overrule the request: a form-filling room, a virtual data room, a public room and a user folder each produce their own mode, and a form opened from the templates folder is read-only and, outside the mobile layout, framed as embedded. When the portal is over its storage quota the configuration comes back read-only with the exceeded scope named. In a private room the caller's encryption keys are added to the editor configuration. Payment is not required and an anonymous caller opens through an external link.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the editor configuration is built for. Take the id from a folder listing such as `GET api/2.0/files/{folderId}`.	[required] [example: `1`]
version	query	Integer (int32)	Which entry of the file history to open, numbered the way the file versions are. Left out, the current revision is opened; naming a version requires access to the history of the file.	[optional] [example: `1`]
view	query	Boolean	Asks for a read-only configuration. Left off, the configuration is built for editing as far as the caller's rights and the room the file lies in allow.	[optional] [example: `false`]
editorType	query	EditorType	Which editor layout the configuration is built for: the full desktop interface, the reduced mobile one, or the embedded viewer meant to be framed inside another page.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
edit	query	Boolean	Asks for editing rather than viewing. On a form in a form-filling room this also records that the form is being edited; the room may still turn the request into viewing or into filling.	[optional] [example: `false`]
fill	query	Boolean	Asks for a PDF form to open for filling out rather than for editing. It has no effect on a file that is not a form.	[optional] [example: `false`]

Responses

Status code	Description	Type	Response headers
200	The editor configuration for the requested file and mode	ConfigurationIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot read the file, or asked for a past version without access to the file history	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

EditHistoryArrayWrapper

HTTP request headers

Content-Type: Not defined
Accept: application/json

restoreFileVersion

EditHistoryArrayWrapper restoreFileVersion(fileId, version, url)

POST /api/2.0/files/file/{fileId}/restoreversion

Restore a file version

Brings an earlier version of a file back and answers with the editing revisions of the file after the restore. Nothing is overwritten: the content of the chosen version is stored again as a new version on top of the history, carrying a comment that says which version it was reverted to, so the intervening versions stay readable. url changes the source - with it the content is fetched from that address, which is how the document service returns a document with a set of changes rolled back, and the new version records that instead. Any links that pointed at drafts of the file are dropped, and the file is marked as new for the other people who can read it. version has to name an existing version and is refused with 400 when it is missing or already the current one. The caller needs the right to edit the history of the file and is otherwise refused with 403, an anonymous caller included. The call is mutating and not idempotent. A locked file, one in Trash, one being edited, an encrypted one and one kept in a connected third-party storage are all refused.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose version is restored.	[required] [example: `1`]
version	query	Integer (int32)	The version to restore, as reported by `GET api/2.0/files/file/{fileId}/edit/history`. It has to name an existing version that is not the current one.	[optional] [example: `1`]
url	query	String	The address the content of the new version is fetched from instead of the stored version, which is how the document service hands back a document with a set of changes rolled back; left out, the stored version is used.	[optional] [example: `https://document-server.example.com/cache/files/conv_1_docx/output.docx`]

Responses

Status code	Description	Type	Response headers
200	The editing revisions of the file after the restore	EditHistoryArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The version is missing or is already the current one	-	-
403	The caller may not change the version history of the file	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveEditingFileFromForm

FileIntegerWrapper saveEditingFileFromForm(fileId, DownloadUri, FileExtension, File, Forcesave)

PUT /api/2.0/files/file/{fileId}/saveediting

Save edited file content

Replaces the content of an existing file with an edited copy and answers with the file as it now stands. The content is the File part of a multipart/form-data body, and when no such part is sent the raw request body is saved instead, so an empty body empties the file. The DownloadUri query parameter does not supply content here; it is only read for the extension when FileExtension is empty. fileExtension names the format of the content being sent, and when it differs from the stored format the portal converts the content, or keeps it under a renamed copy when a third-party storage cannot convert it. The caller needs edit access to the file. The call is mutating and not idempotent: an ordinary call adds a version to the file history, while forcesave=true records an editor autosave, which overwrites the previous autosave revision instead of adding another version and leaves a running editing session in place. It is refused with 403 when the file is locked, lies in Trash, or is open in an editing session started by somebody else, and an unknown file id is reported as missing. For content too large to post in one request use POST api/2.0/files/file/{fileId}/edit_session.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose content is replaced. The submitted content is written onto this file, so it has to be the file the editing session was opened on rather than a copy of it.	[required] [example: `1`]
DownloadUri	query	String	An address the document service saved the document at. This operation does not fetch the content from it - the content always comes from the request body - and reads it only for the extension, when no file extension is given.	[optional] [example: `https://example.com/file.txt`]
FileExtension	form	String	The format the submitted content is in, with the leading dot, as in `.docx`. When it differs from the format the file is stored in, the portal converts the content before saving it. Left empty, the extension is read off the download address, and failing that the stored format is assumed.	[optional]
File	form	File (binary)	The edited content, sent as the `File` part of a `multipart/form-data` body. When the part is missing the raw request body is saved as the content instead, so an empty body empties the file.	[optional]
Forcesave	form	Boolean	Records the write as an editor autosave: the file keeps its running editing session and the previous autosave revision is overwritten. Left off, the write closes the solo editing session, is refused while somebody else has the file open, and adds a version to the history.	[optional]

Responses

Status code	Description	Type	Response headers
200	The file is saved and the stored version is returned	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The file id cannot be resolved to a storage that could accept the content	-	-
403	The caller cannot edit the file, or it is locked, in Trash, or open in somebody else's editing session	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

saveFileAsPdf

FileIntegerWrapper saveFileAsPdf(id, SaveAsPdfInteger)

POST /api/2.0/files/file/{id}/saveaspdf

Save a file as PDF

Converts a file into a PDF, stores that PDF as a new file in the folder named in the body, and answers with the file that was created. The source is left untouched, so the two files then live side by side. title names the result without an extension - the .pdf extension is added to it - and an empty title reuses the name of the source with its extension replaced. The conversion is done by the document service while the request waits, so the call takes as long as the document needs and answers with the finished file rather than with a queue entry. The caller needs read access to the source file and the right to create files in the destination folder, and is otherwise refused; a source file or a destination folder that does not exist is answered with 404. The call is mutating and not idempotent: each call adds another PDF, its title made unique when one of that name is already there. The result is marked as new for the room, and for a form the portal recognises it is stored as a PDF form. To convert in place instead use PUT api/2.0/files/file/{fileId}/checkconversion.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file to convert; it is left untouched.	[required] [example: `1`]
SaveAsPdfInteger	body	SaveAsPdfInteger	The destination folder and the name of the PDF.	[required]

Responses

Status code	Description	Type	Response headers
200	The PDF file that was created	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
404	The source file or the destination folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveFormRoleMapping

saveFormRoleMapping(fileId, SaveFormRoleMappingDtoInteger)

POST /api/2.0/files/file/{fileId}/formrolemapping

Save form role mapping

Assigns the roles of a PDF form to the people who are to fill them in, and starts the filling: the form is marked as being filled out, the account that called is recorded as the one who started it, everybody named in a role is notified, and the form becomes visible to the members whose room rights are limited to filling forms. Each role carries its name, the account that takes it and the sequence number that decides the turn, so the same sequence means the roles may be filled in parallel and different ones make a queue. Sending an empty role list resets the filling instead, dropping the assignment altogether. The whole set is replaced on every call, so the call is idempotent for a given set of roles but not additive. The file has to be a PDF form lying in a room; the caller needs the right to start the filling of that form, which the room admin and a member with content-creator rights have, and is otherwise refused with 403. Read back what was stored with GET api/2.0/files/file/{fileId}/formroles.

Parameters

Name	In	Type	Description	Notes
fileId	path	String	The form the role mapping belongs to. Send the same value as the `formId` of the request body, which is the one the handler reads.	[required]
SaveFormRoleMappingDtoInteger	body	SaveFormRoleMappingDtoInteger		[optional]

Responses

Status code	Description	Type	Response headers
200	The roles were stored and the filling was started or reset	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not start or reset the filling of this form	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setCustomFilterTag

FileIntegerWrapper setCustomFilterTag(fileId, CustomFilterParameters)

PUT /api/2.0/files/file/{fileId}/customfilter

Set the Custom Filter editing mode

Turns the Custom Filter editing mode of a spreadsheet on or off and answers with the file as it now stands. In that mode the sorting and filtering one person applies to the sheet is visible to that person alone, so that several people can work on the same data without moving the rows under each other; with the mode off, filtering is shared again, as everywhere else. Turning it on also drops everybody else out of the running editing session, the caller excepted, because the mode has to be established before the sheet is opened. Only formats that support the mode are accepted; anything else is rejected as an invalid request. The caller needs the right to use the mode in the room, which the room admin and a DocSpace admin acting as room manager have; read-only access, a member without access to the room and an anonymous caller are refused. Once the mode has been switched on by one person, only that person, a room manager or a DocSpace admin can switch it off again. The call is mutating and, called twice with the same value, changes nothing the second time.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The spreadsheet whose Custom Filter mode is switched.	[required] [example: `1`]
CustomFilterParameters	body	CustomFilterParameters	The Custom Filter state to reach.	[required]

Responses

Status code	Description	Type	Response headers
200	The spreadsheet with its Custom Filter state as it now stands	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setEncryptionInfo

setEncryptionInfo(fileId, AccessRequestKeyDto)

PUT /api/2.0/files/{fileId}/access

Set file encryption information

Issues the file keys that let the named people open one file of an end-to-end encrypted private room. Each entry of the body names the account the key is for, the public key it was encrypted with and the encrypted key itself, so the plain key never reaches the portal: the client encrypts it once per recipient with the public key that GET api/2.0/files/file/{fileId}/publickeys reports for them. The keys of the accounts named in the request are replaced, and the keys of everybody else are left as they are, which makes the call idempotent for a given set of recipients while remaining a mutating one; sending no entry for a person does not revoke that person's key. The file has to lie in a private room, and every account named in the request has to have read access to it. The caller needs read access to the file and the right to create content in that room, which its members with editing rights and its admins have; a caller without those rights, a file outside a private room and a file that does not exist are all refused with 403. Read the result back with GET api/2.0/files/{fileId}/access.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the keys are issued for; it has to lie in a private room.	[required] [example: `12345`]
AccessRequestKeyDto	body	List	One key per account that is to open the file. The keys of the accounts named here are replaced and the keys of everybody else are left as they are, so sending no entry for a person does not revoke that person's key.	[optional]

Responses

Status code	Description	Type	Response headers
200	The file keys were stored	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not issue keys for this file, or the file is not in a private room	-	-
404	The file does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFileExternalLink

FileShareWrapper setFileExternalLink(id, FileLinkRequest)

PUT /api/2.0/files/file/{id}/links

Set a file external link

Creates an external link to a file, or changes or revokes an existing one, and answers with the link as it now stands. linkId decides which: an identifier that is not yet in use, the empty one included, creates a link, while the identifier of an existing link rewrites it, so the whole set of parameters is applied every time and a field left out is reset rather than kept. access carries the rights the link grants, and access set to the value that denies everything revokes the link instead - the answer is then empty, and a revoked primary link is not recreated by a later read. title names the link for the people who manage it, expirationDate limits its lifetime and is refused when it lies more than a few years ahead, password asks visitors for a secret, denyDownload leaves them with viewing only, internal admits signed-in members alone, and primary=true makes it the primary link of the file. The caller needs the right to share the file and is otherwise refused, an unknown file being answered as not found. The call is mutating.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file the link points at.	[required] [example: `1`]
FileLinkRequest	body	FileLinkRequest	The settings of the link. They are applied in full, so a field left out is reset rather than kept.	[required]

Responses

Status code	Description	Type	Response headers
200	The link as it now stands, or nothing when it was revoked	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFileOrder

FileIntegerWrapper setFileOrder(fileId, OrderRequestDto)

PUT /api/2.0/files/{fileId}/order

Set file order

Puts a file at a given position inside its folder and answers with the file, its order reporting where it now stands. Positions count from 1, and the file that held the wanted position, together with everything after it, is shifted to make room, so the numbering of a folder stays without gaps; a position beyond the end of the folder places the file last. The value may also be sent as a dotted path, as in 1.2.3, in which case only its last segment is read. Ordering is what the manual sorting of a room is built on, and it only means something in rooms whose contents are indexed - elsewhere the value is stored and ignored. The caller needs edit access to the file, which room managers, content creators and members with editing rights have; a member acting on somebody else's file, a guest and an anonymous caller are refused with 403, and an unknown file is answered with 404. The call is mutating and idempotent. To move several items in one go use PUT api/2.0/files/order.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to move.	[required] [example: `1`]
OrderRequestDto	body	OrderRequestDto	The position the file is to take.	[optional]

Responses

Status code	Description	Type	Response headers
200	The file with the position it now holds	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not reorder this file	-	-
404	The file does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileEntryIntegerArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFilesOrder

FileEntryIntegerArrayWrapper setFilesOrder(OrdersRequestDtoInteger)

PUT /api/2.0/files/order

Set order of files

Puts several files and folders at given positions in one go and answers with the entries that were moved, each with the position it now holds. Every item of items names an entry by its identifier and its kind - a file or a folder - and the position it is to take, counting from 1; a position may also be sent as a dotted path, as in 1.2.3, of which only the last segment is read. The items are applied one after another in the order they are sent, and each of them shifts its neighbours, so the result depends on that order; the whole request is not one transaction, and a failure in the middle leaves the items before it moved. Every item has to lie in a room the caller may administer, which the room admin and a DocSpace admin acting as room manager do: read-only access, a guest and an anonymous caller are refused, and an identifier that matches nothing is answered as not found. Ordering only means something in rooms whose contents are indexed. The call is mutating. For a single file use PUT api/2.0/files/{fileId}/order.

Parameters

Name	In	Type	Description	Notes
OrdersRequestDtoInteger	body	OrdersRequestDtoInteger		[optional]

Responses

Status code	Description	Type	Response headers
200	The files and folders that were moved, with the positions they now hold	FileEntryIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

startEditFile

StringWrapper startEditFile(fileId, StartEdit)

POST /api/2.0/files/file/{fileId}/startedit

Open an editing session

Opens an editing session on the file and answers with the document key that identifies it, the value an editor client passes to the document service in order to join the co-editing session for that exact revision. The file is marked as being edited for as long as the session lasts, which keeps it from being deleted or moved. With editingAlone=false the portal builds the editor configuration, requires write mode plus at least one of the edit, review, comment, form-filling or filter permissions, and asks the document service to start tracking the document. With editingAlone=true the caller claims the file for itself, and the call is refused with 403 when anybody is already editing it. The caller needs edit access: a member with read access, a guest and an anonymous caller whose external link does not grant editing are all refused. The call is mutating and not idempotent. Keep the session alive with GET api/2.0/files/file/{fileId}/trackeditfile, and end it by calling that operation with isFinish=true.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to open the editing session on. The caller needs edit access to it.	[required] [example: `1`]
StartEdit	body	StartEdit	The session options. The body is required even when it only carries the default, so send an empty object to open an ordinary co-editing session.	[required]

Responses

Status code	Description	Type	Response headers
200	The document key of the editing session	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot edit the file, or the file is already being edited and the session was claimed alone	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

startFillingFile

FileIntegerWrapper startFillingFile(fileId)

PUT /api/2.0/files/file/{fileId}/startfilling

Start filling a form

Marks a PDF form in a form-filling room as open for filling out and answers with the form file. The portal stores the filling properties on it - the room it belongs to, its title, the account that started it and the id it keeps as the original form - so that later submissions are collected against this form. The file has to be a PDF whose parent folder is a form-filling room; anything else is answered unchanged and nothing is stored. Access follows room membership rather than portal role: a member holding only form-filling access on the room may not start filling, and a caller with no access to the room at all is refused with 403 unless they can manage it, which the room owner, a room administrator and a DocSpace administrator can. The call is mutating and safe to repeat, since a repeat rewrites the same properties. Once a form is started, the answers submitted for it can be collected into a spreadsheet with POST api/2.0/files/file/{fileId}/xlsx.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The PDF form to open for filling. It has to be the form as it lies in the form-filling room itself, not a copy kept elsewhere and not a submitted result.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The form file, with the filling properties now stored on it	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller holds only form-filling access on the room, or no access to it at all	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

toggleFileFavorite

BooleanWrapper toggleFileFavorite(fileId, favorite)

GET /api/2.0/files/favorites/{fileId}

Set the file favorite status

Sets or clears the favorite mark of one file for the calling account: true adds the file to the favorites, false takes it out again. The call changes stored state even though it is a GET, so it is not one to issue speculatively; repeating it with the same value changes nothing further. The mark is personal, no other member sees it, and the file stays where it is stored. Read access is enough, so a room member with view-only rights and a guest may call it. The answer only echoes the value that was asked for: an identifier that resolves to nothing and a file the caller cannot read are skipped without a word, an encrypted file of a private room is never marked, and the requested value still comes back, so read the outcome from GET api/2.0/files/@favorites instead. A file moved to the Trash keeps its mark and is left out of that listing until it is restored. To mark several entries at once, or to mark folders, use POST api/2.0/files/favorites and DELETE api/2.0/files/favorites.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
favorite	query	Boolean	Which state to put the mark in: `true` adds the file to the favorites of the calling account, `false` removes it from them. Leaving the field out of the request removes the mark rather than setting it.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	Echo of the requested state, which does not prove that the mark was changed	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Changing the favorite mark is refused for the caller	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ItemKeyValuePairBooleanStringWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

trackEditFile

ItemKeyValuePairBooleanStringWrapper trackEditFile(fileId, tabId, docKeyForTrack, isFinish)

GET /api/2.0/files/file/{fileId}/trackeditfile

Track an editing session

Keeps an editing session on the file alive, or ends it; an editor client calls it repeatedly while a document is open. docKeyForTrack has to be the document key of the file as it currently stands, the value POST api/2.0/files/file/{fileId}/startedit returned, and a key matching neither the current revision nor the one being edited is refused with 403. tabId names the client tab that holds the session, so several tabs and several users are tracked on one file independently. Refreshing an entry requires one of the editing rights on the file - editing, reviewing, commenting, filling or filter editing - so a reader is refused. With isFinish=false the entry is refreshed and the file stays marked as being edited; with isFinish=true the entry for that tab is dropped and the other clients are told that editing has stopped. The call changes the tracking state and never the document, and repeating it is safe. It answers key true with an empty value whenever it succeeds, so a failure arrives as an error rather than as a false key. An anonymous caller is accepted only through an external share link.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose editing session is being tracked.	[required] [example: `1`]
tabId	query	UUID (uuid)	The client tab that holds the session, a value the client makes up once and repeats on every call about that tab. Two tabs sending different values are tracked as two sessions on the same file, while the all-zero value belongs to a session claimed for a single editor.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
docKeyForTrack	query	String	The document key of the revision being edited, as `POST api/2.0/files/file/{fileId}/startedit` returned it. It is checked against the file's current key on every call, so a key left over from an older revision is refused.	[optional] [example: `abc123`]
isFinish	query	Boolean	Ends the session for this tab and tells the other clients that editing has stopped. Left off, the session is refreshed and the file stays marked as being edited.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The session was refreshed or closed	ItemKeyValuePairBooleanStringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The document key does not match the revision being edited	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateFile

FileIntegerWrapper updateFile(fileId, UpdateFile)

PUT /api/2.0/files/file/{fileId}

Update a file

Renames a file, restores one of its versions, or both at once, and answers with the file as it now stands. A non-empty title renames the file, keeping the stored extension whatever the new title says, so a rename cannot change the format; an empty or missing title leaves the name alone. A lastVersion above 0 restores that version the way POST api/2.0/files/file/{fileId}/restoreversion does, storing its content again on top of the history, while 0 or less leaves the versions untouched and answers with the file as it is - which makes this operation a read of the file when both fields are left out. The caller needs edit access, and renaming somebody else's file additionally needs room-manager rights: a member or room admin with plain editing access, read-only access, a guest and a DocSpace admin who is not a member of the room are all refused with 403, while a content creator may rename a file of their own. The call is mutating. Renaming marks the file as new for everybody else who can read it.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to update.	[required] [example: `1`]
UpdateFile	body	UpdateFile	The new title and the version to restore.	[required]

Responses

Status code	Description	Type	Response headers
200	The file after the rename, the restore, or both	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not rename the file or change its version	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

FilesFoldersApi

checkUpload

STRINGArrayWrapper checkUpload(folderId, CheckUploadRequest)

POST /api/2.0/files/{folderId}/upload/check

Check for upload conflicts

Reports which of the submitted titles already belong to a file in the folder, so an upload can decide in advance whether to overwrite or to ask for another name. Only the clashing titles come back, unordered and without repetitions, and an empty array means every name is free. Matching is by title and ignores case, so a name that differs only in capitalisation is still reported; an existing file that is encrypted is left out, because an upload cannot take it over. The call changes nothing. It needs the same right as the upload itself, the right to add content to the folder, which room managers and content creators have and readers, editors and guests do not; an archived room, a section root and a folder the caller cannot write to are all refused, while an unknown folder is answered as missing. A request without filesTitle is rejected as an invalid request, an empty list is accepted and answers with an empty array.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder whose contents the names are tested against; take the id from a listing such as `GET api/2.0/files/@root`.	[required] [example: `1`]
CheckUploadRequest	body	CheckUploadRequest	The names to test against the files the folder already holds.	[required]

Responses

Status code	Description	Type	Response headers
200	The submitted titles that already belong to a file in the folder	STRINGArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

STRINGArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createFolder

FolderIntegerWrapper createFolder(folderId, CreateFolder)

POST /api/2.0/files/folder/{folderId}

Create a folder

Creates a folder inside the folder named in the path and answers with the folder as it was stored. The title is trimmed, may not be blank and is refused when it is longer than the limit the schema prints; titles are not required to be unique, so creating the same title twice leaves two folders side by side, which makes the call mutating and not idempotent. The caller needs the right to create content in the parent, which the room manager, a content creator and the owner of a personal section have; a member without that right, an archived parent, and a section root that only holds rooms - Rooms, Forms and AI agents - are all refused, as is a parent that does not exist. Rooms are not created here: use POST api/2.0/files/rooms for those, and this operation for ordinary folders within them. Members of the room are notified of the new folder. Read the identifier of the new folder from id and fill it with POST api/2.0/files/{folderId}/upload.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the request is addressed to: when a folder is created it is the parent that receives the new folder, and when a folder is renamed it is the folder that gets the new title.	[required] [example: `1`]
CreateFolder	body	CreateFolder	The title carried by the request body.	[required]

Responses

Status code	Description	Type	Response headers
200	The folder that was created	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createFolderPrimaryExternalLink

FileShareWrapper createFolderPrimaryExternalLink(id, FolderLinkRequest)

POST /api/2.0/files/folder/{id}/link

Create the folder primary external link

Answers with the primary external link of a folder or a room, creating it on the first call and returning the one that already exists afterwards, so the operation is idempotent in effect: a second call with other parameters does not reconfigure the existing link, and changing one is the business of PUT api/2.0/files/folder/{id}/links. The parameters therefore only shape the link at the moment it is born - access its rights, title its name, expirationDate its lifetime, which is unlimited here unless one is given, internal whether only signed-in members may follow it, denyDownload whether the contents may only be viewed, and password a secret to be asked for. Sending access with the value that grants nothing creates no link and answers with nothing. The caller needs the right to manage the links of the room the folder belongs to, which its manager and a portal administrator acting as room manager have, and a member with content-creator or read access is refused with 403; an unknown folder is answered with 404. Read the address from sharedTo.shareLink.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The folder or room the link belongs to.	[required] [example: `1`]
FolderLinkRequest	body	FolderLinkRequest	The link and the way it is to be shaped.	[required]

Responses

Status code	Description	Type	Response headers
200	The primary external link of the folder	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not manage the links of this folder	-	-
404	The folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createReportFolderHistory

DocumentBuilderTaskWrapper createReportFolderHistory(folderId, format, from, to)

POST /api/2.0/files/folder/{folderId}/log/report

Start the folder history report generation

Queues a background job that renders the history of a folder into a spreadsheet, or into a CSV file when format asks for one, and saves the result in the caller's My documents. The answer is the queued task, not the report: poll GET api/2.0/files/folder/{folderId}/log/report until isCompleted is true, then take the file from resultFileId, resultFileName and resultFileUrl, of which a CSV report fills only the last two. from and to limit the exported period; leaving both out exports the whole history. While a report for the same folder and caller is still running, this call joins it and answers with the running task instead of starting a second one, so retrying is safe. The caller needs read access to the folder and may not be a guest, and the portal plan has to include the audit feature - otherwise the call is refused, with 403 for the access rule and 404 for a folder that does not exist. Only a portal administrator gets the address, browser and platform columns. Give up a running report with DELETE api/2.0/files/folder/{folderId}/log/report.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder whose history is exported; the report covers the folder itself and the entries inside it.	[required] [example: `1`]
format	query	AuditReportFormat	The shape the report is written in: `Xlsx` produces a spreadsheet that is saved as a file of the portal, while `Csv` produces a comma-separated text file that is uploaded to My documents without being reported back with a file identifier.	[optional] [example: `Xlsx`] [enum: `0`, `1`]
from	query	Date (date-time)	The earliest moment an exported entry may have, read in the time zone of the portal; left out, the report starts at the oldest entry the portal still keeps.	[optional] [example: `2025-01-01T00:00:00`]
to	query	Date (date-time)	The latest moment an exported entry may have, read in the time zone of the portal; left out, the report ends at the newest entry.	[optional] [example: `2025-12-31T23:59:59`]

Responses

Status code	Description	Type	Response headers
200	The queued report task	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not export the history of this folder	-	-
404	The folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

deleteFolder

FileOperationArrayWrapper deleteFolder(folderId, DeleteFolder)

DELETE /api/2.0/files/folder/{folderId}

Delete a folder

Queues the deletion of one folder together with everything inside it, and answers with the file operations of the caller, the one just created among them. The folder is not gone when the response arrives: poll GET api/2.0/files/fileops until the operation reports finished, and read its error to learn whether the deletion succeeded. By default the folder is moved to the Trash section, from where it can be restored; immediately=true discards it for good instead, and inside a room, where there is no Trash, deletion is always final. deleteAfter=true postpones the deletion until the editing sessions on the contents have ended, so files somebody is working on are not pulled away. The caller needs the right to delete the folder, which the room manager, a portal administrator acting as room manager and a content creator acting on a folder of their own have; editing access alone, read access and a guest are refused. The call is destructive. To delete several items at once use PUT api/2.0/files/fileops/delete.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder to delete, together with everything it holds.	[required] [example: `10`]
DeleteFolder	body	DeleteFolder	How the deletion is to be carried out.	[required]

Responses

Status code	Description	Type	Response headers
200	The file operations of the caller, including the deletion just queued	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

XlsxReportResponseWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

generateXlsxByFolder

XlsxReportResponseWrapper generateXlsxByFolder(folderId)

POST /api/2.0/files/folder/{folderId}/xlsx

Generate XLSX report by folder

Rebuilds the spreadsheet that gathers the answers submitted to a form, starting from the Complete folder that holds the filled copies. The answer names the original form the results belong to, says in isNewFile whether the spreadsheet is being created or an existing one rewritten in place, and carries the queued job in task; the file itself is not ready yet, so poll GET api/2.0/files/file/{fileId}/xlsx with the identifier of the form until the task reports completion. The folder has to be the Complete folder of a form-filling room and has to hold at least one submitted copy whose original form still exists, and the caller needs the right to maintain that form, which the room manager has. A folder that does not exist, or one that holds nothing to report on, is answered with 404, and a folder of the wrong kind or a caller without those rights with 403. The call is mutating: it writes the results file of the form.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the operation acts on. Take the identifier from a listing such as `GET api/2.0/files/@root` or `GET api/2.0/files/{folderId}`: a folder stored in the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The queued report task together with the form the answers belong to	XlsxReportResponseWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The folder is not a completed-forms folder, or the caller may not maintain the form	-	-
404	The folder, the submitted copy or the original form was not found	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFavoritesFolder

FolderContentIntegerWrapper getFavoritesFolder(userIdOrGroupId, filterType, count, startIndex, sortBy, sortOrder, filterValue)

GET /api/2.0/files/@favorites

Get the Favorites section

Returns the caller's own Favorites section: the files and folders this account has marked as favorite, together with the section folder itself. Favorites are per-account, so the entries another member marked are not listed here, and a guest sees only their own, usually empty, list. Mark a single file with GET api/2.0/files/favorites/{fileId}, or add and remove batches of files and folders with POST api/2.0/files/favorites and DELETE api/2.0/files/favorites. Nothing in the section is modified, though passing sortBy saves the requested order as the default order for this account. Entries the caller can no longer read, and entries that have been moved to the Trash section, drop out of the listing even though their favorite mark stays, so the section can shrink without an explicit unmark. folders and files hold one page of the section, total counts the entries matching the request before count and startIndex are applied, and current describes the section folder itself.

Parameters

Name	In	Type	Description	Notes
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the entries authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list everything the caller can read.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the listing to a single kind of entry, such as documents, images or one type of room. Omit it to list every kind the section holds.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
count	query	Integer (int32)	The size of one page of section content. Pair it with `startIndex` to walk the listing, and compare the two with `total` in the response to see when the last page has been read.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries to skip before the returned page begins; add `count` to it to ask for the next page.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the section is filtered by: it is matched as a substring of entry titles and, for files, against the indexed document content as well. Omit it to list the section unfiltered.	[optional] [example: `My Document`]

Responses

Status code	Description	Type	Response headers
200	The Favorites section with one page of the entries the caller marked as favorite	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to read the Favorites section	-	-
404	The Favorites section could not be resolved for this account	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FilesStatisticsResultWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFilesUsedSpace

FilesStatisticsResultWrapper getFilesUsedSpace()

GET /api/2.0/files/filesusedspace

Get used space of files

Reports how much storage the portal spends on documents, split by section - My documents, Trash, Rooms, Archive and, where the feature is on, AI agents - each entry naming the section and the space it takes in bytes. The figures cover the whole portal rather than the calling account, and moving an entry between sections moves its space with it, which is why deleting a file to the Trash does not free anything until the Trash is emptied. Only a caller who may change portal settings, that is the owner and the portal administrators, is allowed here; a room administrator, an ordinary member and a guest are all refused. The call is read-only, takes no parameters and answers with the sections in a fixed order. The quota of the portal as a whole, storage outside documents included, is not part of this answer.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The space taken by documents in each section, in bytes	FilesStatisticsResultWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolder

FormsItemArrayWrapper getFolder(folderId)

GET /api/2.0/files/{folderId}/formfilter

Get folder form filter

Lists the fields the completed forms of a form-filling room carry, each of them a key and the kind of value behind it, so that a client can offer them as filters. Feed a pair from this list back as formsItemKey and formsItemType of GET api/2.0/files/{folderId} to keep only the completed forms whose field of that name holds a value. The fields are read from the search index of one of the forms already gathered, so they appear once indexing has caught up with the first submission. Only the Complete folder of a form-filling room carries such fields: for any other folder, for a folder that does not exist and for one that has been deleted the answer is an empty list rather than a refusal, and the same holds while nothing has been submitted yet. The operation reads the index alone, changes nothing and needs no authorization.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the operation acts on. Take the identifier from a listing such as `GET api/2.0/files/@root` or `GET api/2.0/files/{folderId}`: a folder stored in the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The form fields that can be used as filters, empty when the folder carries none	FormsItemArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FormsItemArrayWrapper

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderByFolderId

FolderContentIntegerWrapper getFolderByFolderId(folderId, userIdOrGroupId, sharedBy, filterType, roomId, folderType, excludeSubject, applyFilterOption, withSubFolders, extension, searchArea, formsItemKey, formsItemType, count, startIndex, sortBy, sortOrder, filterValue, Location)

GET /api/2.0/files/{folderId}

Get a folder by ID

Returns one page of the contents of a folder - its subfolders in folders, its files in files, the folder itself in current and the chain of parents in pathParts - and is the operation a client browses the file tree with. filterType, filterValue, extension, userIdOrGroupId, sharedBy and folderType narrow what is listed, applyFilterOption decides whether those filters bite on the files, on the folders or on both, and withSubFolders, which is on unless it is switched off, lets a narrowed request descend through the whole subtree instead of the top level alone. filterValue is matched against titles and against indexed document content, and indexing is asynchronous, so a file uploaded a moment ago can be missing from a search for a short while. count and startIndex page through the result while total counts everything that matches, and sortBy with sortOrder both order the page and are saved as the default order of the account. Reading a room or an ordinary folder clears its new-item marks for the caller. A caller who may not read the folder is answered with 403, and a folder that does not exist with 404.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder whose contents are listed. Each section root has an operation of its own, such as `GET api/2.0/files/@my`, and every other folder is opened by the identifier a listing gave for it.	[required] [example: `1`]
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the entries authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list everything the caller can read.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
sharedBy	query	UUID (uuid)	Restricts the listing to the entries this member shared, which narrows a shared listing down to what one person handed out.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the listing to a single kind of entry, such as documents, spreadsheets, images or one type of room. Omit it to list every kind the folder holds.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
roomId	query	Integer (int32)	Keeps only the entries that lie in this room, which matters when the listing being read gathers entries from more than one of them.	[optional] [example: `1`]
folderType	query	List	Keeps only the folders of these kinds, each given as the number of a folder type; it is how a listing is narrowed down to, say, the form-filling folders of a room.	[optional] [example: `[2]`] [enum: `0`, `1`, `2`, `3`, `5`, `6`, `8`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `19`, `20`, `21`, `22`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `33`, `34`, `35`, `36`]
excludeSubject	query	Boolean	Turns `userIdOrGroupId` around: with true the entries of that member or group are the ones left out, with false they are the only ones kept.	[optional] [example: `false`]
applyFilterOption	query	ApplyFilterOption	Chooses which half of the listing `filterType` and `filterValue` are applied to: with `Files` the folders come back unfiltered, with `Folders` the files do, and with `All` both halves are filtered.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
withSubFolders	query	Boolean	Whether a narrowed request reaches into the subfolders: with true, which is what an omitted parameter means, matching entries are gathered from the whole subtree, with false only the top level is read. It makes a difference only once `filterType`, `userIdOrGroupId` or `filterValue` narrows the request, because an unfiltered listing always shows the top level alone.	[optional] [example: `true`]
extension	query	String	Keeps only the files carrying one of these extensions, several of them separated by commas; the leading dot is optional.	[optional] [example: `docx,pdf`]
searchArea	query	SearchArea	Which area a listing that spans several of them is taken from - the active rooms, the archive, the room templates or the form-filling rooms. A folder that belongs to one area only settles the area itself and ignores the parameter.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`]
formsItemKey	query	String	Keeps only the completed forms whose form field of this name holds a value. Take the name from `GET api/2.0/files/{folderId}/formfilter`, and use it in the folder that gathers the completed copies of a form-filling room.	[optional] [example: `first_name`]
formsItemType	query	String	The kind of the form field named by `formsItemKey`, taken from the same list; the two are sent together.	[optional] [example: `text`]
count	query	Integer (int32)	The size of one page of the listing. Pair it with `startIndex` to walk through the result, and compare the two with `total` in the response to see when the last page has been read.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries to skip before the returned page begins; add `count` to it to ask for the next page.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the listing is filtered by: it is matched as a substring of entry titles and, for files, against the indexed document content as well. Omit it to list the folder unfiltered.	[optional] [example: `My Document`]
Location	query	Location	Where the entries of a tag-based listing have to live to be kept: `Room` keeps what lies in a room, `Documents` what lies in a personal section, and `Link` what was reached through an external link that is still valid. It shapes the Favorites and Recent listings and does nothing in an ordinary folder.	[optional] [example: `1`] [enum: `1`, `2`, `3`]

Responses

Status code	Description	Type	Response headers
200	One page of the folder contents, with the folder itself and the chain of its parents	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read this folder	-	-
404	The folder does not exist	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderHistory

HistoryArrayWrapper getFolderHistory(folderId, fromDate, toDate, count, startIndex)

GET /api/2.0/files/folder/{folderId}/log

Get folder history

Lists what has happened to a folder and to the entries inside it - creations, renames, uploads, moves, deletions and changes of access - each record naming the action, the moment it happened and the member behind it. Records that belong to one action are grouped, so a batch arrives as a single entry carrying the rest of itself in related, and the list runs from the most recent record backwards. fromDate and toDate narrow the period, startIndex and count page through the result, and the number of records matching the request is reported in the response headers rather than in the body. Any member who can read the folder may read its history; a caller without access is answered with 403 and a folder that does not exist with 404. When the folder is a form-filling folder the caller reached through a filling invitation, the history is narrowed to what that caller may see. The call is read-only. To take the same history away as a spreadsheet, start a report with POST api/2.0/files/folder/{folderId}/log/report.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder whose activity log is read; the log covers the folder itself and the entries inside it.	[required] [example: `1`]
fromDate	query	Date (date-time)	The earliest moment an entry may have, read in the time zone of the portal; left out, the log starts at the oldest entry the portal still keeps.	[optional] [example: `2025-01-01T00:00:00.0000000Z`]
toDate	query	Date (date-time)	The latest moment an entry may have, read in the time zone of the portal; left out, the log ends at the newest entry.	[optional] [example: `2025-12-31T23:59:59.0000000Z`]
count	query	Integer (int32)	How many entries one page holds. The number of entries that match the query is reported in the response headers, not in the body.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries to skip before the page begins, counted from the newest one, so pages are taken by adding the page size to it.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	One page of the folder history, the most recent record first	HistoryArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read this folder	-	-
404	The folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

HistoryArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderInfo

FolderIntegerWrapper getFolderInfo(folderId)

GET /api/2.0/files/folder/{folderId}

Get folder information

Returns one folder as an object - its title, its parent, the moments it was created and last changed, the access the caller has to it, the number of items that are new for them, and the room settings when the folder is a room - without listing anything inside it. Use it to resolve a folder identifier into something displayable, and GET api/2.0/files/{folderId} when the contents are what is wanted; unlike that operation, this one leaves the new-item marks of the folder alone. Any member who can read the folder may call it, and an anonymous caller only through an external link that grants access, everybody else being refused; a folder that does not exist is answered as not found. The call is read-only. The chain of parents above the folder is not part of the answer and is read with GET api/2.0/files/folder/{folderId}/path.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the operation acts on. Take the identifier from a listing such as `GET api/2.0/files/@root` or `GET api/2.0/files/{folderId}`: a folder stored in the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The folder	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderLinks

FileShareArrayWrapper getFolderLinks(id)

GET /api/2.0/files/folder/{id}/links

Get folder external links

Lists the external links of a folder or a room, each with its identifier, title, address, rights, expiration date, password flag and download restriction, the primary link among them once it exists. At most the first hundred links are answered and the number returned is reported in the response headers; there are no paging parameters here. A folder that has never been shared by link answers with an empty list, and so does a member who may read the folder but not manage its links - the empty answer therefore means nothing to show you rather than no links exist. A member without access to the room is refused, an anonymous caller is rejected, and a folder that does not exist is answered as not found. The call is read-only. Take an identifier from here to PUT api/2.0/files/folder/{id}/links to change or remove that link, and read the primary one alone with GET api/2.0/files/folder/{id}/link.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The folder or room whose external links are listed.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The external links of the folder the caller may manage	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderPath

FileEntryBaseArrayWrapper getFolderPath(folderId)

GET /api/2.0/files/folder/{folderId}/path

Get the folder path

Returns the chain of folders that leads to the folder named in the path, ordered from the section root down to the folder itself, which is the last entry. It is what a breadcrumb trail is built from, and it also tells a client which section - a room, the personal section, the archive - a bare folder identifier belongs to. Only the folders the caller may see are part of the chain, so a member who was given access to a folder deep inside a room gets a shorter path than the room manager does. The caller needs read access to the folder and is otherwise answered with 403, while a folder that does not exist is answered as not found. The call is read-only and takes no paging parameters. To go the other way, from a folder down into its contents, call GET api/2.0/files/{folderId}.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the operation acts on. Take the identifier from a listing such as `GET api/2.0/files/@root` or `GET api/2.0/files/{folderId}`: a folder stored in the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The chain of folders leading to the folder, the section root first	FileEntryBaseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read this folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderPrimaryExternalLink

FileShareWrapper getFolderPrimaryExternalLink(id, count, startIndex)

GET /api/2.0/files/folder/{id}/link

Get the folder primary external link

Answers with the primary external link of a folder or a room - the one the Copy link action of a client hands out - with its address in sharedTo.shareLink, its rights in access, and its title, expiration date, password flag and download restriction beside them. The link is created on the first read if the folder has none, with read rights, no password and no expiry, so this operation mutates on that first call and is a plain read afterwards; repeated calls answer with the same link identifier. The caller needs the right to manage the links of the room the folder belongs to, which its manager and a portal administrator acting as room manager have; a member with read access alone is refused with 403 and an anonymous caller is rejected, while a link that was deliberately revoked is answered with 404 rather than being recreated. The paging parameters are accepted for compatibility and leave the single link answered here unchanged. Every external link of the same folder is listed by GET api/2.0/files/folder/{id}/links.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The folder or room the operation addresses. A folder stored on the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `10`]
count	query	Integer (int32)	How many entries at most to answer with, in the operations of this folder that return a list; an operation that answers with a single object is not affected by it.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries of such a list to skip before answering, used together with `count` to walk through it page by page.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	The primary external link of the folder	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not manage the links of this folder	-	-
404	The folder does not exist, or its primary link was revoked	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolders

FileEntryBaseArrayWrapper getFolders(folderId)

GET /api/2.0/files/{folderId}/subfolders

Get subfolders

Lists the folders that sit directly inside the folder named in the path, ordered by title, without their own contents and without the files that lie beside them. The whole list arrives at once - there are no paging or filtering parameters here - so for a large folder, or when the files are wanted as well, use GET api/2.0/files/{folderId}, which pages and filters. A folder that holds no subfolders answers with an empty list. The caller needs read access to the folder, and only the subfolders they may see are listed, so a member of a room can get fewer entries than its manager; a caller without access is answered with 403, and a folder that does not exist, or one that has been deleted for good, is answered as not found. The call is read-only and leaves the new-item marks of the folder alone.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the operation acts on. Take the identifier from a listing such as `GET api/2.0/files/@root` or `GET api/2.0/files/{folderId}`: a folder stored in the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The direct subfolders of the folder, ordered by title	FileEntryBaseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read this folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFormsFolder

FolderContentIntegerWrapper getFormsFolder(userIdOrGroupId, filterType, count, startIndex, sortBy, sortOrder, filterValue)

GET /api/2.0/files/@forms

Get the Forms section

Returns the Forms section: the flat list of form-filling rooms the caller may read. Such rooms are stored under the Rooms tree but are surfaced only here, so GET api/2.0/files/rooms leaves them out of the active area and lists them when searchArea names the forms area instead. The section is not expanded into room content, so folders carries the rooms while files comes back empty; to read what is inside one of them, call GET api/2.0/files/{folderId} with the room identifier. Nothing is modified, though passing sortBy saves the requested order as the default order for this account. filterType, filterValue, userIdOrGroupId and the sorting parameters narrow and order the room list, count and startIndex page through it, total reports how many rooms match the request in full, and current describes the section folder itself.

Parameters

Name	In	Type	Description	Notes
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the entries authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list everything the caller can read.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the listing to a single kind of entry, such as documents, images or one type of room. Omit it to list every kind the section holds.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
count	query	Integer (int32)	The size of one page of section content. Pair it with `startIndex` to walk the listing, and compare the two with `total` in the response to see when the last page has been read.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries to skip before the returned page begins; add `count` to it to ask for the next page.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the section is filtered by: it is matched as a substring of entry titles and, for files, against the indexed document content as well. Omit it to list the section unfiltered.	[optional] [example: `My Document`]

Responses

Status code	Description	Type	Response headers
200	The Forms section with one page of the form-filling rooms available to the caller	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to read the Forms section	-	-
404	The Forms section could not be resolved for this account	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getMyFolder

FolderContentIntegerWrapper getMyFolder(userIdOrGroupId, filterType, applyFilterOption, count, startIndex, sortBy, sortOrder, filterValue)

GET /api/2.0/files/@my

Get the My documents section

Returns the contents of the caller's My documents section, the personal storage that belongs to this account alone and stays invisible to other members until something in it is shared explicitly. Any authenticated member that has a personal section can read it; guest accounts are not given one, and the call then answers 404. Nothing in the section is modified, though passing sortBy saves the requested order as the default order for this account. Without a filter only the top level of the section is listed; as soon as filterType, userIdOrGroupId or filterValue narrows the request, the search descends through the whole subtree. filterValue is matched against titles and against indexed document content, and the index is written asynchronously, so a file uploaded a moment ago can be missing from a search for a short while. folders and files hold one page of the result, total counts everything that matches before count and startIndex are applied, and current describes the section folder. To open a folder inside the section, call GET api/2.0/files/{folderId} with its identifier.

Parameters

Name	In	Type	Description	Notes
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the entries authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list everything the caller can read.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the listing to a single kind of entry, such as documents, images or one type of room. Omit it to list every kind the section holds.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
applyFilterOption	query	ApplyFilterOption	Chooses which half of the listing `filterType` and `filterValue` are applied to: with `Files` the folders come back unfiltered, with `Folders` the files do, and with `All` both halves are filtered.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
count	query	Integer (int32)	The size of one page of section content. Pair it with `startIndex` to walk the listing, and compare the two with `total` in the response to see when the last page has been read.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries to skip before the returned page begins; add `count` to it to ask for the next page.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the section is filtered by, matched as a substring of entry titles. Omit it to list the section unfiltered.	[optional] [example: `My Document`]

Responses

Status code	Description	Type	Response headers
200	The My documents section with one page of its contents	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to read the My documents section	-	-
404	This account has no personal section	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getNewFolderItems

FileEntryBaseArrayWrapper getNewFolderItems(folderId)

GET /api/2.0/files/{folderId}/news

Get new folder items

Lists the entries of a folder that are new for the calling member - the files and folders created or changed there since they last opened it - ordered from the most recently changed backwards. It is what the badge of a room is filled from, and it is personal: two members of the same room get different answers. Reading this list does not clear the marks, so the same entries come back until the folder itself is opened with GET api/2.0/files/{folderId}, which does clear them. A folder with nothing new answers with an empty list, and marks disappear on their own when the entry behind them is deleted or moved out of reach. The caller needs read access to the folder and is otherwise answered with 403. The whole list arrives at once, without paging or filtering, and the call is read-only.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the operation acts on. Take the identifier from a listing such as `GET api/2.0/files/@root` or `GET api/2.0/files/{folderId}`: a folder stored in the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The entries of the folder that are new for the caller	FileEntryBaseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read this folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRecentFolder

FolderContentIntegerWrapper getRecentFolder(userIdOrGroupId, filterType, excludeSubject, applyFilterOption, searchArea, extension, count, startIndex, sortBy, sortOrder, filterValue)

GET /api/2.0/files/recent

Get the Recent section

Returns the Recent section: the files the calling account has opened lately. The section holds files only, so folders comes back empty, and it is personal, so another member's history is not visible here. A file is added when it is opened and can also be added explicitly with POST api/2.0/files/file/{fileId}/recent; DELETE api/2.0/files/recent clears the whole history, and PUT api/2.0/files/displayrecent switches the section on and off for the account, which also decides whether GET api/2.0/files/@root includes it. Nothing in the section is modified, though passing sortBy saves the requested order as the default order for this account. The listing is ordered by the moment the caller last opened each file, newest first, and sortBy and sortOrder do not change that order. files holds one page, total counts the files matching the request before count and startIndex are applied, and current describes the section folder itself.

Parameters

Name	In	Type	Description	Notes
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the files authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list the whole history.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the listing to a single kind of file, such as documents, spreadsheets or images. Omit it to list every kind the history holds.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
excludeSubject	query	Boolean	Inverts `userIdOrGroupId`: with `true` the files of that member or group are the ones left out of the listing instead of the only ones kept.	[optional] [example: `false`]
applyFilterOption	query	ApplyFilterOption	Chooses which half of a listing `filterType` and `filterValue` are applied to. The Recent section holds files only, so the value does not change what comes back.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
searchArea	query	SearchArea	The area a listing is taken from. The Recent section is assembled from the caller's own open history rather than from an area, so the value does not change which files are returned.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`]
extension	query	List	The file extensions the listing is limited to, matched against the end of the file name. The leading dot is optional, and the parameter is repeated once per extension.	[optional] [example: `.docx`]
count	query	Integer (int32)	The size of one page of section content. Pair it with `startIndex` to walk the listing, and compare the two with `total` in the response to see when the last page has been read.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries to skip before the returned page begins; add `count` to it to ask for the next page.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place. The Recent section keeps its own newest-first order, so the value does not reorder this listing.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account. The Recent section keeps its own newest-first order, so the value does not reorder this listing.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the history is filtered by: it is matched as a substring of file titles and against the indexed document content as well. Omit it to list the whole history.	[optional] [example: `My Document`]

Responses

Status code	Description	Type	Response headers
200	The Recent section with one page of the files the caller opened lately	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to read the Recent section	-	-
404	The Recent section could not be resolved for this account	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getReportFolderHistory

DocumentBuilderTaskWrapper getReportFolderHistory(folderId)

GET /api/2.0/files/folder/{folderId}/log/report

Get the folder history report generation status

Reports how far the history report of a folder has got, and is the operation to poll after POST api/2.0/files/folder/{folderId}/log/report has queued one. percentage climbs to 100, isCompleted turns true when the job is over however it ended, error carries the reason when it failed, and resultFileId, resultFileName and resultFileUrl name the file that was saved in the caller's My documents - a CSV report leaving the identifier empty. An empty answer means there is no report for this folder and caller, either because none was started or because a finished one has already been picked up by an earlier poll. The caller needs read access to the folder and may not be a guest, and the portal plan has to include the audit feature; a caller who fails the access rule is answered with 403 and a folder that does not exist with 404. The call is read-only, and each caller sees only their own report.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder whose history report is being polled. It is the folder that was passed to the operation that started the report.	[required]

Responses

Status code	Description	Type	Response headers
200	The state of the report task, or nothing when there is none	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not export the history of this folder	-	-
404	The folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FolderContentIntegerArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRootFolders

FolderContentIntegerArrayWrapper getRootFolders(userIdOrGroupId, filterType, withoutTrash, count, startIndex, sortBy, sortOrder, filterValue)

GET /api/2.0/files/@root

Get filtered sections

Returns every top-level section the calling account can see in one response, each of them a full section object carrying its own first page of content: Favorites, Recent, Shared with me, My documents, Trash, Rooms, Forms, Archive and, while AI access is enabled for the portal, AI agents. A section is left out when the account has none of it, which is why a guest gets no personal section, and Recent is listed only while it is switched on with PUT api/2.0/files/displayrecent. Pass withoutTrash=true to drop the Trash section. The filters, count and startIndex are applied to each section separately, so count=1 returns one entry per section and every section reports its own total. Because it builds the content of all of them, this is the most expensive listing in the module: when a single section is enough, read it directly, for example with GET api/2.0/files/@my. The call modifies nothing in the sections and leaves their new-item badges untouched, though passing sortBy saves the requested order as the default order for this account.

Parameters

Name	In	Type	Description	Notes
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the entries authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list everything the caller can read.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the content listed inside every returned section to a single kind of entry, such as documents, images or one type of room. Omit it to list every kind the sections hold.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
withoutTrash	query	Boolean	Set it to `true` to leave the Trash section out of the returned set of sections; with `false`, or when the parameter is omitted, the section is returned whenever the account has one of its own.	[optional] [example: `false`]
count	query	Integer (int32)	The size of the content page returned for each section separately, so a value of 1 yields one entry per section rather than one entry in total.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries skipped in each section before its page begins; add `count` to it to ask for the next page of every section.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the content of every section is filtered by: it is matched as a substring of entry titles and, for files, against the indexed document content as well. Omit it to list the sections unfiltered.	[optional] [example: `My Document`]

Responses

Status code	Description	Type	Response headers
200	The sections available to the caller, each with one page of its content	FolderContentIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to read one of the sections	-	-
404	One of the sections could not be resolved for this account	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getTrashFolder

FolderContentIntegerWrapper getTrashFolder(userIdOrGroupId, filterType, applyFilterOption, count, startIndex, sortBy, sortOrder, filterValue)

GET /api/2.0/files/@trash

Get the Trash section

Returns the caller's Trash section: the files and folders this account has deleted, kept there until they are restored or discarded. Each member has a Trash of their own and sees only what they deleted themselves. Restore an entry by moving it back with PUT api/2.0/files/fileops/move, or discard the whole section with PUT api/2.0/files/fileops/emptytrash; both start a background operation that is polled through GET api/2.0/files/fileops. This call itself modifies nothing, though passing sortBy saves the requested order as the default order for this account. Only the top level of the section is listed, so the contents of a deleted folder are not expanded into it, and filterValue is matched against titles alone here rather than against document content. folders and files hold one page of the result, total counts everything that matches before count and startIndex are applied, and current describes the section folder. An account that is given no Trash of its own, an outsider for instance, receives 404.

Parameters

Name	In	Type	Description	Notes
userIdOrGroupId	query	UUID (uuid)	Restricts the listing to the entries authored by this portal member, or by the members of this group; the same parameter accepts either kind of identifier. Omit it to list everything the caller can read.	[optional] [example: `00000000-0000-0000-0000-000000000000`]
filterType	query	FilterType	Narrows the listing to a single kind of entry, such as documents, images or one type of room. Omit it to list every kind the section holds.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `7`, `8`, `9`, `10`, `11`, `12`, `13`, `14`, `17`, `20`, `22`, `23`, `24`, `25`, `26`]
applyFilterOption	query	ApplyFilterOption	Chooses which half of the listing `filterType` and `filterValue` are applied to: with `Files` the folders come back unfiltered, with `Folders` the files do, and with `All` both halves are filtered.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
count	query	Integer (int32)	The size of one page of section content. Pair it with `startIndex` to walk the listing, and compare the two with `total` in the response to see when the last page has been read.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	The number of matching entries to skip before the returned page begins; add `count` to it to ask for the next page.	[optional] [example: `0`]
sortBy	query	String	The name of the field the entries are ordered by, matched case-insensitively against the file sort fields: `DateAndTime`, `AZ`, `Size`, `Author`, `Type`, `New`, `DateAndTimeCreation`, `RoomType`, `Tags`, `Room`, `CustomOrder`, `LastOpened` and `UsedSpace`. A recognized value is also saved as the default order of the account and reused by later listings that omit the parameter, while a value matching none of the fields leaves that saved order in place.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction in which the `sortBy` field is ordered. It is saved together with `sortBy` as the default order of the account.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	The search string the section is filtered by, matched as a substring of entry titles. Omit it to list the section unfiltered.	[optional] [example: `My Document`]

Responses

Status code	Description	Type	Response headers
200	The Trash section with one page of the entries the caller deleted	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to read the Trash section	-	-
404	This account has no Trash section	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

insertFile

FileIntegerWrapper 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	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot add content to this folder	-	-
404	No folder with the specified ID	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

insertFileToMyFromBody

FileIntegerWrapper insertFileToMyFromBody(File, Title, CreateNewIfExist, KeepConvertStatus, Stream.CanRead, Stream.CanWrite, Stream.CanSeek, Stream.CanTimeout, Stream.Length, Stream.Position, Stream.ReadTimeout, Stream.WriteTimeout)

POST /api/2.0/files/@my/insert

Insert a file into My documents

Stores one file in the caller's own My documents section, the personal storage every portal member has, and returns the stored file. The destination takes no identifier: it is resolved from the calling account and created on first use, while a guest account has none and is answered as missing (404). Send the content as a multipart/form-data part or as the raw request body, and name it with title, which wins over the name of the uploaded part and has invalid characters replaced before storing. The call is not idempotent: by default a file of the same title is overwritten as a new version, while createNewIfExist=true stores a separate copy under a title made unique with a numeric suffix; a title held by a file that is locked or open in the editor cannot be overwritten either, and a second file appears under the same title. Formats listed in extsMustConvert of GET api/2.0/files/settings are converted after the response is sent; keepConvertStatus=true keeps that result readable through GET api/2.0/files/file/{fileId}/checkconversion, which otherwise drops it. Files over the single-request size limit or the account's storage quota are refused: send those through POST api/2.0/files/{folderId}/upload/create_session, and use POST api/2.0/files/{folderId}/insert for any other destination.

Parameters

Name	In	Type	Description	Notes
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]
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]
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]
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]
Stream.CanRead	form	Boolean		[optional]
Stream.CanWrite	form	Boolean		[optional]
Stream.CanSeek	form	Boolean		[optional]
Stream.CanTimeout	form	Boolean		[optional]
Stream.Length	form	Long (int64)		[optional]
Stream.Position	form	Long (int64)		[optional]
Stream.ReadTimeout	form	Integer (int32)		[optional]
Stream.WriteTimeout	form	Integer (int32)		[optional]

Responses

Status code	Description	Type	Response headers
200	The stored file, with the identifier, version and title it was saved under	FileIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Creating a file in the personal section is not allowed for this account	-	-
404	The caller has no personal section, so there is nothing to store the file in	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

renameFolder

FolderIntegerWrapper renameFolder(folderId, CreateFolder)

PUT /api/2.0/files/folder/{folderId}

Rename a folder

Gives a folder a new title and answers with the folder as it now stands. The title is trimmed, may not be blank and is refused when it is longer than the limit the schema prints; a title that matches the current one leaves the folder untouched, and titles need not be unique among the neighbours. The caller needs the right to rename the folder, which the room manager, a content creator acting on a folder of their own and the owner of a personal section have, while a guest is refused with 403 whatever their access; a folder in the Trash section or in an archived room cannot be renamed either, and a folder that does not exist is answered as not found. A room may be renamed here as well, in which case the caller needs the right to edit the room, and PUT api/2.0/files/rooms/{id} is the operation that changes its other settings. The call is mutating and idempotent; on a folder stored in a connected third-party account the identifier of the folder may change with the title.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the request is addressed to: when a folder is created it is the parent that receives the new folder, and when a folder is renamed it is the folder that gets the new title.	[required] [example: `1`]
CreateFolder	body	CreateFolder	The title carried by the request body.	[required]

Responses

Status code	Description	Type	Response headers
200	The folder with its new title	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not rename this folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFolderOrder

FolderIntegerWrapper setFolderOrder(folderId, OrderRequestDto)

PUT /api/2.0/files/folder/{folderId}/order

Set folder order

Puts a folder at a given position among the entries of its parent and answers with the folder, its order reporting where it now stands. Positions count from 1, and the entry that held the wanted position, together with everything after it, is shifted to make room, so the numbering of the parent stays without gaps; a position beyond the end places the folder last. The value may also be sent as a dotted path, as in 1.2.3, in which case only its last segment is read. Ordering is what the manual arrangement of a room is built on, and it only means something in rooms whose contents are indexed - elsewhere the value is stored and ignored. The caller needs edit access to the folder, which room managers and content creators have, and a member without it is refused, while a folder that does not exist is answered as not found. The call is mutating and idempotent. To move several entries in one go use PUT api/2.0/files/order.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder to move.	[required] [example: `1`]
OrderRequestDto	body	OrderRequestDto	The position the folder is to take.	[optional]

Responses

Status code	Description	Type	Response headers
200	The folder with the position it now holds	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFolderPrimaryExternalLink

FileShareWrapper setFolderPrimaryExternalLink(id, FolderLinkRequest)

PUT /api/2.0/files/folder/{id}/links

Set the folder external link

Creates an external link to a folder or a room, or changes or revokes an existing one, and answers with the link as it now stands. linkId decides which: an identifier that is not yet in use, the empty one included, creates a link, while the identifier of an existing link rewrites it, so the whole set of parameters is applied every time and a field left out is reset rather than kept. access carries the rights the link grants, and access set to the value that denies everything revokes the link instead - the answer is then empty, and a revoked primary link is not recreated by a later read. title names the link for the people who manage it, expirationDate limits its lifetime and is ignored when it lies in the past, password asks visitors for a secret, denyDownload leaves them with viewing only, internal admits signed-in members alone, and primary=true makes it the primary link of the folder. The caller needs the right to manage the links of the room, which its manager and a portal administrator acting as room manager have; anyone else is refused and an unknown folder is answered as not found. The call is mutating.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The folder or room the link belongs to.	[required] [example: `1`]
FolderLinkRequest	body	FolderLinkRequest	The link and the way it is to be shaped.	[required]

Responses

Status code	Description	Type	Response headers
200	The link as it now stands, or nothing when it was revoked	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

terminateReportFolderHistory

terminateReportFolderHistory(folderId)

DELETE /api/2.0/files/folder/{folderId}/log/report

Terminate the folder history report generation

Gives up the history report the caller has started for a folder with POST api/2.0/files/folder/{folderId}/log/report. The request only asks the background worker to stop, and the answer carries no body, so a following GET api/2.0/files/folder/{folderId}/log/report is what shows the task ending as cancelled. Asking to terminate when nothing is running is accepted and changes nothing, which makes the call safe to repeat. A report that has already finished is not undone by this call and its file stays in My documents. The caller needs read access to the folder and may not be a guest, and the portal plan has to include the audit feature; a caller who fails the access rule is answered with 403 and a folder that does not exist with 404. Each caller can only terminate their own report.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder whose running history report is to be given up. It is the folder that was passed to the operation that started the report.	[required]

Responses

Status code	Description	Type	Response headers
200	The request to stop the report was accepted	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not export the history of this folder	-	-
404	The folder does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

uploadFile

FileIntegerArrayWrapper uploadFile(folderId, createNewIfExist, storeOriginalFile, keepConvertStatus, File)

POST /api/2.0/files/{folderId}/upload

Upload a file

Stores a file in the folder named by the path in a single multipart request, taking its name from the uploaded part; use POST api/2.0/files/{folderId}/insert when the name has to be given separately or the content is sent as a raw body. The answer is a list that always holds exactly one file. 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. storeOriginalFile reaches further than this call, because it saves the setting on the calling account, the same one PUT api/2.0/files/storeoriginal writes, and it stays in force for later uploads. 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. A request without a file is rejected as invalid, and a payload above the portal upload limit is refused.

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`]
createNewIfExist	query	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] [example: `true`]
storeOriginalFile	query	Boolean	Reaches further than this request: it writes a setting on the calling account, the same one `PUT api/2.0/files/storeoriginal` writes, and it stays in force for later uploads. True keeps both the uploaded file and the copy the portal converts it into, false replaces the uploaded file with the converted one, and leaving it out keeps whatever the account already has.	[optional] [example: `true`]
keepConvertStatus	query	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] [example: `true`]
File	form	File (binary)	The content to store, sent as a `multipart/form-data` part; the name of that part becomes the title of the stored file, with characters a title cannot hold replaced and the name cut to 170 characters. A request without it is rejected as invalid.	[optional]

Responses

Status code	Description	Type	Response headers
200	The stored file, as a list with one element	FileIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot add content to this folder	-	-
404	No folder with the specified ID	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

uploadFileToMy

FileIntegerArrayWrapper uploadFileToMy(createNewIfExist, storeOriginalFile, keepConvertStatus, File)

POST /api/2.0/files/@my/upload

Upload a file to My documents

Uploads one file into the caller's own My documents section and returns it inside a single-element array; one request stores exactly one file. The destination takes no identifier: it is resolved from the calling account and created on first use, while a guest account has none and is answered as missing (404). The body has to be multipart/form-data carrying the file part; a request without it is rejected as invalid, and the stored name comes from that part, since unlike POST api/2.0/files/@my/insert there is no separate title. The call is not idempotent: by default a file of the same title is overwritten as a new version, while createNewIfExist=true stores a separate copy under a title made unique with a numeric suffix. storeOriginalFile is not a per-request switch: it writes the same account setting as PUT api/2.0/files/storeoriginal, which decides what happens to the formats listed in extsMustConvert of GET api/2.0/files/settings when they are converted after the response - false replaces the uploaded file with the converted one, true keeps both; keepConvertStatus=true keeps that conversion result readable through GET api/2.0/files/file/{fileId}/checkconversion. Files over the single-request size limit or the account's storage quota are refused; send those through POST api/2.0/files/{folderId}/upload/create_session.

Parameters

Name	In	Type	Description	Notes
createNewIfExist	query	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] [example: `true`]
storeOriginalFile	query	Boolean	Reaches further than this request: it writes a setting on the calling account, the same one `PUT api/2.0/files/storeoriginal` writes, and it stays in force for later uploads. True keeps both the uploaded file and the copy the portal converts it into, false replaces the uploaded file with the converted one, and leaving it out keeps whatever the account already has.	[optional] [example: `true`]
keepConvertStatus	query	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] [example: `true`]
File	form	File (binary)	The content to store, sent as a `multipart/form-data` part; the name of that part becomes the title of the stored file, with characters a title cannot hold replaced and the name cut to 170 characters. A request without it is rejected as invalid.	[optional]

Responses

Status code	Description	Type	Response headers
200	An array holding the single uploaded file	FileIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Uploading a file to the personal section is not allowed for this account	-	-
404	The caller has no personal section, so there is nothing to store the file in	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

FilesOperationsApi

abortUploadSession

abortUploadSession(sessionId, folderId)

DELETE /api/2.0/files/{folderId}/session/{sessionId}

Abort an upload session

Cancels a chunked upload opened with POST api/2.0/files/{folderId}/session and discards the parts already received, so nothing of it reaches the folder. The session is found by the id in the path alone: the folder segment is not matched against it, and neither is the account that opened it, which makes the id the only secret protecting the transfer. The call is destructive and is not safe to repeat, because the record is gone afterwards: a second attempt, a session already closed by PUT api/2.0/files/{folderId}/session/{sessionId}/finalize and a session that expired after twelve hours of silence all fail rather than answer as missing. Finalizing removes the session too, so there is nothing left to abort once the file exists. The answer carries no body. An upload that is simply abandoned needs no call at all, since the session and its buffered parts are dropped when it expires.

Parameters

Name	In	Type	Description	Notes
sessionId	path	String	The session to cancel, as returned in `id` when it was created: a 32-character hexadecimal string that identifies the session on its own.	[required] [example: `9f1c7a2b4d3e4f5a8b6c0d1e2f3a4b5c`]
folderId	path	Integer (int32)	The folder the session was opened against. It is part of the route only and is not matched against the session, which is found by its own id.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The session and the parts received so far have been discarded	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

addFavorites

BooleanWrapper addFavorites(BaseBatchRequestDto)

POST /api/2.0/files/favorites

Add favorite files and folders

Marks the listed files and folders as favorites for the calling account. The favorite list is personal: nothing changes for other members, and the entries stay where they are stored. Read access to each item is enough, so a room member with view-only rights and a guest may call it. Items the caller cannot read, ids that do not exist and encrypted files of a private room are skipped without a word, and the answer is true even when nothing was marked, so read the outcome back from GET api/2.0/files/@favorites instead of trusting it. Numeric ids address entries stored in the portal itself, string ids entries on a connected third-party account, and both kinds may be sent in one request. The call is mutating but safe to repeat: an item already marked stays listed once. An entry moved to the Trash keeps its mark and is left out of the listing until it is restored. returnSingleOperation arrives with the shared body and does nothing here. Use DELETE api/2.0/files/favorites to undo, or GET api/2.0/files/favorites/{fileId} for a single file.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always true: the request was understood, which does not mean that anything was marked	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Marking favorites is refused for the caller	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

bulkDownload

FileOperationArrayWrapper bulkDownload(DownloadRequestDto)

PUT /api/2.0/files/fileops/bulkdownload

Bulk download

Queues a background job that packs the requested files and folders into a single archive, and answers with the caller's download operations, including the one just started. The archive is not ready when the response arrives: poll GET api/2.0/files/fileops until the operation reports finished, then take the address of the archive from its url. Items listed in fileConvertIds are converted to the format named there before they are packed, while the items of fileIds are packed as they are. Read access to every listed item is required: an item the caller may not read fails the whole call with 403, and an id that resolves to nothing is answered as missing, so filter the selection beforehand. Only one download at a time is allowed per caller, and a second call made while the first is still running is refused with 403 as well. An empty selection queues nothing and simply answers with the operations that are already there. An anonymous caller may use the call for the items covered by the external link they hold.

Parameters

Name	In	Type	Description	Notes
DownloadRequestDto	body	DownloadRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The download operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	An item in the selection cannot be read by the caller, or another download of theirs is still running	-	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

ConversationResultArrayWrapper

HTTP request headers

Content-Type: application/json
Accept: application/json

checkConversionStatus

ConversationResultArrayWrapper checkConversionStatus(fileId, start)

GET /api/2.0/files/file/{fileId}/checkconversion

Get conversion status

Reports how far the conversion of a file has got, as a list that holds one entry while the portal still knows about that conversion and nothing once it is over. Read progress, which counts from 0 to 100, error for the reason a conversion failed, and file, which carries the converted file as soon as it exists. Queue the conversion with PUT api/2.0/files/file/{fileId}/checkconversion and poll this operation until the entry reaches 100 or disappears: a finished entry is handed out once and then dropped, and an entry whose conversion stopped is discarded a few minutes later, so an empty list means either already reported or never started rather than an error. The same empty list is the answer for an identifier no file matches. Passing start=true starts the conversion as well, with the format from the portal settings and no password, which makes that one flag mutating; without it the operation is read-only. The caller needs read access to the file, and anyone else is refused.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose conversion is asked about.	[required] [example: `1`]
start	query	Boolean	Whether to start the conversion as well: `true` queues it with the default output format and no password, `false` only reports what the portal already knows.	[optional] [example: `false`]

Responses

Status code	Description	Type	Response headers
200	The conversion entry of the file, or an empty list when the portal has none	ConversationResultArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

checkMoveOrCopyBatchItems

FileEntryBaseArrayWrapper checkMoveOrCopyBatchItems(inDto)

GET /api/2.0/files/fileops/move

Check move or copy conflicts

Reports which of the requested files and folders already have a same-named entry in destFolderId, so that the clash can be settled before the move or the copy is started. Nothing is moved, copied or changed by the call, although the address is shared with PUT api/2.0/files/fileops/move: the answer is the part of the request that clashes, and an empty array means the batch would go through without one. The conflictResolveType of the request is not taken into account — clashing items are reported whatever it says — and encrypted files are left out of the report. A source id that resolves to nothing is not an error and is passed over. The caller needs create access to the destination: an archived room and a room the caller cannot write to are refused with 403, a destination that does not exist is answered as missing, and a request without destFolderId is rejected as an invalid request. To learn whether the destination accepts the files at all use GET api/2.0/files/fileops/checkdestfolder.

Parameters

Name	In	Type	Description	Notes
inDto	query	BatchRequestDto	The files and folders to move or copy, the folder they go to, and the way name clashes are settled.	[optional]

Responses

Status code	Description	Type	Response headers
200	The listed items that already have a same-named entry in the destination folder	FileEntryBaseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot create items in the destination folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

CheckDestFolderWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

checkMoveOrCopyDestFolder

CheckDestFolderWrapper checkMoveOrCopyDestFolder(inDto)

GET /api/2.0/files/fileops/checkdestfolder

Check the destination folder

Reports whether the destination folder accepts the listed files, before a move or a copy is started. Only fileIds and destFolderId are read from the request: result says whether all of the files are accepted, only some of them or none, and files names the ones that are. The check is about what the destination allows to be stored in it rather than about name clashes — everywhere except a form-filling room every file is accepted, while a form-filling room accepts only PDF forms, so a text document offered to one comes back as none accepted. The caller needs create access to the destination, so a room the caller cannot write to and an archived room are refused with 403, a destination that does not exist is answered as missing, and a request without destFolderId is rejected as an invalid request. Folder ids and the copying options of the request play no part here. The call changes nothing; for same-named entries at the destination use GET api/2.0/files/fileops/move.

Parameters

Name	In	Type	Description	Notes
inDto	query	BatchRequestDto	The files and folders to move or copy, the folder they go to, and the way name clashes are settled.	[optional]

Responses

Status code	Description	Type	Response headers
200	Whether the destination accepts all of the listed files, some of them or none, and which ones it accepts	CheckDestFolderWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot create items in the destination folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

copyBatchItems

FileOperationArrayWrapper copyBatchItems(BatchRequestDto)

PUT /api/2.0/files/fileops/copy

Copy files and folders

Queues a background job that copies the requested files and folders into destFolderId, leaving the originals where they are, and answers with the caller's move and copy operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished; its files and folders then name what was produced. Before starting, GET api/2.0/files/fileops/move reports which items already have a same-named entry at the destination and conflictResolveType decides what happens to them, while GET api/2.0/files/fileops/checkdestfolder reports whether the destination accepts the files at all. The caller needs create access to the destination — room manager or content-creator rights inside a room — and read access to every source item; anything less is refused with 403. With content=true each listed folder is replaced by its own files and subfolders, so the folder itself is not recreated at the destination. An empty selection queues nothing and answers with the operations that are already there. To remove the originals instead use PUT api/2.0/files/fileops/move.

Parameters

Name	In	Type	Description	Notes
BatchRequestDto	body	BatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The move and copy operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot create items in the destination folder, or cannot read one of the listed items	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ChunkedUploadSessionResponseWrapperIntegerWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createUploadSession

ChunkedUploadSessionResponseWrapperIntegerWrapper createUploadSession(folderId, SessionRequest)

POST /api/2.0/files/{folderId}/upload/create_session

Chunked upload

Deprecated in favour of POST api/2.0/files/{folderId}/session, which opens the same session and returns it without the success envelope used here; new callers should go there. Reserves a chunked upload of a file in the folder named by the path: the title comes from fileName, the declared payload size from fileSize, and the answer carries the session id every later call quotes, the address of the standalone chunk handler, the moment an idle session is dropped and the reserved byte count. No content is stored yet. Send the payload as multipart parts to POST api/2.0/files/{folderId}/session/{sessionId}/upload, keeping each part within chunkUploadSize from GET api/2.0/files/settings, then close the session with PUT api/2.0/files/{folderId}/session/{sessionId}/finalize. The caller needs the right to add content to the target folder, which room managers and content creators have and readers, editors and guests do not: they get 403, as does a section root such as Rooms or Archive, while an unknown folder is answered as missing. A payload above the portal limit for chunked uploads is refused before the session exists.

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`]
SessionRequest	body	SessionRequest	The file the session is opened for, and how a clash with an existing name is settled.	[required]

Responses

Status code	Description	Type	Response headers
200	The created session, wrapped in the success envelope	ChunkedUploadSessionResponseWrapperIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot add content to the target folder	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createUploadSessionInFolder

ChunkedUploadSessionResponseIntegerWrapper createUploadSessionInFolder(folderId, SessionRequest)

POST /api/2.0/files/{folderId}/session

Create an upload session

Opens a chunked upload session for a file in the folder named by the path and returns the session itself, which is the difference from the deprecated POST api/2.0/files/{folderId}/upload/create_session and its success envelope. The answer gives id, quoted by every later call, location for the standalone chunk handler used by clients that bypass this API, expired, and bytes_total echoing the reserved size. Whether parts are really needed follows from fileSize: below chunkUploadSize from GET api/2.0/files/settings the whole payload goes in one POST api/2.0/files/{folderId}/session/{sessionId}, which stores the file and answers 201, and above it the parts go one by one to POST api/2.0/files/{folderId}/session/{sessionId}/upload and the file appears only after PUT api/2.0/files/{folderId}/session/{sessionId}/finalize. The caller must be allowed to add content to the folder, so readers, editors and guests are refused, a section root is refused as well, and an unknown folder is answered as missing. Nothing is written until the parts arrive, and an abandoned session disappears twelve hours later.

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`]
SessionRequest	body	SessionRequest	The file the session is opened for, and how a clash with an existing name is settled.	[required]

Responses

Status code	Description	Type	Response headers
200	The created upload session	ChunkedUploadSessionResponseIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ChunkedUploadSessionResponseIntegerWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteBatchItems

FileOperationArrayWrapper deleteBatchItems(DeleteBatchRequestDto)

PUT /api/2.0/files/fileops/delete

Delete files and folders

Queues a background job that deletes the requested files and folders, and answers with the caller's delete operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished, and read its error: a failure on a single item is reported there rather than as a status code. With immediately=false the items are moved to the caller's Trash and can be restored from it, while immediately=true removes them at once and for good; deleting a folder takes everything inside it either way. The call is destructive and it is not a no-op on repetition — a second call with the same ids deletes whatever has been restored in the meantime. Access is checked before the job is queued: deleting from a room requires room manager or content-creator rights, editing or read rights are refused with 403, and an id that resolves to nothing is answered as missing. An empty selection queues nothing and answers with the operations that are already there. To clear the Trash itself use PUT api/2.0/files/fileops/emptytrash.

Parameters

Name	In	Type	Description	Notes
DeleteBatchRequestDto	body	DeleteBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The delete operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller does not have the rights to delete one of the listed items	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteFavoritesFromBody

BooleanWrapper deleteFavoritesFromBody(BaseBatchRequestDto)

DELETE /api/2.0/files/favorites

Delete favorite files and folders

Removes the favorite mark from the listed files and folders for the calling account. Nothing is deleted from storage: the entries keep their place, their content and their sharing, and only disappear from GET api/2.0/files/@favorites; to delete the entries themselves call PUT api/2.0/files/fileops/delete instead. Marks of other members are untouched, and read access to each item is enough to call it. The ids go into the JSON body documented here; the same route also accepts them as repeated fileIds and folderIds query parameters, but only in a request that carries no JSON body at all. Numeric ids address entries stored in the portal itself, string ids entries on a connected third-party account. The answer is true whenever the request was understood, which an empty request, an id that does not exist and an item that was never marked all achieve, so it does not report how many marks were dropped. returnSingleOperation arrives with the shared body and does nothing here. Repeating the call is safe. Use POST api/2.0/files/favorites to mark entries again.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always true: the marks named in the request are gone or were never there	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteFileVersions

FileOperationArrayWrapper deleteFileVersions(DeleteVersionBatchRequestDto)

PUT /api/2.0/files/fileops/deleteversion

Delete file versions

Queues a background job that removes the listed versions from the history of one file, and answers with the caller's delete operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished; a failure met while the job runs is reported in its error rather than as a status code. Removal is permanent — deleted versions do not travel through Trash and cannot be restored, while the file itself stays in place with the versions that are left. Send the numbers that GET api/2.0/files/file/{fileId}/history reports, and send at least one: an empty list is not an empty request, it deletes the whole file instead. The number of the current version is refused before anything is queued, while numbers that no longer exist are passed over without a complaint. The caller needs the rights that deleting the file itself would need, so a member with read-only rights is refused, as are a file in an archived room and a file that is already in Trash, and a file that does not exist is answered as missing. To delete the file itself use PUT api/2.0/files/fileops/delete.

Parameters

Name	In	Type	Description	Notes
DeleteVersionBatchRequestDto	body	DeleteVersionBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The delete operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

duplicateBatchItems

FileOperationArrayWrapper duplicateBatchItems(DuplicateRequestDto)

PUT /api/2.0/files/fileops/duplicate

Duplicate files and folders

Queues a background job that copies each requested file and folder next to itself, into the folder where it already is, and answers with the caller's duplicate operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished. The copies keep the name of the original with a numeric suffix, so nothing is overwritten and every repetition adds one more copy; duplicating a folder duplicates its content as well. No destination is taken — to place a copy somewhere else use PUT api/2.0/files/fileops/copy. The caller needs the rights that creating an item in that folder would need, which inside a room means room manager or content-creator rights: read or editing rights, and an item the caller has no access to at all, are refused with 403. An empty selection queues nothing and answers with the operations that are already there.

Parameters

Name	In	Type	Description	Notes
DuplicateRequestDto	body	DuplicateRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The duplicate operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot create items in the folder that holds one of the listed items	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

emptyTrash

FileOperationArrayWrapper emptyTrash(Single, folderType)

PUT /api/2.0/files/fileops/emptytrash

Empty the Trash folder

Queues a background job that permanently removes the content of the caller's own Trash, and answers with the caller's delete operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished. Every authenticated account may empty its own Trash and only its own: no per-item access check takes place because nothing outside the caller's Trash is touched. With folderType the sweep is narrowed to the items that were originally stored in sections and rooms of the named types, so clearing what came from personal documents leaves what came from rooms untouched; without the parameter the whole Trash is emptied. What is removed here cannot be restored afterwards, which is the difference from PUT api/2.0/files/fileops/delete, where immediately=false puts items into Trash in the first place. Calling it on an already empty Trash queues nothing and answers with the operations that are already there.

Parameters

Name	In	Type	Description	Notes
Single	query	Boolean	Which operations the answer carries: `true` returns the operation this call started and nothing else, `false` returns every delete operation that the caller has running or unread.	[optional] [example: `false`]
folderType	query	List	Limits the sweep to the items whose original location was inside a section or a room of one of the named types, leaving the rest of the Trash untouched; without the parameter the whole Trash is emptied. `5` covers what was deleted from personal documents, `14` what was deleted from rooms.	[optional] [example: `[5]`] [enum: `0`, `1`, `2`, `3`, `5`, `6`, `8`, `10`, `11`, `12`, `13`, `14`, `15`, `16`, `19`, `20`, `21`, `22`, `25`, `26`, `27`, `28`, `29`, `30`, `31`, `32`, `33`, `34`, `35`, `36`]

Responses

Status code	Description	Type	Response headers
200	The delete operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

UploadSessionResponseIntegerWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

finalizeSession

UploadSessionResponseIntegerWrapper finalizeSession(folderId, sessionId)

PUT /api/2.0/files/{folderId}/session/{sessionId}/finalize

Finalize an upload session

Assembles the parts received so far into the file the session was opened for and closes the session. What comes out depends on how the session started: one opened against an existing file through POST api/2.0/files/file/{fileId}/edit_session replaces that content in place and keeps the version number, while one opened against a folder either creates the file or, when a file of the same name was taken over, stores the content as its next version. A form loses its filling state on the way in. The answer arrives with 201 and carries the identifiers of the file together with the file itself. The call ends the session: the record and the buffered parts are removed, so it cannot be repeated and there is nothing left to abort afterwards. Running it before all the declared bytes have arrived assembles whatever is there, so read the progress from the chunk calls first. An unknown, already closed or expired session id fails instead of answering as missing.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the session was opened against. It is part of the route only and is not matched against the session, which is found by its own id.	[required] [example: `1`]
sessionId	path	String	The session to assemble, as returned in `id` when it was created: a 32-character hexadecimal string that identifies the session on its own.	[required] [example: `9f1c7a2b4d3e4f5a8b6c0d1e2f3a4b5c`]

Responses

Status code	Description	Type	Response headers
200	The assembled file and the identifiers of the closed session	UploadSessionResponseIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getOperationStatuses

FileOperationArrayWrapper getOperationStatuses(id)

GET /api/2.0/files/fileops

Get active file operations

Returns the background file operations of the caller that are still running or whose finished result has not been read yet, grouped by kind: duplications first, then moves and copies, deletions, downloads and mark-as-read. This is the polling target for every operation in this section — an operation appears here as soon as it is queued and carries progress from 0 to 100, finished, the error of a failed item and, for a download, the address of the archive in url. A record is dropped once its finished state has been handed out, so a completed operation is reported once and an empty array means there is nothing left to report rather than that the work failed. Pass id to follow a single operation; an id that is not among the caller's operations gives an empty array. Operations are private to the account that started them, an anonymous caller being scoped to the session of the external link. The call changes nothing. To follow one kind only use GET api/2.0/files/fileops/{operationType}.

Parameters

Name	In	Type	Description	Notes
id	query	String	The operation to report on, as returned in `id` when it was started; without it every operation of the caller is reported. An id that is not among the caller's operations gives an empty answer rather than an error.	[optional] [example: `b2f3e9a4-7c15-4d8e-9f60-3a1c5e7d0b42`]

Responses

Status code	Description	Type	Response headers
200	The file operations of the caller that are still running or not yet read	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getOperationStatusesByType

FileOperationArrayWrapper getOperationStatusesByType(operationType, id)

GET /api/2.0/files/fileops/{operationType}

Get file operations by type

Returns the background file operations of the caller that are of one kind, named by the number in the route: 1 for a copy, 2 for a deletion, 3 for a download, 4 for a mark-as-read and 7 for a duplication. The answer carries the same records as GET api/2.0/files/fileops, with the same rule that a finished operation is reported once and then dropped, and id narrows it further to a single operation. Moves, kind 0, cannot be read through this route: the address api/2.0/files/fileops/move belongs to another operation, so read moves from GET api/2.0/files/fileops and pick the records whose operation is 0. A kind that has no queue of its own — 5 for an import, 6 for a conversion — is accepted and answers with an empty array, while a number outside the operation type is rejected as an invalid request. The call changes nothing and never shows another account's operations.

Parameters

Name	In	Type	Description	Notes
operationType	path	FileOperationType	The kind of operation the answer is limited to. Only the kinds that have a queue of their own ever carry records — a copy, a deletion, a download, a mark-as-read and a duplication — and moves cannot be read through this route at all, because its address belongs to another operation.	[required] [example: `2`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`]
id	query	String	The operation to report on, as returned in `id` when it was started; without it every operation of the caller is reported. An id that is not among the caller's operations gives an empty answer rather than an error.	[optional] [example: `b2f3e9a4-7c15-4d8e-9f60-3a1c5e7d0b42`]

Responses

Status code	Description	Type	Response headers
200	The operations of the caller that are of the requested kind	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

markAsRead

FileOperationArrayWrapper markAsRead(BaseBatchRequestDto)

PUT /api/2.0/files/fileops/markasread

Mark files and folders as read

Queues a background job that clears the new-item badge from the requested files and folders for the calling account, and answers with the caller's mark-as-read operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished. Marking a folder clears the badges of everything inside it as well. Items the caller cannot read are passed over in silence rather than refused, so the call succeeds even when the whole selection is inaccessible, and an empty selection queues nothing and answers with the operations that are already there. Repeating the call on items that are already read changes nothing, and nothing is opened, moved or modified by it — only the caller's own badges are affected, while other members keep theirs. To see what is currently marked as new use GET api/2.0/files/{folderId}/news for one folder and GET api/2.0/files/rooms/news for the rooms of the caller.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The mark-as-read operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

moveBatchItems

FileOperationArrayWrapper moveBatchItems(BatchRequestDto)

PUT /api/2.0/files/fileops/move

Move files and folders

Queues a background job that moves the requested files and folders into destFolderId, removing them from where they were, and answers with the caller's move and copy operations, including the one just started. Poll GET api/2.0/files/fileops until the operation reports finished. Before starting, GET api/2.0/files/fileops/move reports which items already have a same-named entry at the destination and conflictResolveType decides what happens to them, while GET api/2.0/files/fileops/checkdestfolder reports whether the destination accepts the files at all. The caller needs create access to the destination and the right to take the items out of their source, which is why room members with editing or review rights are refused with 403, and why content-creator rights inside a room allow copying an item out of it but not moving it. A room cannot be moved this way — use PUT api/2.0/files/rooms/{id}/archive instead. To keep the originals use PUT api/2.0/files/fileops/copy. An empty selection queues nothing.

Parameters

Name	In	Type	Description	Notes
BatchRequestDto	body	BatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The move and copy operations of the caller, the one just queued included	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot create items in the destination folder, or cannot take one of the items out of its source	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ConversationResultArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

startFileConversion

ConversationResultArrayWrapper startFileConversion(fileId, CheckConversionRequestDtoInteger)

PUT /api/2.0/files/file/{fileId}/checkconversion

Start file conversion

Queues the conversion of a file into the portal's own editable format and answers with the conversion entry the caller is to poll. The whole body may be omitted, in which case the defaults apply. outputType names the target format and, left empty, the portal's default for that kind of document is used; password unlocks a protected source file; version converts an older version instead of the current one. createNewIfExist decides where the result goes: with true a new file is created beside the source, while with false, the default, the converted file that already exists is replaced. sync=true converts inside the request and answers with the finished result instead of a queue entry, which is only sensible for small documents. Otherwise poll GET api/2.0/files/file/{fileId}/checkconversion until progress reaches 100 and take the converted file from file. Only formats the portal has to convert are accepted; anything already editable, and anything it cannot convert, is answered without work being queued or rejected as an invalid request. The caller needs read access to the file. The call is mutating and not idempotent.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file to convert.	[required] [example: `1`]
CheckConversionRequestDtoInteger	body	CheckConversionRequestDtoInteger	The parameters of the conversion. The whole body may be omitted, in which case the defaults of the portal apply.	[optional]

Responses

Status code	Description	Type	Response headers
200	The conversion entry to poll, or the finished result when the conversion is synchronous	ConversationResultArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

terminateTasks

FileOperationArrayWrapper terminateTasks(id)

PUT /api/2.0/files/fileops/terminate/{id}

Cancel file operations

Cancels a background file operation of the caller and answers with the operations that are left. Pass the id that was reported when the operation started to stop that one; a call that leaves the trailing route segment out stops every operation the caller has running, of every kind. Cancelling stops the job where it stands and does not undo it: what has already been copied, moved or deleted stays that way, so a cancelled batch can leave part of itself at the destination and part of it at the source, and the result has to be read back rather than assumed. The cancelled record is dropped from GET api/2.0/files/fileops at once, which is why the answer here is usually empty. An id that is not among the caller's operations cancels nothing and is not an error. Operations are private to the account that started them, an anonymous caller being scoped to the session of the external link, so the call can never reach an operation of anyone else.

Parameters

Name	In	Type	Description	Notes
id	path	String	The operation to cancel, as returned in `id` when it was started. A call that leaves the route segment out cancels every operation of the caller, and an id that is not among their operations cancels nothing without being an error.	[required] [example: `b2f3e9a4-7c15-4d8e-9f60-3a1c5e7d0b42`]

Responses

Status code	Description	Type	Response headers
200	The operations of the caller that are left after the cancellation	FileOperationArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateFileComment

StringWrapper updateFileComment(fileId, UpdateComment)

PUT /api/2.0/files/file/{fileId}/comment

Update a comment

Replaces the comment stored on one version of a file - the note that explains what changed in it - and answers with the comment as it was stored, which is the text cut to the length the portal keeps. version names the version and has to be an existing one: a version that does not exist is rejected as an invalid request, while a file that does not exist at all is answered as not found. Sending an empty comment clears the note. The caller needs the right to edit the history of the file, which the room admin, a DocSpace admin acting as room manager and a member with content-creator rights have; a member with editing access to somebody else's file, read-only access, a guest and an anonymous caller are all refused. A file that is locked by somebody else or lies in Trash is refused as well. The call is mutating and idempotent - repeating it with the same text leaves the same comment. The comments of all versions come back with GET api/2.0/files/file/{fileId}/edit/history.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose version comment is replaced.	[required] [example: `1`]
UpdateComment	body	UpdateComment	The version and the comment to store on it.	[required]

Responses

Status code	Description	Type	Response headers
200	The comment as it was stored	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ChunkedUploadSessionResponseIntegerWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

uploadAsyncSession

ChunkedUploadSessionResponseIntegerWrapper uploadAsyncSession(folderId, sessionId, ChunkNumber, File)

POST /api/2.0/files/{folderId}/session/{sessionId}/upload

Upload a numbered chunk

Stores one part of a file under the number given in chunkNumber, which is what the ordinary chunked flow uses: parts are kept by their number rather than by arrival, so a part that failed can be resent under the same number without restarting the session. Numbering starts at 1, and leaving the number out makes the server count the parts itself. The answer is always the session, never the file, and this call never completes the upload: the file appears only after PUT api/2.0/files/{folderId}/session/{sessionId}/finalize. Use POST api/2.0/files/{folderId}/session/{sessionId} instead when the parts go strictly in order and the upload should complete by itself. A part bigger than chunkUploadSize from GET api/2.0/files/settings is refused, so that value is also the size to split the payload by. The first part of a PDF is inspected, and a PDF that is not a fillable form is refused when the session targets a form-filling room. The session is found by its id alone.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the session was opened against. It is part of the route only and is not matched against the session, which is found by its own id.	[required] [example: `1`]
sessionId	path	String	The session this part belongs to, as returned in `id` when it was created; a 32-character hexadecimal string.	[required] [example: `9f1c7a2b4d3e4f5a8b6c0d1e2f3a4b5c`]
ChunkNumber	query	Integer (int32)	The position of this part in the file, counted from 1. Sending the same number again replaces that part instead of adding one, which is how a failed part is retried; leaving the number out makes the server count the parts itself.	[optional] [example: `1`]
File	form	File (binary)	The part of the file to store, sent as the multipart field of the same name. It is kept under the number given beside it, and a part larger than the portal chunk size is refused.	[optional]

Responses

Status code	Description	Type	Response headers
200	The session with its progress after the part was stored	ChunkedUploadSessionResponseIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

uploadSession

UploadSessionResponseIntegerWrapper uploadSession(folderId, sessionId, File)

POST /api/2.0/files/{folderId}/session/{sessionId}

Upload the next chunk

Sends the next part of a file into the session opened for it, as the multipart File field, and lets the server keep count: parts are appended in the order they arrive, so two of these calls must never run in parallel on one session. While bytes are still missing the answer describes the session and uploaded is false; when the last part completes the declared size the file is written, its upload links are cleared, it is marked as new for the room, and the answer comes back with 201, uploaded true and the whole file in file. A session created for a payload smaller than chunkUploadSize from GET api/2.0/files/settings finishes on the first such call and needs no separate finalize step. A part larger than that limit is refused. The first part of a PDF is inspected, and a PDF that is not a fillable form is refused when the session targets a form-filling room. The session is addressed by its id, and the folder in the path is not matched against it.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder the session was opened against. It is part of the route only and is not matched against the session, which is found by its own id.	[required] [example: `1`]
sessionId	path	String	The session this part belongs to, as returned in `id` when it was created; the parts of one session must be sent one after another, not in parallel.	[required] [example: `9f1c7a2b4d3e4f5a8b6c0d1e2f3a4b5c`]
File	form	File (binary)	The next part of the file, sent as the multipart field of the same name. Parts are appended in the order they arrive, and a part larger than the portal chunk size is refused.	[optional]

Responses

Status code	Description	Type	Response headers
200	The progress of the session, or the stored file once the last part has arrived	UploadSessionResponseIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

UploadSessionResponseIntegerWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

FilesQuotaApi

resetRoomQuota

FolderIntegerArrayWrapper resetRoomQuota(UpdateRoomsRoomIdsRequestDtoInteger)

PUT /api/2.0/files/rooms/resetquota

Reset the room quota limit

Returns every listed room to the default room quota of the portal and streams the updated rooms back in the order they were given. This is not the same as removing the limit: the room stops carrying its own value and starts following the portal default, which a portal administrator can change at any time. The per-room quota feature has to be on, the caller must be a manager of each listed room, and an archived room or a room in the trash is refused. The list is not transactional, so rooms processed before a failing one keep the default and the rest keep what they had. Only numeric room ids are processed, which means ids of rooms stored in a connected third-party account are silently skipped. Use PUT api/2.0/files/rooms/roomquota to set an explicit value, and a quota of -1 in PUT api/2.0/files/rooms/{id} to leave the room with no custom limit at all.

Parameters

Name	In	Type	Description	Notes
UpdateRoomsRoomIdsRequestDtoInteger	body	UpdateRoomsRoomIdsRequestDtoInteger		[optional]

Responses

Status code	Description	Type	Response headers
200	The rooms as they are after the default limit was restored	FolderIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FolderIntegerArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateRoomsQuota

FolderIntegerArrayWrapper updateRoomsQuota(UpdateRoomsQuotaRequestDtoInteger)

PUT /api/2.0/files/rooms/roomquota

Change the room quota limit

Sets the same custom storage limit, in bytes, on every listed room and streams the updated rooms back in the order they were given. The per-room quota feature has to be on for the portal, and the value must stay within the portal own limit, otherwise the call is refused before anything is written. The caller must be a manager of each listed room, and an archived room or a room in the trash is refused. The list is not transactional: rooms processed before the offending one keep their new limit, so a failed call has to be checked room by room. Only numeric room ids are processed, which means ids of rooms stored in a connected third-party account are silently skipped. A room whose limit already equals the requested value is left untouched and still returned. To go back to the portal default use PUT api/2.0/files/rooms/resetquota, and to drop the custom limit entirely send a quota of -1 to PUT api/2.0/files/rooms/{id}.

Parameters

Name	In	Type	Description	Notes
UpdateRoomsQuotaRequestDtoInteger	body	UpdateRoomsQuotaRequestDtoInteger		[optional]

Responses

Status code	Description	Type	Response headers
200	The rooms as they are after the new limit was applied	FolderIntegerArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FolderIntegerArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

FilesSettingsApi

changeAccessToThirdparty

BooleanWrapper changeAccessToThirdparty(SettingsRequestDto)

PUT /api/2.0/files/thirdparty

Change the third-party settings access

Turns the portal-wide permission to connect third-party storages such as Google Drive, Dropbox or Nextcloud on or off, and returns the value that is now stored. Only the portal owner and a DocSpace administrator may change it: a room administrator, a member or a guest is refused, and so is an unauthenticated caller. This is a single setting for the whole portal rather than a preference of the caller, so it changes what every account sees. While it is off, connecting an account through POST api/2.0/files/thirdparty is refused and the contents of an already connected provider folder cannot be listed; the stored connections themselves survive and work again once it is turned back on. The providers this portal can offer are listed by GET api/2.0/files/thirdparty/capabilities. The same value is published as enableThirdParty by GET api/2.0/files/settings. Sending the same value again is safe. The response is the value read back from the portal, not a success flag.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if third-party storages may be connected in this portal	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

AutoCleanUpDataWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeAutomaticallyCleanUp

AutoCleanUpDataWrapper changeAutomaticallyCleanUp(AutoCleanupRequestDto)

PUT /api/2.0/files/settings/autocleanup

Update the trash bin auto-clearing setting

Writes the trash auto-clearing setting of the calling account and returns the pair that is now stored. Both fields are written together from the request, so a call that omits gap stores an interval outside the published list rather than keeping the previous one - always send the interval, including when set is false. While clearing is on, an item is removed from the caller's trash for good once it has been there longer than the interval, and each trashed entry reports the moment it is due to disappear in its own autoDelete field; switching clearing off stops that and leaves whatever is in the trash. The setting belongs to the calling account alone: every authenticated role down to a guest may change its own, one member's choice never affects another, and an unauthenticated caller is refused. Items already removed are not recoverable. Read the pair back with GET api/2.0/files/settings/autocleanup.

Parameters

Name	In	Type	Description	Notes
AutoCleanupRequestDto	body	AutoCleanupRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The trash auto-clearing setting that is now stored for the caller	AutoCleanUpDataWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeDefaultAccessRights

FileShareResponseArrayWrapper changeDefaultAccessRights(request_body)

PUT /api/2.0/files/settings/dafaultaccessrights

Change the default access rights

Stores the access rights the sharing dialog offers the calling account by default, and returns the set that was actually stored. The body is a bare array of access-right values, not an object. The portal normalises the array instead of keeping it as sent: it keeps the fill-forms, custom-filter and review entries, then adds read-and-write or comment - whichever is present, in that order - and stops there, and it falls back to read alone when nothing else applies, so the response can be shorter than the request and its order can differ. An empty array clears the setting, after which read alone is reported. A value outside the published list is rejected as an invalid request. The set belongs to the calling account alone: every authenticated role down to a guest may store its own, and an unauthenticated caller is refused. Nothing already shared is changed. The stored set is published as defaultSharingAccessRights by GET api/2.0/files/settings.

Parameters

Name	In	Type	Description	Notes
request_body	body	List	The access rights the sharing dialog should offer by default. The array is the whole request body rather than a field of an object, and the portal stores a normalised subset of it instead of the array as sent, so read the answer to learn what was kept. An empty array clears the setting, after which the portal reports read access alone. A value outside the published list is rejected as an invalid request.	[optional]

Responses

Status code	Description	Type	Response headers
200	The normalised set of default access rights stored for the caller	FileShareResponseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileShareResponseArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeDeleteConfirm

BooleanWrapper changeDeleteConfirm(SettingsRequestDto)

PUT /api/2.0/files/changedeleteconfrim

Ask for delete confirmation

Stores whether the caller wants to be asked for confirmation before files and folders are deleted, and returns the value that is now stored. The setting belongs to the calling account alone: every authenticated role down to a guest may change its own copy, one member's choice never affects another, and an unauthenticated caller is refused. It is a hint for the interface, not a server-side guard: the delete operations under api/2.0/files/fileops remove whatever they are given regardless of this value, so a client that skips its own prompt loses nothing but the prompt. Pass set=true to be asked again, set=false to delete without a prompt. The same value is published as confirmDelete by GET api/2.0/files/settings, which is the only way to read it back. Repeating the call with the same value writes it again and is safe. A new account starts with the confirmation switched on, and the value says nothing about where deleted items land: they go to the trash and are cleared from there according to GET api/2.0/files/settings/autocleanup.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if the caller is asked to confirm a deletion	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ExternalSharingSettingsWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeDownloadZip

ICompressWrapper changeDownloadZip(DisplayRequestDto)

PUT /api/2.0/files/settings/downloadtargz

Change the download archive format

Selects the archive format the portal packs the caller's multi-item downloads into: set=true switches to .tar.gz, set=false back to .zip. The choice is stored for the calling account only, so every authenticated role down to a guest may set its own, while an unauthenticated caller is refused. It takes effect on the archives built by PUT api/2.0/files/fileops/bulkdownload and by the download links that operation returns; archives already produced keep the format they were packed with. The returned archive object carries no readable fields of its own, so it cannot be used to confirm the change: read downloadTarGz from GET api/2.0/files/settings instead. Writing the same value again is safe and changes nothing else. A new account starts on .zip. The format decides only how the archive is packed: which items go into it, and the access needed to take them, are decided by the bulk-download operation itself, and a single file is downloaded as it is whatever is stored here.

Parameters

Name	In	Type	Description	Notes
DisplayRequestDto	body	DisplayRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The archive helper for the format that is now selected	ICompressWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ICompressWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeExternalSharingSettings

ExternalSharingSettingsWrapper changeExternalSharingSettings(ExternalSharingSettingsRequestDto)

PUT /api/2.0/files/settings/externalsharingsettings

Configure external sharing

Writes the portal's whole external-sharing policy in one request and returns the set that is now in force. Only the portal owner and a DocSpace administrator may call it; everyone else is refused, including an unauthenticated caller. Every field of the request is applied, so send the complete set rather than the field being changed - an omitted boolean is read as false. The portal keeps the set consistent: with externalShare false the default link type is forced to users of this portal only and sharing on social networks is turned off, and the three restriction fields only matter while external sharing is off. blockExistingLinksOnRestrict decides what happens to links that already exist, so it is the field that changes access to data already shared. The new set is pushed to the connected clients of the portal as well, and is published field by field by GET api/2.0/files/settings. Sending the same set again is safe.

Parameters

Name	In	Type	Description	Notes
ExternalSharingSettingsRequestDto	body	ExternalSharingSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The external sharing policy that is now in force	ExternalSharingSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

checkDocServiceUrl

DocServiceUrlWrapper checkDocServiceUrl(CheckDocServiceUrlRequestDto)

PUT /api/2.0/files/docservice

Set the document service address

Writes the portal-wide ONLYOFFICE Docs connection settings - the public Document Server address, its address inside the private network, the address it calls this portal back on, the request signature secret and header, and SSL verification - then verifies them against the running Document Server before keeping them. Every address is optional: an empty value drops the portal's own setting so that the deployment default takes over again. An address gets http:// prepended when it carries no scheme, while an absolute address with a query string is rejected with 400, as is a signature secret sent without its header. Only the portal owner and a DocSpace administrator may call this; a room administrator, a user and a guest are refused with 403. The call is mutating and safe to repeat with the same body. Verification is live - the editor api script, the healthcheck, a test conversion, the command service and the document builder are all exercised - and when it fails the previous settings are restored in full and nothing is changed. The answer is what GET api/2.0/files/docservice returns with no version requested, so version comes back empty and the signature secret is not echoed back.

Parameters

Name	In	Type	Description	Notes
CheckDocServiceUrlRequestDto	body	CheckDocServiceUrlRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The settings are stored and the Document Server answered the verification requests	DocServiceUrlWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	An address cannot be parsed or carries a query string, the signature secret is sent without its header, or an http address is given for a portal served over https	-	-
403	The caller is not the portal owner or a DocSpace administrator	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

DocServiceUrlWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

displayFileExtension

BooleanWrapper displayFileExtension(SettingsRequestDto)

PUT /api/2.0/files/displayfileextension

Display a file extension

Stores whether file titles are shown to the caller with their extension, and returns the value that is now stored. It is a preference of the calling account: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. Only the presentation changes - the titles kept by the portal always include the extension, and the listing and file operations keep returning them in full, so a client that trims the extension for display must add it back before it renames or searches for anything. Writing a value that is already stored is accepted and leaves the setting untouched. The value is published as displayFileExtension by GET api/2.0/files/settings, which is the only way to read it back. A new account starts with extensions hidden. This governs display alone: which extensions may be uploaded, viewed or edited at all is published by the same settings operation as separate format lists.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if file titles are shown with their extension	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

displayRecent

BooleanWrapper displayRecent(DisplayRequestDto)

PUT /api/2.0/files/displayrecent

Show the Recent section

Stores whether the Recent section is offered to the calling account, and returns the value that is now stored. The setting belongs to that account alone: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. Hiding the section removes it from the list of section roots returned by GET api/2.0/files/@root, and the document editor stops offering the recent-files entry; the section itself keeps being maintained, and GET api/2.0/files/recent still returns its contents. Pass set=true to show it again. The same value is published as recentSection by GET api/2.0/files/settings, which is the only way to read it back. Repeating the call with the same value writes it again and is safe. A new account starts with the section shown. Hiding it neither clears the recent history nor stops it being recorded, so showing the section again brings the same entries back.

Parameters

Name	In	Type	Description	Notes
DisplayRequestDto	body	DisplayRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if the Recent section is offered to the caller	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller is not allowed to change this setting	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

externalShare

BooleanWrapper externalShare(DisplayRequestDto)

PUT /api/2.0/files/settings/external

Change the external sharing ability

Turns external (public) links on or off for the whole portal and returns the value that is now stored. Only the portal owner and a DocSpace administrator may change it: a room administrator, a member or a guest is refused, and so is an unauthenticated caller. Turning it off also turns sharing on social networks off, so a following read of externalShareSocialMedia reports false without a separate call. This operation sets one flag; to write the whole external-sharing policy in one request - the default link type, the sections the restriction applies to and whether existing links are blocked at once - use PUT api/2.0/files/settings/externalsharingsettings. The value is published as externalShare by GET api/2.0/files/settings. Sending the same value again is safe. The response is the value read back from the portal rather than a success flag. External links are allowed in a new portal. Turning them off does not delete the links that already exist - whether those stop working at once is decided by the blockExistingLinksOnRestrict field of the settings operation named above.

Parameters

Name	In	Type	Description	Notes
DisplayRequestDto	body	DisplayRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if external links may be created in this portal	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

externalShareSocialMedia

BooleanWrapper externalShareSocialMedia(DisplayRequestDto)

PUT /api/2.0/files/settings/externalsocialmedia

Change the external sharing ability on social networks

Turns the social-network sharing buttons on or off for the whole portal and returns the value that is now in force. Only the portal owner and a DocSpace administrator may change it; a room administrator, a member or a guest is refused, and so is an unauthenticated caller. The requested value is combined with the state of external sharing itself: while that is off, enabling this setting has no effect and the response comes back false, so turn external sharing on with PUT api/2.0/files/settings/external first and only then this one. Turning external sharing off later switches this setting off again on its own. The value is published as externalShareSocialMedia by GET api/2.0/files/settings. Sending the same value again is safe. Read the response instead of assuming the requested value was stored. The setting governs the share-to-network buttons offered next to an external link; it neither creates nor revokes links, and the links themselves keep working either way.

Parameters

Name	In	Type	Description	Notes
DisplayRequestDto	body	DisplayRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if sharing on social networks is now in force	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

forcesave

BooleanWrapper forcesave()

PUT /api/2.0/files/forcesave

Change the forcesaving ability

Reports that forcesaving is on for this portal. The operation is a stub kept for compatibility: it takes no request body, stores nothing and always answers true, so calling it neither turns forcesaving on nor off and repeating it changes nothing. Forcesaving itself - the editor writing the document back to storage while the session is still open - is on for every portal and cannot be switched off through the API. Any authenticated role down to a guest may call it; an unauthenticated caller is refused. The same constant is published as forcesave by GET api/2.0/files/settings, which is the cheaper way to read it together with the rest of the settings. A companion stub, PUT api/2.0/files/storeforcesave, answers for the storing of forcesaved versions in the same way. Nothing in this call reaches a document: to have the current state of an editing session written to storage, drive the document through the editor operations of the file itself rather than through this setting.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Always true: forcesaving is on for every portal	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

AutoCleanUpDataWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAutomaticallyCleanUp

AutoCleanUpDataWrapper getAutomaticallyCleanUp()

GET /api/2.0/files/settings/autocleanup

Get the trash bin auto-clearing setting

Returns the trash auto-clearing setting of the calling account: whether it is on, and after which interval an item that sits in the trash is removed for good. The setting belongs to that account alone, so every authenticated role down to a guest reads its own value and an unauthenticated caller is refused. The first call for an account is not read-only: when nothing has been stored yet the portal writes the default - clearing on, thirty days - and returns it, so the answer never comes back empty and a following call reports the same pair. The interval is the age of an entry in the trash, not a schedule; each trashed entry also reports the moment it is due to disappear in its own autoDelete field. Use PUT api/2.0/files/settings/autocleanup to change the pair, or read it together with the rest of the configuration from GET api/2.0/files/settings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The trash auto-clearing setting of the caller: the on/off flag and the interval	AutoCleanUpDataWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getDefaultTemplates

DefaultTemplateSettingsWrapper getDefaultTemplates()

GET /api/2.0/files/settings/defaulttemplate

Get the default template setting

Returns the blank document the portal creates for each format: one entry per extension the built-in template set covers, with the file that has been chosen as the blank for it, if any. An entry whose selectedFile is null means no custom template has been set and the built-in blank is used; the remaining fields - title, size, modification moment and view address - are filled only for a custom one. The list is assembled from the portal's built-in template set on every call, so an extension the set no longer covers disappears from it. Entries come in the order the interface shows them: the text document, spreadsheet, presentation and PDF formats first, the rest by extension. Reading the setting requires the portal settings permission, so only the portal owner and a DocSpace administrator may call it. Use PUT api/2.0/files/settings/defaulttemplate to choose an existing file and the matching POST to upload one.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The blank document configured for each supported extension	DefaultTemplateSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getDocServiceUrl

DocServiceUrlWrapper getDocServiceUrl(version)

GET /api/2.0/files/docservice

Get the document service address

Reports where this portal expects ONLYOFFICE Docs to be: the public Document Server address, the URL of the editor api script and of the preload page a client loads before opening a document, the address used inside the private network, the address the Document Server calls this portal back on, the name of the request signature header, whether SSL verification is on, and whether all of it is still at the deployment default. The call is read-only and needs no authorization: an anonymous caller and every role from the portal owner down to a guest read the same values. Pass version=true to have the editor version of the running Document Server included in version; left out, version comes back empty and the portal answers without contacting the Document Server at all. A version request never fails the call - when the Document Server does not answer, a fallback version string is reported instead of an error, so the value is no proof that the server is reachable. The signature secret is not part of the answer, only the header name it travels in. To change any of these settings use PUT api/2.0/files/docservice.

Parameters

Name	In	Type	Description	Notes
version	query	Boolean	Whether the running Document Server is asked for its editor version so that `version` can report it. Left off, the portal answers from its own settings without contacting the Document Server and `version` comes back empty.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The document service location, with the editor version filled in when it was requested	DocServiceUrlWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

DocServiceUrlWrapper

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFilesModule

ModuleWrapper getFilesModule()

GET /api/2.0/files/info

Get the Documents module information

Returns the descriptor of the Documents module of this portal: its identifier, display title and description, the address of its start page, the icon and image addresses, the address of its help section, and whether it is the portal's primary module. It is meant for building navigation to the module, not for working with documents: nothing about files, rooms or permissions comes back, and nothing is changed by the call. The values follow the portal's own configuration and branding, so the title and the description arrive already translated for the caller. Any authenticated role down to a guest may read it; an unauthenticated caller is refused. The content is the same for everyone in the portal and changes only when the portal is reconfigured, so it can be fetched once and cached rather than requested per screen. Only the Documents module is described here; this document carries no listing of the other modules of the portal. The file-related configuration a client needs alongside it - the format tables, the editor addresses and the upload limits - comes from GET api/2.0/files/settings.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The descriptor of the Documents module: identifier, title, description, icon and start addresses	ModuleWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

ModuleWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFilesSettings

FilesSettingsWrapper getFilesSettings()

GET /api/2.0/files/settings

Get file settings

Returns the whole Files configuration in one object: the caller's own preferences (trash auto-clearing, default sharing rights, hidden confirmation dialogs, archive format, section visibility), the portal-wide switches an administrator controls (third-party storages, external sharing), and the static tables a client needs to work with documents - which extensions can be viewed, edited, converted or uploaded, the URL templates for the viewer, editor and thumbnails, and the upload limits. This is the read side of the setting operations in this section: each of those answers with the one value it wrote, and only the trash auto-clearing and default-template settings have a GET of their own. Marked as allowing anonymous access because the external-link pages read the extension tables before signing in, but a caller with neither a session nor a valid link key is still rejected. The result is not filtered by role and is not paginated; fetch it once per session rather than before each file action.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The full set of file settings for the caller and the portal	FilesSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

FilesSettingsWrapper

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

hideConfirmCancelOperation

BooleanWrapper hideConfirmCancelOperation(SettingsRequestDto)

PUT /api/2.0/files/hideconfirmcanceloperation

Hide confirmation dialog when canceling operations

Stores whether the caller is asked to confirm cancelling a running file operation, and returns the value that is now stored. The setting belongs to the calling account alone: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. Unlike the conversion prompt of PUT api/2.0/files/hideconfirmconvert, this one works in both directions - set=true hides the confirmation, set=false brings it back. It is a hint for the interface only: cancelling an operation through the API is unaffected, and the operations themselves keep being reported by GET api/2.0/files/fileops. The value is published as hideConfirmCancelOperation by GET api/2.0/files/settings, which is the only way to read it back. Writing a value that is already stored is accepted and leaves the setting untouched. A new account starts with the confirmation shown. The prompt it hides is the one raised when a running copy, move or download is about to be abandoned, not the one raised before a deletion - that one is PUT api/2.0/files/changedeleteconfrim.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if the cancel confirmation is now hidden for the caller	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

hideConfirmConvert

BooleanWrapper hideConfirmConvert(HideConfirmConvertRequestDto)

PUT /api/2.0/files/hideconfirmconvert

Hide the confirmation dialog when converting

Hides one of the two prompts the interface shows around file conversion, for the calling account only. The save field chooses which prompt, and is not the value being written: save=true hides the prompt that offers to keep a copy in the original format when a file is converted, save=false hides the prompt that offers to open the conversion result. Both flags are one-way - the operation can only hide a prompt, and there is no API to show it again - so the answer is always true and repeating the call changes nothing. The two flags are independent: hiding one leaves the other as it was. Every authenticated role down to a guest may set its own, and an unauthenticated caller is refused. The stored flags are published as hideConfirmConvertSave and hideConfirmConvertOpen by GET api/2.0/files/settings. Conversion itself is started by PUT api/2.0/files/file/{fileId}/checkconversion and is not affected by either flag.

Parameters

Name	In	Type	Description	Notes
HideConfirmConvertRequestDto	body	HideConfirmConvertRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always true: the chosen conversion prompt is now hidden	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

hideConfirmRoomLifetime

BooleanWrapper hideConfirmRoomLifetime(SettingsRequestDto)

PUT /api/2.0/files/hideconfirmroomlifetime

Hide confirmation dialog when changing room lifetime settings

Stores whether the caller is warned before the lifetime settings of a room are changed, and returns the value that is now stored. A room lifetime moves the files of the room to the trash once they reach the configured age, which is why the interface confirms the change; this setting decides whether that confirmation is shown to the calling account. It belongs to that account alone: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. It works in both directions - set=true hides the warning, set=false brings it back - and is a hint for the interface only, so changing a room lifetime through PUT api/2.0/files/rooms/{id} is unaffected. The value is published as hideConfirmRoomLifetime by GET api/2.0/files/settings, which is the only way to read it back. A new account starts with the warning shown, and writing a value that is already stored is accepted and leaves the setting untouched. Hiding the warning does not shorten or extend any lifetime: what a room does with ageing files is decided by the room itself.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if the room lifetime warning is now hidden for the caller	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

keepNewFileName

BooleanWrapper keepNewFileName(SettingsRequestDto)

PUT /api/2.0/files/keepnewfilename

Keep the default file name

Stores whether the caller wants new documents created with the default name instead of being asked for one, and returns the value that is now stored. It is a preference of the calling account: every authenticated role down to a guest may change its own copy, one member's choice never affects another, and an unauthenticated caller is refused. The portal only keeps the value and reports it - the creation operations, POST api/2.0/files/{folderId}/file among them, always use the title they are given, so this setting changes what an interface asks for rather than what the server does. Writing a value that is already stored is accepted and leaves the setting and the audit trail untouched. The value is published as keepNewFileName by GET api/2.0/files/settings, which is the only way to read it back. A new account starts with the prompt in place. The title a created document actually gets, and how a clash with an existing title is resolved, are decided by the creation request rather than here.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if new documents are created with the default name	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

resetDefaultTemplate

DefaultTemplateSettingsWrapper resetDefaultTemplate(DefaultTemplateSettingsResetRequestDto)

DELETE /api/2.0/files/settings/defaulttemplate

Reset the default template setting

Drops the custom blank document configured for one extension and returns the full set of templates as it now stands. New documents of that extension are created from the portal's built-in blank again, and the file that served as the custom one is deleted from the template storage - the original the template was copied from is untouched. The extension is named in the request body, and the entry for it comes back with selectedFile null. Resetting an extension that has no custom blank is accepted and changes nothing, which makes a repeated call safe; an extension the built-in template set does not cover is ignored in the same way. Requires the portal settings permission, so only the portal owner and a DocSpace administrator may call it. To set a blank instead of dropping it, use PUT api/2.0/files/settings/defaulttemplate. Documents already created from the custom blank are left as they are - the reset only decides what the next new document of that extension starts from. The set as it stands can also be read with GET api/2.0/files/settings/defaulttemplate.

Parameters

Name	In	Type	Description	Notes
DefaultTemplateSettingsResetRequestDto	body	DefaultTemplateSettingsResetRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The blank document configured for each supported extension after the reset	DefaultTemplateSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read the portal settings	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setDefaultTemplate

DefaultTemplateSettingsWrapper setDefaultTemplate(DefaultTemplateSettingsRequestDto)

PUT /api/2.0/files/settings/defaulttemplate

Change the default template setting

Makes an existing document the blank the portal creates for one extension, and returns the full set of templates as it now stands. The file is copied into the portal's template storage, so later edits of the original do not change the blank, and the file that served as the previous custom blank for that extension is deleted. selectedFile takes the identifier of a file the caller may copy - a number for a document stored in the portal, a string for one in a connected third-party storage - and its extension must be the one named in fileExtension; a mismatch or an identifier of another kind answers 400, a file the caller may not copy answers 403, and a file that is not there is answered as missing. An extension the built-in template set does not cover is not an error: the call succeeds and changes nothing, so compare the answer with what was asked for. Requires the portal settings permission.

Parameters

Name	In	Type	Description	Notes
DefaultTemplateSettingsRequestDto	body	DefaultTemplateSettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The blank document configured for each supported extension after the change	DefaultTemplateSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The file identifier is of an unsupported kind, or its extension is not the one requested	-	-
403	The caller may not read the portal settings, or may not copy the selected file	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setOpenEditorInSameTab

BooleanWrapper setOpenEditorInSameTab(SettingsRequestDto)

PUT /api/2.0/files/settings/openeditorinsametab

Open document in the same browser tab

Stores whether the caller wants documents opened in the current browser tab instead of a new one, and returns the value that is now stored. It is a preference of the calling account: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. The portal only keeps the value - the editor addresses returned by the file operations are the same either way, so this setting changes how a client opens them rather than what it receives. Writing a value that is already stored is accepted and leaves the setting untouched. The value is published as openEditorInSameTab by GET api/2.0/files/settings, which is the only way to read it back. A new account starts with documents opening in a new tab. Nothing about the document changes with it: the editing session, the access rights that apply and the addresses handed out are the same whichever tab a client uses.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if documents are opened in the current browser tab	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setOrganizeRoomsGrouping

BooleanWrapper setOrganizeRoomsGrouping(SettingsRequestDto)

PUT /api/2.0/files/settings/organizegrouping

Organize rooms grouping

Stores whether the caller sees rooms arranged by the groups they belong to instead of one flat list, and returns the value that is now stored. It is a preference of the calling account: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. The groups themselves are the room groups managed under api/2.0/files/group, and they exist whether or not this setting is on - the portal only records the preference, while GET api/2.0/files/rooms keeps returning the same rooms either way, so the arrangement is done by the client. Writing a value that is already stored is accepted and leaves the setting untouched. The value is published as organizeRoomsGrouping by GET api/2.0/files/settings, which is the only way to read it back. A new account starts with the grouping on. Turning it off changes no group: the groups, the rooms in them and who may see them stay exactly as they were, and are still read through the room group operations.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if the caller sees rooms arranged by room groups	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

showQuickActions

BooleanWrapper showQuickActions(SettingsRequestDto)

PUT /api/2.0/files/showquickactions

Display quick actions

Turns the quick action buttons shown next to a file name on or off, and answers with the value that was sent. This is a preference of the calling account rather than a portal setting, so it changes what the caller sees and nothing for anybody else; any authenticated role down to a guest may set it, while an unauthenticated caller is refused. The value is written only when it differs from the one already stored, and only then is the change recorded in the audit trail, so repeating the same call is harmless and leaves no trace. An account that has never set it is treated as having the buttons on. The answer echoes the request instead of re-reading what was stored, so read the setting back through GET api/2.0/files/settings, which publishes it as showQuickActions.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if quick action buttons are now shown to the caller next to a file name	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

storeForcesave

BooleanWrapper storeForcesave()

PUT /api/2.0/files/storeforcesave

Change the ability to store the forcesaved files

Reports that forcesaved versions are not kept as separate file versions in this portal. The operation is a stub kept for compatibility: it takes no request body, stores nothing and always answers false, so it neither turns the behaviour on nor off and repeating it changes nothing. What it describes is what happens to the intermediate saves the editor makes while a document is still open - they update the current version instead of piling up as new ones in GET api/2.0/files/file/{fileId}/history. Any authenticated role down to a guest may call it; an unauthenticated caller is refused. The same constant is published as storeForcesave by GET api/2.0/files/settings, which is the cheaper way to read it. Its companion stub PUT api/2.0/files/forcesave answers for forcesaving itself in the same way. Version history is not affected by this call either: the versions a document really has are the ones the file history operation lists, and a new one appears when the editing session is closed.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Always false: forcesaved versions are not kept separately	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

storeOriginal

BooleanWrapper storeOriginal(SettingsRequestDto)

PUT /api/2.0/files/storeoriginal

Change the ability to upload original formats

Stores whether the caller's uploads keep the original file when the portal converts them into an editable format, and returns the value that is now stored. With set=true the converted document is saved as a new file next to the upload, so both the original and the converted copy stay in the folder; with set=false the conversion replaces the uploaded file with a new version of it whenever the caller may edit that file. The setting belongs to the calling account alone: every authenticated role down to a guest may change its own copy, and an unauthenticated caller is refused. It applies to conversion on upload and to PUT api/2.0/files/file/{fileId}/checkconversion, not to files already stored. The value is published as storeOriginalFiles by GET api/2.0/files/settings, which is the only way to read it back. The change is recorded in the portal audit trail.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	true if the original file is kept when an upload is converted	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateFileIfExist

BooleanWrapper updateFileIfExist(SettingsRequestDto)

PUT /api/2.0/files/updateifexist

Update a file version if it exists

Reports that uploading a file under a name that already exists does not update the existing file. The operation is a stub kept for compatibility: the request body is read but ignored, nothing is stored, and the answer is always false, so calling it changes no behaviour and repeating it changes nothing. What actually decides the outcome of a name clash is the parameter of the upload itself - see the createNewIfExist and conflict-resolution parameters of the operations under api/2.0/files/{folderId}/upload and of PUT api/2.0/files/fileops/copy. Any authenticated role down to a guest may call it; an unauthenticated caller is refused. Because the value is a constant, there is nothing to read back afterwards, and GET api/2.0/files/settings does not publish it. To add a version to a document that is already stored, address the file directly through the update operations under api/2.0/files/file/{fileId} instead of uploading under the same name and relying on this setting.

Parameters

Name	In	Type	Description	Notes
SettingsRequestDto	body	SettingsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always false: an upload does not update an existing file by name	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

uploadDefaultTemplate

DefaultTemplateSettingsWrapper uploadDefaultTemplate(FileExtension, File)

POST /api/2.0/files/settings/defaulttemplate

Upload a file as the default template setting

Uploads a document and makes it the blank the portal creates for one extension, and returns the full set of templates as it now stands. The request is multipart form data carrying the file, while the extension travels in the FileExtension query parameter; the extension of the uploaded file name must be exactly that one, or the call answers 403. A PDF is additionally checked to be a fillable form, and answers 403 as well when it is not one. The upload is capped at 100 MB and a larger body answers 400 while it is still streaming in. The file is stored in the portal's template storage and the file that served as the previous custom blank for that extension is deleted; an extension the built-in template set does not cover leaves everything unchanged. Requires the portal settings permission. Use PUT api/2.0/files/settings/defaulttemplate to reuse a document that is already in the portal.

Parameters

Name	In	Type	Description	Notes
FileExtension	query	String	The extension the uploaded blank is set for, written in lower case with the leading dot, and travelling in the query string rather than in the form. It must match the extension of the uploaded file name. Only the extensions the portal's built-in template set covers are accepted, and `GET api/2.0/files/settings/defaulttemplate` returns exactly that list; an extension outside it leaves the settings unchanged instead of failing.	[required] [example: `.docx`]
File	form	File (binary)	The template document itself. Its file name must end with the extension named above, a PDF must be a fillable form, and the body is capped at 100 MB - a larger one is refused while it is still streaming in.	[required]

Responses

Status code	Description	Type	Response headers
200	The blank document configured for each supported extension after the upload	DefaultTemplateSettingsWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The uploaded file is missing or larger than the 100 MB limit	-	-
403	The caller may not read the portal settings, or the file does not match the requested extension	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

FilesSharingApi

applyExternalSharePassword

ExternalShareWrapper applyExternalSharePassword(key, ExternalShareRequestParam)

POST /api/2.0/files/share/{key}/password

Unlock a password-protected link

Submits the password of a protected external share link and answers with the same resolved link data as GET api/2.0/files/share/{key}, so this operation is called only after that one reported that a password is required. The token in the path is the requestToken of the link, and the password is the one chosen by the member who shared the entry. The call needs no authentication; a signed-in caller that may already read the room is let through by the resolve operation itself and does not need the password at all. A correct password is remembered for the caller, so later requests with the same token resolve without repeating it, and a wrong one is reported in the status field as an invalid password rather than as an HTTP error, while the remembered password is dropped. Attempts are counted per link and per calling address: once the portal's limit is reached, further attempts are rejected until the block expires, which makes the operation unsuitable for trying passwords in a loop. Nothing about the entry is changed by the call itself.

Parameters

Name	In	Type	Description	Notes
key	path	String	The token of the external share link, taken verbatim from the `requestToken` of a link returned by the link operations of an entry, such as `GET api/2.0/files/rooms/{id}/link`. It is an opaque URL-safe string that carries the link's own identifier, so it cannot be assembled by hand.	[required] [example: `q7Ry8cQ1lZ0dP3sK2mXfA9tBnV6hJ4uE8wCz5oLg`]
ExternalShareRequestParam	body	ExternalShareRequestParam	The body of the request, holding the password to check.	[required]

Responses

Status code	Description	Type	Response headers
200	The entry the token points at, with the status the link reached after the password was checked	ExternalShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too many requests	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ExternalShareWrapper

Authorization

HTTP request headers

Content-Type: application/json
Accept: application/json

changeFileOwner

FileEntryBaseArrayWrapper changeFileOwner(ChangeOwnerRequestDto)

POST /api/2.0/files/owner

Change the room or file owner

Hands the ownership of the listed rooms and files over to a single account, and returns the entries as they look afterwards. Among folders only rooms are accepted - take their identifiers from GET api/2.0/files/rooms; a plain folder is refused. A file is accepted only while it lies in the portal's common section, so a file kept inside a room or in a personal section is refused as well, and so is a file that is locked or currently open in the editor. The new owner has to be an active account that is allowed to manage rooms, and a private room additionally requires that this account has already set up its encryption keys; a deactivated account, a guest or a plain member is rejected. The caller must be the creator of every listed room, or a portal administrator. The call mutates the entries one at a time and stops at the first item it may not touch, leaving the entries already processed changed, so a partial answer is possible; an item whose owner is already the target account is returned untouched, which makes a repeat safe. The previous owner keeps access to a transferred room as its manager, while a transferred file is saved as a new version authored by the new owner. An entry that lives on a connected third-party account is quietly left out.

Parameters

Name	In	Type	Description	Notes
ChangeOwnerRequestDto	body	ChangeOwnerRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The rooms and files whose owner has been changed, as folder and file objects	FileEntryBaseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getEncryptionAccess

EncryptionKeyArrayWrapper getEncryptionAccess(fileId)

GET /api/2.0/files/file/{fileId}/publickeys

Get file encryption keys

Answers with the encryption keys that open one file kept in a private room: one entry per member who holds rights on the file and has published keys, each carrying that member's public key, and the caller's own entry carrying the encrypted private half as well. The private half of another member is never handed out. A member who has not published keys yet is left out of the answer altogether, which is how a client tells that this member cannot open the file until keys are published through POST api/2.0/privacyroom/keys; a member who holds the file only through a group is not reported either, because group entries are skipped. The file has to lie in a private room or in the encrypted section - a file kept anywhere else carries no keys and is rejected as an unsupported request. The caller needs read access to the file and is answered with 403 otherwise, and a file that does not exist is answered as missing. The call is read-only, and the answer changes as soon as a member publishes or rotates keys, so read it again rather than caching it for a later session.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The keys of the members who can open the file, the private half only for the caller	EncryptionKeyArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not read the file	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getExternalShareData

ExternalShareWrapper getExternalShareData(key, fileId, folderId)

GET /api/2.0/files/share/{key}

Resolve an external share link

Resolves the token of an external share link into the room or file it points at, and reports the outcome of validating the link. The token is the requestToken of a link returned by the link operations of an entry, such as GET api/2.0/files/file/{id}/link or GET api/2.0/files/rooms/{id}/link. The call needs no authentication and answers a refused link in the status field rather than with an HTTP error, so that field has to be read before anything else: a token that matches no link, and a link whose entry has been archived or moved to the trash, both resolve as invalid; a link past its expiration date resolves as expired; a password-protected link resolves as requiring a password, which is then submitted through POST api/2.0/files/share/{key}/password; and a public link resolves as denied when the portal forbids sharing with people outside it. The call is not read-only: for a signed-in caller the first successful resolution puts the entry into the account's own lists, and for a visitor without an account it opens an anonymous session that later requests with the same token reuse. Pass fileId or folderId to have an entry inside the link's target echoed back.

Parameters

Name	In	Type	Description	Notes
key	path	String	The token of the external share link, taken verbatim from the `requestToken` of a link returned by the link operations of an entry, such as `GET api/2.0/files/rooms/{id}/link`. It is an opaque URL-safe string that carries the link's own identifier, so it cannot be assembled by hand.	[required] [example: `q7Ry8cQ1lZ0dP3sK2mXfA9tBnV6hJ4uE8wCz5oLg`]
fileId	query	String	A file inside the room the link points at, echoed back in the answer's entity fields so a client can show what was opened. The value is ignored when the file does not sit under the link's target, and passing it together with a folder has no effect - the file wins.	[optional] [example: `9`]
folderId	query	String	A folder inside the room the link points at, echoed back in the answer's entity fields. It is ignored when the folder does not sit under the link's target, and when a file is passed as well.	[optional] [example: `3`]

Responses

Status code	Description	Type	Response headers
200	The entry the token points at, with the validation status of the link	ExternalShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ExternalShareWrapper

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFileSecurityInfo

FileShareArrayWrapper getFileSecurityInfo(id, count, startIndex)

GET /api/2.0/files/file/{id}/share

Get file sharing rights

Lists the accounts and groups that hold rights on one file, one entry per subject, with the level each of them has, whether the caller may still change that level, and which of them owns the file. The owner comes first, then room managers, groups, ordinary members, guests, and last the accounts that have not accepted their invitation yet, each of those ranked by access level and by name. External links are left out and are listed by GET api/2.0/files/file/{id}/links instead, while a PDF form kept in a form-filling room also reports the link of that room, because the form is filled out through it. startIndex and count page through the subjects, and their total number is reported in the response headers rather than in the body. Listing takes the right to change the sharing of the file, which its creator, the manager of its room and a portal administrator acting as room manager have, while inside a public room reading the file is enough; a member who may read but not share is answered with an empty list although the header still counts the subjects, and a caller with no access, a guest included, is refused. A file that does not exist, or was deleted permanently, is answered as missing. The call is read-only; for several entries at once use POST api/2.0/files/share.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
count	query	Integer (int32)	How many entries at most to answer with, in the operations of this file that return a list; an operation that answers with a single object is not affected by it.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries of such a list to skip before answering, used together with `count` to walk through it page by page.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	The accounts and groups that hold rights on the file, the owner first	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getFolderSecurityInfo

FileShareArrayWrapper getFolderSecurityInfo(id, count, startIndex)

GET /api/2.0/files/folder/{id}/share

Get folder sharing rights

Lists the accounts and groups that hold rights on one folder or room, one entry per subject, with the level each of them has, whether the caller may still change that level, and which of them owns the entry. The owner comes first, then room managers, groups, ordinary members, guests, and last the accounts that have not accepted their invitation yet, each of those ranked by access level and by name. External links are left out and are listed by GET api/2.0/files/folder/{id}/links instead. startIndex and count page through the subjects, and their total number is reported in the response headers rather than in the body. For a room, and for a folder inside a public room, read access is enough; any other folder is listed only to a caller who may change its sharing, which the manager of its room and a portal administrator acting as room manager may, and a member who may only read such a folder is answered with an empty list although the header still counts the subjects. A caller with no access, a guest included, is refused, and a folder that does not exist is answered as missing. The call is read-only. For a room prefer GET api/2.0/files/rooms/{id}/share, which filters the same subjects by kind and by name.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The folder or room the operation addresses. A folder stored on the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `10`]
count	query	Integer (int32)	How many entries at most to answer with, in the operations of this folder that return a list; an operation that answers with a single object is not affected by it.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many entries of such a list to skip before answering, used together with `count` to walk through it page by page.	[optional] [example: `0`]

Responses

Status code	Description	Type	Response headers
200	The accounts and groups that hold rights on the folder, the owner first	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

GroupMemberSecurityRequestArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getGroupsMembersWithFileSecurity

GroupMemberSecurityRequestArrayWrapper getGroupsMembersWithFileSecurity(fileId, groupId, count, startIndex, filterValue)

GET /api/2.0/files/file/{fileId}/group/{groupId}/share

Get file access of group members

Lists the members of one portal group together with the access each of them has on a file that group was granted rights to: groupAccess is the level the group itself carries, userAccess is the level set on that member alone, overridden says which of the two applies, owner marks the member who created the file, and canEditAccess says whether the caller may still change that member's level. Take the group identifier from the group entries of GET api/2.0/files/file/{id}/share. startIndex and count page through the members, filterValue keeps only those whose first name, last name or email contains the value - the comparison is made in lower case, so an uppercase value matches nothing - and the number of members is reported in the response headers. Members come back ordered by first name. A group that holds no rights on this file, a file the caller cannot read and a file that does not exist are all answered with an empty list rather than an error, so an empty answer does not mean that the group has no members. A guest is refused. The call is read-only.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file whose access is being read. A file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
groupId	path	UUID (uuid)	The group whose members are listed. Take it from the entries of `GET api/2.0/files/file/{id}/share` that stand for a group; a group that holds no rights on this file is answered with an empty list.	[required] [example: `9924256a-739c-462b-af15-e652a3b1b6eb`]
count	query	Integer (int32)	How many members at most to answer with.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many members to skip before answering, used together with `count` to page through a large group.	[optional] [example: `0`]
filterValue	query	String	Keeps only the members whose first name, last name or email contains this value. The value is matched in lower case, so an uppercase one finds nothing.	[optional] [example: `john`]

Responses

Status code	Description	Type	Response headers
200	The members of the group with the access each of them has on the file	GroupMemberSecurityRequestArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getGroupsMembersWithFolderSecurity

GroupMemberSecurityRequestArrayWrapper getGroupsMembersWithFolderSecurity(folderId, groupId, count, startIndex, filterValue)

GET /api/2.0/files/folder/{folderId}/group/{groupId}/share

Get folder access of group members

Lists the members of one portal group together with the access each of them has on a folder or room that group was granted rights to: groupAccess is the level the group itself carries, userAccess is the level set on that member alone, overridden says which of the two applies, owner marks the member who created the entry, and canEditAccess says whether the caller may still change that member's level. Take the group identifier from the group entries of GET api/2.0/files/folder/{id}/share. startIndex and count page through the members, filterValue keeps only those whose first name, last name or email contains the value - the comparison is made in lower case, so an uppercase value matches nothing - and the number of members is reported in the response headers. Members come back ordered by first name. A group that holds no rights on this folder, a folder the caller cannot read and a folder that does not exist are all answered with an empty list rather than an error, so an empty answer does not mean that the group has no members. A guest is refused. The call is read-only.

Parameters

Name	In	Type	Description	Notes
folderId	path	Integer (int32)	The folder or room whose access is being read. A folder stored on the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `10`]
groupId	path	UUID (uuid)	The group whose members are listed. Take it from the entries of `GET api/2.0/files/folder/{id}/share` that stand for a group; a group that holds no rights on this folder is answered with an empty list.	[required] [example: `9924256a-739c-462b-af15-e652a3b1b6eb`]
count	query	Integer (int32)	How many members at most to answer with.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many members to skip before answering, used together with `count` to page through a large group.	[optional] [example: `0`]
filterValue	query	String	Keeps only the members whose first name, last name or email contains this value. The value is matched in lower case, so an uppercase one finds nothing.	[optional] [example: `john`]

Responses

Status code	Description	Type	Response headers
200	The members of the group with the access each of them has on the folder	GroupMemberSecurityRequestArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

GroupMemberSecurityRequestArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getSecurityInfo

FileShareArrayWrapper getSecurityInfo(BaseBatchRequestDto)

POST /api/2.0/files/share

Get sharing rights in batch

Returns who has access to the files and folders listed in the request, merged into one list of subjects, and is the batch counterpart of GET api/2.0/files/file/{id}/share and GET api/2.0/files/rooms/{id}/share. Identifiers come from any listing operation, such as GET api/2.0/files/{folderId}. The caller needs read access to every listed entry: a single entry it cannot read makes the whole call fail instead of dropping that entry, so the list has to be filtered beforehand. Identifiers that match nothing are skipped without an error, and an empty list of identifiers gives an empty answer. The call is read-only. Each account or group appears once: the caller's own record comes first, the owner's record second, and the rest are ordered by display name. When the same subject holds different rights on the listed entries, its access is reported as the Varies value instead of a real level, which means the entries have to be inspected one by one to see the difference. Records that describe external links are included only for a caller that is allowed to read the links of the entry.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The merged sharing rights of the listed files and folders, one record per account or group	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

MentionWrapperArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getSharedUsers

MentionWrapperArrayWrapper getSharedUsers(fileId)

GET /api/2.0/files/file/{fileId}/sharedusers

Get users to mention in a file

Lists the portal members who can read the file, which is what an editor client offers when somebody types a mention. The set holds the readers of the file plus everyone who reads it by role rather than by share - the portal owner, the DocSpace administrators and the author of the file - while the caller themselves, the subjects standing behind external links and deactivated accounts are left out. It is ordered by display name as the portal renders it. A guest receives a single entry, the owner of the file, because a guest is not a portal member and may not learn who else works on the document. The caller needs read access to the file, and an unknown file id is reported as missing. The call only reads. A caller who reached the file through an external link instead of an account is answered with nothing at all. For the users to offer when protecting a document use GET api/2.0/files/file/{fileId}/protectusers.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the operation addresses. Take the identifier from a listing such as `GET api/2.0/files/{folderId}`: a file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]

Responses

Status code	Description	Type	Response headers
200	The portal members who can read the file, ordered by display name	MentionWrapperArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

removeSecurityInfo

BooleanWrapper removeSecurityInfo(BaseBatchRequestDto)

DELETE /api/2.0/files/share

Remove sharing rights in batch

Revokes the access of every account and group on the files and folders listed in the request, and clears the entries from the caller's own favorites, recent and unread marks. The owner's own record is kept, since removing it would take the entry away from the account that owns it, and external links survive untouched - remove those through the link operations of the entry. The caller must be allowed to change the access of each entry, which means the creator of the room, a portal administrator, or a member with the rights to manage it; a caller whose only access came through an external link may use this call to drop the entry from its own list, while a directly invited member or an unrelated account is refused. The answer is always true and identifiers that match nothing are skipped silently, so a successful answer is not proof that anything was revoked - read the rights back with POST api/2.0/files/share. The call is destructive and safe to repeat. To take the rights of one account away instead of all of them, call PUT api/2.0/files/share with that account's access set to None.

Parameters

Name	In	Type	Description	Notes
BaseBatchRequestDto	body	BaseBatchRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Always true: the accounts and groups that had access to the listed entries no longer have it	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

AceShortWrapperArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

sendEditorNotify

AceShortWrapperArrayWrapper sendEditorNotify(fileId, MentionMessageWrapper)

POST /api/2.0/files/file/{fileId}/sendeditornotify

Notify mentioned users

Emails the people named in emails that they were mentioned in a file, with a link that opens the file at the place the mention sits when actionLink carries the anchor the editor produced. Only addresses that belong to portal accounts are notified: an address that belongs to nobody is skipped, and the note is cut to its first 200 characters in the mail, while a message longer than the field allows is refused with 400. The answer is usually empty: the access list of the file comes back when the file is encrypted, or when one of the addresses belongs to nobody and the caller may share the file - that is then the cue to invite that person with PUT api/2.0/files/file/{id}/share. The caller needs comment rights, which the creator of the file, the manager of its room and a member invited to comment, review or edit have, while a guest or a member without access is refused with 403; a file that does not exist answers with 404 and a file in the trash is refused. The operation is rate-limited and answers 429 once the caller sends too many notifications. A delivery failure is swallowed, so 200 does not prove that the mail left the portal.

Parameters

Name	In	Type	Description	Notes
fileId	path	Integer (int32)	The file the mention was made in. A file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
MentionMessageWrapper	body	MentionMessageWrapper	The notification to send.	[optional]

Responses

Status code	Description	Type	Response headers
200	The people who currently have access to the file, when the caller still has to invite someone; empty otherwise	AceShortWrapperArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The address list is missing, or the message is longer than the field allows	-	-
403	The caller may not comment on the file	-	-
404	The file does not exist	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFileSecurityInfo

FileShareArrayWrapper setFileSecurityInfo(id, SecurityInfoSimpleRequestDto)

PUT /api/2.0/files/file/{id}/share

Share a file

Grants, changes or withdraws the rights of the listed accounts and groups on one file, and answers with the rights those subjects hold afterwards. Every element of share names a subject and the level it is to get, and the level that denies everything takes the access away instead; an empty share changes nothing and is answered with an empty list. A subject the caller is not allowed to share with, such as a guest who belongs to another member, is dropped without an error, so compare the answer with what was sent. With notify set, each account named is emailed about the access it received and sharingMessage is put into that mail with its markup stripped, while a message longer than the field allows is rejected as an invalid request. The caller has to be allowed to change the sharing of the file, which its creator, the manager of the room it lies in and a portal administrator acting as room manager are; anyone else, a guest and a member with read access included, is refused. The call is mutating and safe to repeat. For several files and folders in one request use PUT api/2.0/files/share.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The file whose sharing is being changed. A file stored on the portal is numbered, while a file in a connected third-party account is named by an opaque string.	[required] [example: `10`]
SecurityInfoSimpleRequestDto	body	SecurityInfoSimpleRequestDto	The rights to apply to the file, and whether to announce them by mail.	[required]

Responses

Status code	Description	Type	Response headers
200	The rights the listed subjects hold on the file after the change	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setFolderSecurityInfo

FileShareArrayWrapper setFolderSecurityInfo(id, SecurityInfoSimpleRequestDto)

PUT /api/2.0/files/folder/{id}/share

Share a folder

Grants, changes or withdraws the rights of the listed accounts and groups on one folder, and answers with the rights those subjects hold afterwards. Every element of share names a subject and the level it is to get, and the level that denies everything takes the access away instead; an empty share changes nothing and is answered with an empty list. A subject the caller is not allowed to share with, such as a guest who belongs to another member, is dropped without an error. With notify set, each account named is emailed about the access it received and sharingMessage is put into that mail with its markup stripped, while a message longer than the field allows is rejected as an invalid request. The caller has to be allowed to change the sharing of the folder, which the manager of the room it belongs to and a portal administrator acting as room manager are; anyone else, a guest and a member with read access included, is refused. The call is mutating and safe to repeat. For a room use PUT api/2.0/files/rooms/{id}/share, which invites people by email as well.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The folder whose sharing is being changed. A folder stored on the portal is numbered, while a folder in a connected third-party account is named by an opaque string.	[required] [example: `10`]
SecurityInfoSimpleRequestDto	body	SecurityInfoSimpleRequestDto	The rights to apply to the folder, and whether to announce them by mail.	[required]

Responses

Status code	Description	Type	Response headers
200	The rights the listed subjects hold on the folder after the change	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setSecurityInfo

FileShareArrayWrapper setSecurityInfo(SecurityInfoRequestDto)

PUT /api/2.0/files/share

Set sharing rights in batch

Grants, changes or withdraws the access of the listed accounts and groups on every file and folder named in the request at once, and returns the resulting rights. Entry identifiers come from a listing operation, and the accounts and groups come from the portal's own account and group lists; an access of None withdraws the rights instead of granting them. The caller must be allowed to change the access of every listed entry - the creator of the room, a member with the rights to manage it, or a portal administrator - and a read-only member or a guest is refused even when the payload changes nothing. A subject the caller is not allowed to share with, such as a guest that belongs to another member, is skipped without an error, and an empty share collection makes the call do nothing and answer with an empty list. Repeating the same request leaves the same rights in place. The answer holds one record per listed subject for each entry that was actually processed, so it is shorter than the request when something was skipped and worth comparing against it. For a single room prefer PUT api/2.0/files/rooms/{id}/share, which also invites members by email.

Parameters

Name	In	Type	Description	Notes
SecurityInfoRequestDto	body	SecurityInfoRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The rights of the listed accounts and groups on every entry that was processed	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

FilesThirdPartyIntegrationApi

deleteThirdParty

StringWrapper deleteThirdParty(providerId)

DELETE /api/2.0/files/thirdparty/{providerId}

Remove a third-party account

Disconnects a third-party storage account from the portal and returns the ID of the folder that stood for it, in the provider-accountId form the Files operations use for third-party entries. Take providerId from GET api/2.0/files/thirdparty: it is the numeric account ID, not that composed folder ID. The member who connected the account can remove it; another member's request is refused unless they hold delete rights on the folder it stands for. Nothing is deleted at the storage service: the files stay with the provider, and what goes away is the portal's link to them together with the stored credentials, the sharing records and the tags kept for its entries. A room that was created on this account stops being available. When the account being removed is the one connected for backups by POST api/2.0/files/thirdparty/backup, its backup schedule is deleted as well. The removal cannot be repeated: once the account is gone the same ID is refused rather than confirmed, so treat the first successful answer as the record of it.

Parameters

Name	In	Type	Description	Notes
providerId	path	Integer (int32)	The ID of the connected third-party storage account, as `providerId` of `GET api/2.0/files/thirdparty`.	[required] [example: `12`]

Responses

Status code	Description	Type	Response headers
200	The ID of the folder that stood for the removed account	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getAllProviders

ProviderArrayWrapper getAllProviders(excludewebdav)

GET /api/2.0/files/thirdparty/providers

Get all third-party providers

Lists the third-party storage services this portal can connect, with everything a connection form needs: the display name, the key to send as providerKey, whether the service authenticates through OAuth 2.0, the OAuth client ID and redirect URL where it does, and whether the caller has to supply the server address. Several WebDAV presets share the key WebDav and are told apart by their names, so keep the name the caller chose next to the key when building the request. Pass excludewebdav=true to drop the whole WebDAV family, including the kDrive and Yandex presets, and keep only the OAuth services. The call is read-only. An empty array is a normal answer: it is what a guest gets, and what everyone gets while the portal-wide third-party switch is off (PUT api/2.0/files/thirdparty). The connected flag of an element says the service is available on this portal, not that an account of it exists - the caller's own accounts are listed by GET api/2.0/files/thirdparty.

Parameters

Name	In	Type	Description	Notes
excludewebdav	query	Boolean	Set to true to leave out the whole WebDAV family, the kDrive and Yandex presets included, and keep only the services that authenticate through OAuth 2.0; false lists all of them.	[optional] [example: `false`]

Responses

Status code	Description	Type	Response headers
200	The storage services this portal can connect	ProviderArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ProviderArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getBackupThirdPartyAccount

FolderStringWrapper getBackupThirdPartyAccount()

GET /api/2.0/files/thirdparty/backup

Get the third-party backup folder

Returns the folder of the third-party storage account the portal keeps for backups, so a caller can check where scheduled and manual backups are written. There is at most one such account per portal, connected by an administrator through POST api/2.0/files/thirdparty/backup, and it is deliberately kept out of the personal list of GET api/2.0/files/thirdparty. Any authenticated member may ask, and the call is read-only. The body is null, with a successful status, in two situations the answer does not distinguish: no backup account has been connected, and the caller has no read access to the folder of the one that is. When a folder does come back, its id is the string ID of a third-party folder and can be used with the folder operations that accept one, and its title is the title the account was saved under. Connecting a different account through the backup operation replaces this one rather than adding a second, and DELETE api/2.0/files/thirdparty/{providerId} removes it.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The root folder of the backup storage account, or null when none is connected	FolderStringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

FolderStringArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCapabilities

ArrayArrayWrapper getCapabilities()

GET /api/2.0/files/thirdparty/capabilities

Get third-party provider capabilities

Lists the third-party storage services this portal is able to connect, in the compact form a connection dialog needs. Every element is itself an array whose first item is the provider key accepted as providerKey by POST api/2.0/files/thirdparty. For the services that authenticate through OAuth 2.0 (Box, DropboxV2, GoogleDrive, OneDrive) the second and third items are the OAuth client ID and the redirect URL this portal is registered with, so the caller can build the consent screen URL itself; the services that authenticate by login and password (SharePoint, WebDav, kDrive, Yandex) contribute a single-item array. Only the services enabled in the portal configuration are listed, and an OAuth service whose application is not configured is left out. The call is read-only. An empty array is a normal answer rather than a failure: it is what a guest gets, and what everyone gets while the portal-wide third-party switch is off (PUT api/2.0/files/thirdparty). For display names, the WebDAV presets and the flags a connection form needs, use GET api/2.0/files/thirdparty/providers instead.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The provider keys, each with the OAuth client ID and redirect URL where the service uses OAuth	ArrayArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

ArrayArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getCommonThirdPartyFolders

FolderStringArrayWrapper getCommonThirdPartyFolders()

GET /api/2.0/files/thirdparty/common

Get common third-party folders

Lists the third-party storage accounts attached to the legacy Common section, as folder entries that can be browsed with the usual folder operations. Each entry stands for a whole connected account: its title is the account title, and providerId and providerKey identify the account behind it. Only accounts whose owner the caller may read are included, so the answer differs from one member to another. The call is read-only and returns a plain array with no paging. An empty array is the expected answer in most portals and does not mean an error: accounts connected by POST api/2.0/files/thirdparty are attached to the Rooms section, not to Common, so only accounts inherited from an older portal appear here. The list is also empty while the portal-wide third-party switch is off (PUT api/2.0/files/thirdparty) and when no storage service is configured. For the accounts the caller owns, regardless of where they are attached, use GET api/2.0/files/thirdparty.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The third-party accounts attached to the Common section, as folder entries	FolderStringArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getThirdPartyAccounts

ThirdPartyParamsArrayWrapper getThirdPartyAccounts()

GET /api/2.0/files/thirdparty

Get the third-party accounts

Lists the third-party storage accounts the caller has connected, one element per account, with the title it was saved under, the storage service behind it and the portal section it is attached to. Accounts connected by other members are not included, and neither is the portal backup account of GET api/2.0/files/thirdparty/backup, even for an administrator. The providerId of an element is the value to send to DELETE api/2.0/files/thirdparty/{providerId} and, as providerId in POST api/2.0/files/thirdparty, the way to re-authenticate that same account instead of connecting a new one. Credentials are never disclosed: auth_data comes back empty for every element. An element with roomsStorage set is available as storage for a room, while corporate marks an account inherited from the legacy Common section. The call is read-only, returns a plain array with no paging and no contractual ordering, and answers with an empty array when the caller has connected nothing. To browse the content of an account, take the folder ID from the answer of the operation that connected it or from GET api/2.0/files/@root.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The third-party accounts the caller has connected	ThirdPartyParamsArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

ThirdPartyParamsArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

saveThirdParty

FolderStringWrapper saveThirdParty(ThirdPartyRequestDto)

POST /api/2.0/files/thirdparty

Connect a third-party account

Connects an account at a third-party storage service to the portal, or re-authenticates one that is already connected, and returns the folder that now stands for its root. Send providerId to update an existing account and omit it to connect a new one; the accepted providerKey values come from GET api/2.0/files/thirdparty/providers. The credentials to send depend on the service: the OAuth services take token, which is the authorization code from their consent screen and not an access token, while the WebDAV family and SharePoint take login with password, plus url where the server address is not fixed. Credentials are verified against the service before anything is stored, so a wrong password is refused and nothing is saved. The caller needs the rights to create rooms, and the portal-wide third-party switch has to be on, otherwise the call is refused. A new account is attached to the Rooms section and becomes available as room storage for POST api/2.0/files/rooms/thirdparty/{id}. Connecting twice with the same title creates two separate accounts.

Parameters

Name	In	Type	Description	Notes
ThirdPartyRequestDto	body	ThirdPartyRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The root folder of the connected account	FolderStringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

saveThirdPartyBackup

FolderStringWrapper saveThirdPartyBackup(ThirdPartyBackupRequestDto)

POST /api/2.0/files/thirdparty/backup

Connect the third-party backup storage

Connects the third-party storage account the portal writes its backups to, and returns the folder that stands for its root. Only a portal administrator may call it, and the portal-wide third-party switch has to be on; other callers are refused. The account is portal-wide and single: a second call does not add another one but re-authenticates and retitles the existing one, which makes the operation safe to repeat with the same body. The credentials follow the same rules as in POST api/2.0/files/thirdparty - an authorization code in token for the OAuth services, login with password and, where the server address is not fixed, url for the WebDAV family and SharePoint - and are verified against the service before anything is stored, so a wrong password leaves the previous account untouched. The account is deliberately absent from GET api/2.0/files/thirdparty; read it back with GET api/2.0/files/thirdparty/backup and remove it with DELETE api/2.0/files/thirdparty/{providerId}.

Parameters

Name	In	Type	Description	Notes
ThirdPartyBackupRequestDto	body	ThirdPartyBackupRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The root folder of the backup storage account	FolderStringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

RoomsApi

addRoomTags

FolderIntegerWrapper addRoomTags(id, BatchTagsRequestDto)

PUT /api/2.0/files/rooms/{id}/tags

Attach tags to a room

Attaches the named tags to a room and returns the room with its whole tag set. Tags are portal-wide labels shared by every room, and a name that the catalogue does not hold yet is created there by this call, so attaching is also the short way of adding a tag to the portal. Names already attached to the room are kept as they are, and repeating the call changes nothing, which makes it safe to retry. An empty list is accepted and does nothing, while a blank or overlong name is rejected as an invalid request. The caller must be a manager of the room or an administrator of the portal, and a room in the Archive section is refused with 403. A tag has no identifier of its own and is addressed by name, so GET api/2.0/files/tags is what shows which names already exist. Use DELETE api/2.0/files/rooms/{id}/tags to detach them again, which leaves the tags themselves in the catalogue.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room whose tags are changed, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
BatchTagsRequestDto	body	BatchTagsRequestDto	The names to attach or to detach.	[optional]

Responses

Status code	Description	Type	Response headers
200	The room with its tag set after the change	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit this room, or the room is archived	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

archiveRoom

FileOperationWrapper archiveRoom(id, ArchiveRoomRequest)

PUT /api/2.0/files/rooms/{id}/archive

Archive a room

Queues a background job that moves one room from the Rooms section to the Archive section, and returns the operation record of that job. An archived room stays readable to its members and becomes read only: files cannot be created, renamed or edited in it, and its settings, tags, logo and links can no longer be changed, which is why many other room operations answer an archived room with a refusal. The caller must be a manager of the room; administrators of the portal cannot archive a room they were not invited to, and a room template cannot be archived at all and is answered as missing. The room is not archived when the response arrives: poll GET api/2.0/files/fileops until finished is true. Archiving an already archived room is harmless. deleteAfter decides only how long the finished record survives, not what happens to the room. Use PUT api/2.0/files/rooms/{id}/unarchive to bring the room back.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to move, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
ArchiveRoomRequest	body	ArchiveRoomRequest	The body of the request. It carries only the lifetime of the job record, so an empty object is a normal request.	[optional]

Responses

Status code	Description	Type	Response headers
200	The queued archive operation to poll	FileOperationWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileOperationWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeRoomCover

FolderIntegerWrapper changeRoomCover(id, CoverRequestDto)

POST /api/2.0/files/rooms/{id}/cover

Change the room cover

Sets the cover picture and the background colour a room is shown with, and returns the whole room afterwards. cover accepts only an identifier listed by GET api/2.0/files/rooms/covers, and color only six hexadecimal digits with no leading number sign, so anything else is rejected as an invalid request. Either field may be sent on its own, an empty cover clears the picture, an empty color restores the default one, and an empty body leaves the room untouched. The cover is what the room shows while it has no uploaded logo: setting a logo with POST api/2.0/files/rooms/{id}/logo hides the cover without erasing it, and deleting that logo brings it back. The caller must be a manager of the room, an archived room is refused with 403, and an unknown or deleted room is answered with 404. Repeating the same request is harmless, and the cover survives archiving and unarchiving.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to change, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
CoverRequestDto	body	CoverRequestDto	The cover and the colour to apply. Either half may be sent on its own, and an empty object leaves the room as it is.	[required]

Responses

Status code	Description	Type	Response headers
200	The room as it is after the cover change	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit this room, or the room is archived	-	-
404	No room with this ID is visible to the caller	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createRoom

FolderIntegerWrapper createRoom(CreateRoomRequestDto)

POST /api/2.0/files/rooms

Create a room

Creates a room in the portal Rooms section and returns it. roomType decides which sharing links, member roles and form features the room offers, and it cannot be changed afterwards, so a room of the wrong kind has to be recreated. The caller must be the portal owner, a portal administrator or a room administrator; a user or a guest is refused, and so is a public room while the portal forbids external sharing. title is required and must not be blank: characters a folder name cannot hold are replaced with underscores and the rest is truncated, so the stored title can differ from the one sent and two rooms can share it. quota is accepted only while the per-room quota feature is on and must stay within the portal quota, cover only for an id returned by GET api/2.0/files/rooms/covers, and color as six hexadecimal digits with no leading number sign. Tag names the portal does not know yet are added to the tag catalogue. share is not implemented and any non-empty value is rejected, so invite members afterwards with PUT api/2.0/files/rooms/{id}/share. Passing the portal room limit ends the call as a billing refusal and creates nothing.

Parameters

Name	In	Type	Description	Notes
CreateRoomRequestDto	body	CreateRoomRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The created room with its id, type, settings, logo and tags	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

RoomFromTemplateStatusWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createRoomFromTemplate

RoomFromTemplateStatusWrapper createRoomFromTemplate(CreateRoomFromTemplateDto)

POST /api/2.0/files/rooms/fromtemplate

Create a room from the template

Starts a background job that copies a room template into a new room of the Rooms section, and answers with the same progress record that GET api/2.0/files/rooms/fromtemplate/status returns. The caller must be able to read the template and to create rooms at all, so a user or a guest is refused, and the checks run before the job is queued. The room does not exist when the response arrives: poll the status operation until isCompleted is true, then take roomId from it, and treat a non-empty error as a failed job. Only one such job is kept per account, and a finished one is discarded when the next is started, so a second creation loses the record of the first. Anything not sent is inherited from the template, and copyLogo keeps the template logo and makes logo pointless. quota is accepted only while the per-room quota feature is on, and a template of a public room cannot be instantiated while the portal forbids external sharing. A template that does not exist or cannot be read is answered as missing.

Parameters

Name	In	Type	Description	Notes
CreateRoomFromTemplateDto	body	CreateRoomFromTemplateDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The progress record of the room creation job	RoomFromTemplateStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createRoomLogo

FolderIntegerWrapper createRoomLogo(id, LogoRequest)

POST /api/2.0/files/rooms/{id}/logo

Set the room logo

Turns an image already uploaded to the portal into the logo of a room and returns the room with the addresses of the four logo sizes. This is the second half of a two-step flow: upload the picture with POST api/2.0/files/logos first and pass the path it returns as tmpFile, because the image itself is never sent here. The temporary file belongs to the account that uploaded it and is consumed by this call, so it cannot be reused for a second room and a path somebody else uploaded is refused. x, y, width and height crop the picture; sending a position without a size is rejected as an invalid request, while a size without a position is accepted. An empty tmpFile leaves the room as it is. A logo replaces the cover in the interface without erasing it, and removing the logo brings the cover back. The caller must be a manager of the room, an archived room is refused, and an unknown room is answered with 404.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room the logo is set on.	[required] [example: `1`]
LogoRequest	body	LogoRequest	The uploaded picture and the piece of it to use.	[required]

Responses

Status code	Description	Type	Response headers
200	The room with the addresses of its new logo	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
404	No room with this ID is visible to the caller	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createRoomTag

StringWrapper createRoomTag(CreateTagRequestDto)

POST /api/2.0/files/tags

Create a room tag

Adds a custom tag to the portal-wide catalog of room tags and answers with the stored name. Tags are shared by the whole portal instead of belonging to the caller: once the tag exists, every room manager can attach it to their own rooms with PUT api/2.0/files/rooms/{id}/tags, and that call also creates a tag it does not find. Creating a name that is already in the catalog returns the existing tag unchanged rather than a duplicate or an error, so repeating the call after a timeout is safe. A blank name, or one longer than the published limit, is rejected as an invalid request. Only a room manager or a portal administrator may create a tag, and a user or a guest is refused. The answer is the name as stored, and that name is the value to send in the tags filter of GET api/2.0/files/rooms and in the room tag calls. The catalog itself is read with GET api/2.0/files/tags.

Parameters

Name	In	Type	Description	Notes
CreateTagRequestDto	body	CreateTagRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The name of the created tag, or of the tag that already carried this name	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Only a room manager or a portal administrator can create tags	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

RoomTemplateStatusWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createRoomTemplate

RoomTemplateStatusWrapper createRoomTemplate(RoomTemplateDto)

POST /api/2.0/files/roomtemplate

Create a room template

Queues a background job that turns an existing room into a reusable room template, and returns the state of that job right away. The template lands in the portal's Templates section, inherits the source room's type, privacy, indexing, storage limit, lifetime, download and watermark settings, and receives copies of the room's files together with its ordinary subfolders and everything inside them; the service subfolders a room keeps for its own workflows are left out. The caller needs room-manager rights on the source room, and the room must not be archived: a room that cannot be found under Rooms is answered as missing, and every other refusal comes back as a rejection. The template is not ready when the response arrives, so poll GET api/2.0/files/roomtemplate/status until isCompleted is true, then read templateId; a non-empty error there means the job failed and the half-built template was removed. Only one template creation is tracked per caller, and starting another replaces the previous record. Setting public to true discards share and groups and shares the finished template with everyone instead, while copyLogo reuses the source room's own picture and makes logo irrelevant.

Parameters

Name	In	Type	Description	Notes
RoomTemplateDto	body	RoomTemplateDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Status	RoomTemplateStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

createRoomThirdParty

FolderStringWrapper createRoomThirdParty(id, CreateThirdPartyRoom)

POST /api/2.0/files/rooms/thirdparty/{id}

Create a third-party room

Turns a folder of a connected third-party storage account into a room of the Rooms section, so that the files of the room keep living in that storage instead of the portal. Connect the account first with POST api/2.0/files/thirdparty and take the path parameter from a folder listing of that account: it is the identifier of a folder in the storage, not of a room. One connected account can back one room only, so a second call over the same account is refused, and so is an account that was not connected for room storage. The caller needs the right to create rooms, which a portal user and a guest do not have; a public room is refused while the administrator restricts external access, and reaching the room limit of the tariff is refused too. With createAsNewFolder the room is a new subfolder named after title, otherwise the folder from the path becomes the room itself and indexing, denyDownload, tags and logo are then dropped. The answer is the new room, whose identifiers are strings; a public or a form-filling room already has its primary link, readable with GET api/2.0/files/rooms/{id}/link.

Parameters

Name	In	Type	Description	Notes
id	path	String	The identifier of the folder in the connected third-party storage that becomes the room, or receives it as a subfolder. Folder identifiers of a connected account are strings and are returned by the folder listings of that account.	[required] [example: `box-12-\|280143035119`]
CreateThirdPartyRoom	body	CreateThirdPartyRoom	The settings of the room to be created out of the folder.	[required]

Responses

Status code	Description	Type	Response headers
200	The room created out of the third-party folder, with string identifiers	FolderStringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteCustomTags

deleteCustomTags(BatchTagsRequestDto)

DELETE /api/2.0/files/tags

Delete the custom room tags

Deletes custom room tags from the portal catalog by name and detaches them from every room that carries them; the rooms themselves and their content are untouched, and only the tag disappears from their tag lists. Only a portal administrator may call it, and a room manager who is allowed to create tags is refused. The names are matched exactly as they are stored: names that are not in the catalog are skipped in silence and an empty list is accepted as a no-op, so a successful answer does not prove that anything was deleted; check a name with GET api/2.0/files/tags/{tagName}/haslinks first when that matters. The call cannot be undone: creating the name again with POST api/2.0/files/tags brings back the tag but not its links, which have to be attached to each room once more. The answer carries no body. To take a tag off one room and leave it in the catalog for the others, use DELETE api/2.0/files/rooms/{id}/tags instead.

Parameters

Name	In	Type	Description	Notes
BatchTagsRequestDto	body	BatchTagsRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The tags were removed from the catalog and from every room	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Only a portal administrator can delete tags	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteRoom

FileOperationWrapper deleteRoom(id, DeleteRoomRequest)

DELETE /api/2.0/files/rooms/{id}

Remove a room

Queues a background job that deletes one room with everything inside it, and returns the operation record of that job. Deleting a room is destructive and has no trash step: the room and its files are gone once the job finishes, unlike a file or a folder, which is moved to the trash first. The right to delete is checked before the job is queued, so a caller who may not delete the room is refused straight away and an unknown room is answered as missing; the same checks run again when the job starts, which is why the error of the finished operation still has to be read. Poll GET api/2.0/files/fileops until finished is true, or read the returned record again by its id. The record is kept until it is read once, so one poll after completion still sees it. deleteAfter in the body is required by the contract but has no effect on the job. An archived room is deleted the same way, and a second delete of the same id reports that the room is missing.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to delete, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `10`]
DeleteRoomRequest	body	DeleteRoomRequest	The body of the request. It is required even though the deletion does not depend on what it holds.	[required]

Responses

Status code	Description	Type	Response headers
200	The queued delete operation to poll	FileOperationWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileOperationWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteRoomLogo

FolderIntegerWrapper deleteRoomLogo(id)

DELETE /api/2.0/files/rooms/{id}/logo

Remove a room logo

Removes the uploaded logo of a room and returns the room with empty logo addresses. What the room falls back to is its cover and colour, which the logo only hid: if a cover was set before the logo, it is shown again, and POST api/2.0/files/rooms/{id}/cover is what changes it. Nothing else about the room is touched, so membership, tags, links and settings are preserved. A room that has no logo is accepted and answered with 200, and repeating the call is therefore harmless. The caller must be a manager of the room; a member invited even with editing rights is refused, and so is a room in the Archive section. A room that does not exist or was deleted is answered as missing. After the logo is removed a new one can be set again through POST api/2.0/files/logos followed by POST api/2.0/files/rooms/{id}/logo.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The room with its logo removed	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

deleteRoomTags

FolderIntegerWrapper deleteRoomTags(id, BatchTagsRequestDto)

DELETE /api/2.0/files/rooms/{id}/tags

Detach tags from a room

Detaches the named tags from a room and returns the room with its remaining tag set. Only the link between the room and the tag is removed: the tag stays in the portal catalogue and keeps working for every other room, and DELETE api/2.0/files/tags is what removes it from the portal itself. Names that are not in the catalogue, or not attached to this room, are skipped without an error, so a successful answer does not prove that anything was detached; compare the returned tag set instead. An empty list is accepted and does nothing, while a null entry in the list is rejected as an invalid request. The caller must be a manager of the room or an administrator of the portal, and a room in the Archive section is refused with 403. A tag that loses its last room stays in the catalogue, and only deleting that room takes the tag with it.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room whose tags are changed, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
BatchTagsRequestDto	body	BatchTagsRequestDto	The names to attach or to detach.	[optional]

Responses

Status code	Description	Type	Response headers
200	The room with its tag set after the change	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not edit this room, or the room is archived	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ExternalDbSyncTaskWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

getExternalDbSyncStatus

ExternalDbSyncTaskWrapper getExternalDbSyncStatus(id)

GET /api/2.0/files/rooms/{id}/externaldbsync

Get external DB sync status

Returns the record of the external database export job of a form filling room, or an empty body when the room has no job at all. The room must be a form filling room and the caller must be able to edit it, otherwise the call is refused; an unknown room is answered with 404. This is the polling target of POST api/2.0/files/rooms/{id}/externaldbsync: repeat it until isCompleted is true, and then read forms, which lists one entry per original form with its own success and error and is empty while the job is still running. percentage advances as forms are processed, status distinguishes a job that is queued, running, finished or failed, and error carries the message of a job that stopped as a whole. The record belongs to the room rather than to the account that started the job, so any member who can edit the room sees the same answer. The call changes nothing and is safe to repeat.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The synchronization job record, or an empty body when the room has no job	ExternalDbSyncTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
404	No room with this ID is visible to the caller	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getNewRoomItems

NewItemsFileEntryBaseArrayWrapper getNewRoomItems(id)

GET /api/2.0/files/rooms/{id}/news

Get new items in a room

Returns what is new for the calling account in one room, grouped by the day the entry was last changed, with the newest day first and the entries inside a day ordered from the most recent. Only files are reported: a folder somebody else created is not an entry of its own, while a file created inside it is, however deep it lies. What the caller changed is never new for the caller, and a file that was deleted afterwards disappears from the answer. Reading this list leaves the badges alone, which is what makes it the operation to call before GET api/2.0/files/rooms/{id}, since opening the room clears them. An empty array therefore means that there is nothing new, not that the badges were already read. The caller needs access to the room; somebody who is not a member is refused, and an unknown or deleted room is answered as missing. Use GET api/2.0/files/rooms/news for the same report across every room at once.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The new files of the room, grouped by day	NewItemsFileEntryBaseArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

NewItemsFileEntryBaseArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getPublicSettings

BooleanWrapper getPublicSettings(id)

GET /api/2.0/files/roomtemplate/{id}/public

Get room template public access

Reports whether the room template addressed by id is shared with everyone or is reachable only by the accounts it was explicitly shared with. True means the Everyone group holds read access, so any member allowed to create rooms can build one from the template with POST api/2.0/files/rooms/fromtemplate; false means only the owner and the named recipients can. The identifier has to belong to a room template — take it from templateId of GET api/2.0/files/roomtemplate/status, or from the folder list of GET api/2.0/files/rooms called with searchArea set to 4 — while an ordinary room, a deleted template or an unknown value is answered as missing. The caller needs read access to the template, so somebody else's private template is refused even for a portal administrator, and members who cannot reach the Templates section at all are refused whatever the template's state. The call only reads state; use PUT api/2.0/files/roomtemplate/public to change it.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The identifier of the room template. Take it from `templateId` of `GET api/2.0/files/roomtemplate/status`, or from the folder list of `GET api/2.0/files/rooms` called with `searchArea` set to 4; an identifier of an ordinary room is not accepted.	[required] [example: `1234`] [min: 1] [max: 2147483647]

Responses

Status code	Description	Type	Response headers
200	Ok	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

CoversResultArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomCovers

CoversResultArrayWrapper getRoomCovers()

GET /api/2.0/files/rooms/covers

Get room cover gallery

Returns the gallery of cover pictures a room can be given: every entry pairs the identifier to send to POST api/2.0/files/rooms/{id}/cover with the drawing itself as inline vector markup ready to be rendered. The gallery is built into the product rather than stored per portal, so it is the same for every account and every room, does not depend on what rooms exist, and its identifiers do not change with the language of the request. The identifiers are unique and stable, which makes them safe to keep in a client, while the drawings behind them may change between product versions. Any account of the portal may read the gallery, but a guest is refused. The list is the only source of valid cover identifiers: a value that is not in it is rejected wherever a cover is set, including room creation and room update. The call changes nothing and is safe to repeat.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The built-in room covers with their identifiers and vector markup	CoversResultArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomCreatingStatus

RoomFromTemplateStatusWrapper getRoomCreatingStatus()

GET /api/2.0/files/rooms/fromtemplate/status

Get the room creation progress

Returns the progress of the room-from-template job started by the calling account with POST api/2.0/files/rooms/fromtemplate. The record is private to the account that started the job: jobs of other members are never reported, and only one record is kept per account. The body is empty when the account has no such record, and it is also empty when the job queue cannot be read, so an empty answer is not proof that nothing was started. progress is a percentage, isCompleted marks the end of the job whether it succeeded or failed, error carries the failure message and is empty on success, and roomId is meaningful only once the room exists. The record survives the end of the job and is dropped when the next creation starts, so polling after completion keeps returning the same answer. Poll this operation until isCompleted is true and then read the room itself with GET api/2.0/files/rooms/{id}. The call changes nothing and is safe to repeat.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The progress record of the caller room creation job, or an empty body when there is none	RoomFromTemplateStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

RoomFromTemplateStatusWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomIndexExport

DocumentBuilderTaskWrapper getRoomIndexExport()

GET /api/2.0/files/rooms/indexexport

Get the room index export

Returns the state of the index export of the calling account, the job started by POST api/2.0/files/rooms/{id}/indexexport. The record is not addressed by room: there is at most one per account, and the answer describes the latest export whichever room it was started for. When the account has never started one, or its record was cancelled, the body is null rather than an error, so null is the normal way of saying that there is nothing to report. While the job runs, percentage moves in coarse steps instead of smoothly, which makes it a rough hint rather than a measure of the remaining time; isCompleted is the field to wait on, and it is also set for a job that failed or was cancelled, so read status to tell the outcomes apart and error for the message. After a successful build, resultFileId, resultFileName and resultFileUrl point to the spreadsheet saved in the My documents section of the caller. The record survives completion and is replaced only by the next export.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The state of the export, or null when the account has none	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomInfo

FolderIntegerWrapper getRoomInfo(id)

GET /api/2.0/files/rooms/{id}

Get room information

Returns one room with its type, title, tags, logo, cover, colour, quota and virtual data room settings, together with the access level the caller has in it. Reading the room is not a side-effect-free call: it clears the caller new-item badges for that room, and newForMe comes back as 0, so read GET api/2.0/files/rooms/{id}/news first when the new items matter. The caller needs read access to the room; portal administrators can read a room they were never invited to, while a member without access is refused. The operation also answers an anonymous caller, but only in the context of a valid external share link of that room, and a plain anonymous request is rejected as unauthenticated. A room that never existed, was deleted, or lives in a section the caller cannot see is answered as missing. Archived rooms are returned as well and are recognised by their root section rather than by a separate flag. Use GET api/2.0/files/rooms to search and page through rooms instead of guessing ids.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The room with its settings and the access level of the caller	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomLinks

FileShareArrayWrapper getRoomLinks(id, type)

GET /api/2.0/files/rooms/{id}/links

Get the room links

Returns the sharing links of a room, with the invitation and the external links mixed together unless type narrows it to one kind. Each entry carries the link address, its title, access level, expiration, the flag that marks the primary external link of the room and, for invitation links, how many times it may still be used. Public and form filling rooms come with an external link created for them, so an empty answer there means that the link was revoked rather than that the room is private; rooms of the other kinds start with no links at all and only gain one when somebody creates it, which for a collaboration room and a virtual data room can be an invitation link alone. The caller needs access to the room and the right to see its links: a member invited without that right gets an empty list rather than an error, while somebody who is not in the room at all is refused. Paging parameters are not honoured here: the first hundred links are returned and the reported count is the number of entries actually sent.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room whose links are listed, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
type	query	LinkType	Narrows the answer to one kind of link: invitation links, which turn whoever opens them into a member, or external links, which open the room without an account. Leaving it out returns both kinds together.	[optional] [example: `1`] [enum: `0`, `1`]

Responses

Status code	Description	Type	Response headers
200	The sharing links of the room	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomSecurityInfo

FileShareArrayWrapper getRoomSecurityInfo(id, filterType, count, startIndex, filterValue)

GET /api/2.0/files/rooms/{id}/share

Get the room access rights

Returns one page of the access list of a room: the owner first, then the managers, the groups, the ordinary members, the guests and finally the invitations nobody has accepted yet, with the total in the response headers. filterType selects what is listed and defaults to accounts and groups, which leaves the sharing links of the room out; those are read with GET api/2.0/files/rooms/{id}/links. filterValue matches the displayed name of the subject, and an invitation that is still pending is listed under the email address it was sent to. Paging is done with count and startIndex, and the order is stable between calls. Any member who can read the room sees the accounts and the groups, so the list is not limited to the managers, and portal administrators can read the list of a room they were never invited to; somebody who is not in the room at all is refused. Asking for the link entries instead needs the right to see the links of the room, and a member without it gets an empty page rather than an error.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room whose access list is read, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
filterType	query	ShareFilterType	What kind of access entries to list. The default covers accounts and groups and leaves the sharing links of the room out; those are read with `GET api/2.0/files/rooms/{id}/links`.	[optional] [example: `0`] [enum: `0`, `1`, `2`, `4`, `8`, `15`, `16`, `32`]
count	query	Integer (int32)	How many entries to return in one answer. The total number of matching entries comes back in the response headers, so it is what tells the caller whether another page is needed.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many matching entries to skip before the page starts. Together with the page size it walks the list, which is ordered by role and then by name and is therefore stable between calls.	[optional] [example: `0`]
filterValue	query	String	Keeps only the entries whose displayed name contains this text. An invitation that has not been accepted yet is listed under the email address it was sent to, so that is what has to be searched for.	[optional] [example: `Smith`]

Responses

Status code	Description	Type	Response headers
200	One page of the room access entries, ordered by role and then by name	FileShareArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

RoomTemplateStatusWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomTagsInfo

STRINGArrayWrapper getRoomTagsInfo(count, startIndex, filterValue)

GET /api/2.0/files/tags

Get available room tags

Returns the custom room tags available to the caller as a flat array of names, not of objects. What the array holds depends on the account: a portal administrator gets the whole catalog, including tags that no room uses yet, while every other account gets only the tags attached to rooms it can see, with duplicates removed. An empty answer therefore means that this caller sees no tagged room, not that the portal has no tags. filterValue keeps the names that contain the given text, ignoring case, while count and startIndex page the result; no total is returned, so a page shorter than count is the signal that the list is exhausted. The names are exactly the values accepted by the tags filter of GET api/2.0/files/rooms and by the room tag calls, which makes this the call to fill a tag picker with. Add a tag with POST api/2.0/files/tags and check whether one is still in use with GET api/2.0/files/tags/{tagName}/haslinks.

Parameters

Name	In	Type	Description	Notes
count	query	Integer (int32)	How many tag names one page may carry. The answer reports no total, so a page shorter than this is the sign that the list is exhausted.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many tag names to skip before the page begins. Raise it by the number of names already received to read the next page.	[optional] [example: `0`] [min: 0] [max: 2147483647]
filterValue	query	String	Keeps only the tag names that contain this text, ignoring case. It is a substring match, so a fragment from the middle of a name is enough.	[optional] [example: `conf`]

Responses

Status code	Description	Type	Response headers
200	The tag names available to the caller	STRINGArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

STRINGArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomTemplateCreatingStatus

RoomTemplateStatusWrapper getRoomTemplateCreatingStatus()

GET /api/2.0/files/roomtemplate/status

Get room template creation status

Reports the state of the room template creation the caller started with POST api/2.0/files/roomtemplate. The record is private to the account that started the job: work started by another member is never reported, and a caller who has started none gets an empty response instead of an object. Poll until isCompleted turns true, then take the identifier of the finished template from templateId; a non-empty error means the job failed and no template was kept. Treat isCompleted as the completion signal rather than progress, which the background job only sets to 100 once the work is over. The record outlives the job, so a finished operation can be read again and keeps returning the same identifier until the caller starts another template creation, which replaces it. The call only reads state and needs no access to the source room or to the template, but it does require an authenticated caller.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	Status	RoomTemplateStatusWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomsFolder

FolderContentIntegerWrapper getRoomsFolder(type, subjectId, subjectOwnerId, searchArea, withoutTags, tags, excludeSubject, provider, quotaFilter, storageFilter, privacyFilter, count, startIndex, sortBy, sortOrder, filterValue, groupId)

GET /api/2.0/files/rooms

Get rooms

Lists the rooms of one section of the portal: the active rooms by default, or the archive, the form-filling section or the room templates, chosen with searchArea. The rooms arrive in folders while files stays empty, current describes the section itself, and total counts every room that matched the filters before paging. A caller sees only the rooms they created or were invited to, while a portal administrator sees all of them, so an empty answer means nothing is visible to this account rather than nothing exists. The remaining parameters narrow the same set, by room type, title, tags, member, owner, storage, quota and privacy, and they combine with each other. Sorting is not free of side effects: a sortBy value is also stored as this account's default order for later listings, and omitting it reuses the stored order. Page the result with count and startIndex. Read a single room with GET api/2.0/files/rooms/{id}, and create one with POST api/2.0/files/rooms.

Parameters

Name	In	Type	Description	Notes
type	query	List	Keeps only the rooms of the listed kinds. Repeat the parameter to pass more than one value; they are combined with OR, and omitting it returns the rooms of every kind.	[optional] [example: `1`]
subjectId	query	UUID (uuid)	Keeps only the rooms this account or group has access to, which is how the rooms of one member are listed. The identifier comes from the portal people and group listings, and the exclude flag turns the filter into its opposite.	[optional] [example: `9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9`]
subjectOwnerId	query	UUID (uuid)	Keeps only the rooms created by this account, regardless of who else was invited to them. The identifier comes from the portal people listing, and the exclude flag turns the filter into its opposite.	[optional] [example: `9a1b2c3d-4e5f-6071-8293-a4b5c6d7e8f9`]
searchArea	query	SearchArea	The section to list. Every section is a separate root and a room belongs to exactly one of them at a time, so archiving a room moves it out of the active section. The default is the active section, which leaves the form-filling rooms to their own value.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`]
withoutTags	query	Boolean	When true, keeps only the rooms that carry no tag at all, which is the complement of the tag filter. When false or omitted, tags play no part in the selection.	[optional] [example: `false`]
tags	query	String	A JSON array of tag names serialized into a single query value, for example [Important,Legal]. A room matches when it carries any one of them. Take the names from `GET api/2.0/files/tags`; a name that is not in the catalog simply matches nothing.	[optional] [example: `["Important"]`]
excludeSubject	query	Boolean	Inverts the two subject filters: when true, the rooms of the named account are the ones left out of the answer instead of the only ones kept. It does nothing on its own.	[optional] [example: `false`]
provider	query	ProviderFilter	Keeps only the rooms whose content lives in the named third-party service, for portals where rooms may be connected to external storage. The default keeps rooms of every origin.	[optional] [example: `1`] [enum: `0`, `1`, `2`, `3`, `4`, `5`, `6`, `7`, `8`, `9`]
quotaFilter	query	QuotaFilter	Splits the rooms by whether a storage quota was set on the room itself or it follows the portal default, which is how rooms with a custom limit are found.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
storageFilter	query	StorageFilter	Splits the rooms by where their content is stored, in the portal itself or in a connected third-party account. It is the coarse form of the provider filter.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
privacyFilter	query	RoomPrivacyFilter	Splits the rooms by whether they are private, that is encrypted rooms whose content the portal cannot read. Omitting it returns both kinds.	[optional] [example: `1`] [enum: `0`, `1`, `2`]
count	query	Integer (int32)	How many rooms one page may carry. Ask for the next page by raising the start index by the number of rooms already received.	[optional] [example: `25`] [min: 1] [max: 100]
startIndex	query	Integer (int32)	How many matching rooms to skip before the page begins. Page through the answer until the skip plus the rooms received reaches the total it reports.	[optional] [example: `0`]
sortBy	query	String	The field to order the rooms by, named as in the file listings: `AZ` for the title, `DateAndTime` for the last change, `DateAndTimeCreation`, `Author`, `Size`, `Type`, `RoomType`, `Tags`, `UsedSpace`, `LastOpened`. The name is matched ignoring case, an unknown one is rejected rather than ignored, and the accepted one also becomes this account's stored order.	[optional] [example: `DateAndTime`]
sortOrder	query	SortOrder	The direction of the order chosen by the sort field. It has no effect when no sort field is given and the stored order of the account is used.	[optional] [example: `1`] [enum: `0`, `1`]
filterValue	query	String	Keeps only the rooms whose title contains this text, ignoring case. It is a substring match over the title alone: room content and tags are not searched.	[optional] [example: `Sales`]
groupId	query	Integer (int32)	Keeps only the rooms that belong to this room group. The identifier comes from `GET api/2.0/files/group`; the groups of portal members are a different concept and their identifiers do not match here.	[optional] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The rooms of the selected section with the paging counters	FolderContentIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller cannot read the selected section	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

NewItemsRoomNewItemsArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomsNewItems

NewItemsRoomNewItemsArrayWrapper getRoomsNewItems()

GET /api/2.0/files/rooms/news

Get new items in all rooms

Collects everything that is marked as new for the caller across the active rooms into one answer, grouped first by the day an entry changed and then by the room it belongs to. An entry becomes new when somebody else creates or changes it in a room the caller has already opened, so the caller's own work never shows up here, and neither does anything from a room they have never visited. Only files are listed: a new subfolder is not an item, although files created inside it are, at any depth. The days come newest first, and inside a day the rooms and their files follow the same order by change time. The archive is out of scope, only rooms of the active section are covered. Reading the list clears nothing: the marks stay until the room itself is opened with GET api/2.0/files/rooms/{id}. An empty array means that this account has nothing new. For one room, use GET api/2.0/files/rooms/{id}/news.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The new entries of every active room, grouped by day and by room	NewItemsRoomNewItemsArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomsPrimaryExternalLink

FileShareWrapper getRoomsPrimaryExternalLink(id)

GET /api/2.0/files/rooms/{id}/link

Get the room primary external link

Returns the primary external link of a room, which is the one address meant to be handed out to people outside the portal. A public room and a form filling room get such a link when they are created, and asking for it again returns the same link rather than a new one, so the answer is stable. In a room that has no primary link yet this call creates one instead of reporting nothing, which needs the right to manage the links of the room: a member invited with a lower level is refused with 403, and so is anybody who is not in the room at all. A link that was explicitly revoked stays revoked and is reported as missing rather than recreated, and an unknown room is answered with 404 as well. An archived public room still reports its link. The answer is the same entry that GET api/2.0/files/rooms/{id}/links returns with the primary flag set, including the request token that has to travel with the address.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The primary external link of the room	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	The caller may not see the links of this room	-	-
404	No room with this ID is visible to the caller, or its primary link was revoked	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

hasTagLinks

BooleanWrapper hasTagLinks(tagName2, tagName)

GET /api/2.0/files/tags/{tagName}/haslinks

Check room tag usage

Reports whether any room still carries the named tag, which is the check to run before the tag is deleted from the catalog. Only a portal administrator may call it, and every other account is refused. The name is matched exactly against the catalog, and a name that is not in it is answered with 404. That also tells the two ways a tag stops being used apart: taking the tag off the last room that carried it leaves the tag in the catalog and turns the answer to false, while deleting that last room removes the tag itself, after which the call answers 404. A true answer means at least one room, active or archived, still references the tag, so deleting it with DELETE api/2.0/files/tags would strip it from those rooms. The handler reads the tag name from the query string, so the value has to be sent twice: in the path segment and as the tagName query parameter.

Parameters

Name	In	Type	Description	Notes
tagName2	path	String	The tag being checked. Send the same value as the `tagName` query parameter, which is the one the handler reads.	[required]
tagName	query	String	The tag to check, spelled exactly as it is stored in the catalog. This query value is the one the handler reads, so the path segment of the same name has to repeat it.	[optional] [example: `Important`]

Responses

Status code	Description	Type	Response headers
200	True when at least one room still carries the tag	BooleanWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
404	No tag with this name exists in the catalog	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

pinRoom

FolderIntegerWrapper pinRoom(id)

PUT /api/2.0/files/rooms/{id}/pin

Pin a room

Pins a room to the top of the room list of the calling account and returns the room with the pinned flag set. Pinning is personal: it changes the order only for the caller, is invisible to the other members of the room, and does not survive a trip through the Archive section, so an unarchived room has to be pinned again. Pinned rooms stay above the unpinned ones whatever sorting or filter the listing uses, and their own order between each other is stable. An account may keep only a limited number of pinned rooms at a time, ten on a portal with the default configuration, and AI rooms are counted separately against their own allowance; a request over the limit is refused until something is unpinned with PUT api/2.0/files/rooms/{id}/unpin. Pinning a room that is already pinned changes nothing and is safe to repeat. Anybody who can read the room may pin it, including guests and portal administrators who were never invited, while somebody who is not in the room is refused, an archived room is rejected and an unknown room is answered as missing.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The room with its pinned flag set for the caller	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

reorderRoom

FolderIntegerWrapper reorderRoom(id)

PUT /api/2.0/files/rooms/{id}/reorder

Reorder room contents

Renumbers the manual order of the items lying directly in a room so that they run from one upwards with no gaps and no duplicates, and returns the room. The order of the items relative to each other is preserved: only the numbers are compacted, and nothing is moved, renamed, duplicated or deleted. Files and folders share one sequence. Nested folders keep their own numbering and are not touched, so each level is compacted on its own. The operation is meant for a room with indexing turned on, where the manual order is what listings follow; a room without indexing accepts it and simply has nothing that depends on the result. Running it twice changes nothing the second time, and an already dense sequence is left as it is, which makes the call safe to retry. The caller must be a manager of the room; a member invited with any other level is refused, an archived room is rejected, and an unknown or deleted room is answered as missing.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The room whose contents were renumbered	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

resendEmailInvitations

resendEmailInvitations(id, UserInvitation)

POST /api/2.0/files/rooms/{id}/resend

Resend the room invitations

Sends the room invitation email again to members who were invited but have not joined yet. resendAll covers every pending invitation of the room and makes usersIds irrelevant, while an explicit list without that flag is limited to the named accounts. An account that has already accepted the invitation, is not a member of the room, or is invisible to the caller is skipped without an error, and a request that names nobody and does not set the flag does nothing, so a successful answer never proves that a message went out. Nothing about the room or its membership changes, and the operation can be repeated. The caller must be a manager of the room, an archived room is refused, a room template is answered as missing, and a malformed account id is rejected as an invalid request. The call is rate limited, so a client that loops over members should send one batch instead. The response carries no body.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room whose invitations are resent, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
UserInvitation	body	UserInvitation	Which pending invitations to send again.	[required]

Responses

Status code	Description	Type	Response headers
200	The invitations that were still pending have been sent again	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setPublicSettings

setPublicSettings(SetPublicDto)

PUT /api/2.0/files/roomtemplate/public

Set room template public access

Switches the room template named by id between shared with everyone and private, rewriting its whole recipient list in the process. With public true the Everyone group is granted read access, so every member allowed to create rooms can build one from the template with POST api/2.0/files/rooms/fromtemplate; with false that access is taken away. In both cases every other account and group the template was shared with — including the addresses passed as share when it was created — loses access, so this is not a way to add a single recipient to an existing list. Only the account that owns the template may call it: a portal administrator who does not own it is refused, and so is a member invited to the source room. The identifier has to resolve to a room template; an ordinary room or an unknown value is answered as missing, and an identifier below 1 is rejected as an invalid request. Repeating the call with the same value changes nothing, and nothing is returned; read the current state with GET api/2.0/files/roomtemplate/{id}/public.

Parameters

Name	In	Type	Description	Notes
SetPublicDto	body	SetPublicDto		[optional]

Responses

Status code	Description	Type	Response headers
200	Ok	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setRoomLink

FileShareWrapper setRoomLink(id, RoomLinkRequest)

PUT /api/2.0/files/rooms/{id}/links

Set the room external or invitation link

Creates, updates or deletes one sharing link of a room and returns it. linkType chooses the kind: an invitation link makes whoever opens it a member with the given access level, while an external link opens the room without an account. Omitting linkId creates a link, passing the id of an existing one updates it, and an unknown id is created with that id; the kind of an existing link cannot be changed afterwards. An access level of 0 deletes the link, and deleting the primary external link of a public or form filling room immediately replaces it with a fresh one, so such a room is never left without one. A room keeps at most one invitation link, and a second one is refused; form filling rooms take no invitation links, and collaboration, form filling and virtual data rooms take no external links. An expiration date in the past is dropped silently for an external link and rejected for an invitation link. password, denyDownload and internal apply to external links only.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room the link belongs to, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
RoomLinkRequest	body	RoomLinkRequest	The link to create, change or revoke.	[required]

Responses

Status code	Description	Type	Response headers
200	The link as it is after the change, or an empty body when nothing was created	FileShareWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

ExternalDbSyncTaskWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setRoomSecurity

RoomSecurityWrapper setRoomSecurity(id, RoomInvitationRequest)

PUT /api/2.0/files/rooms/{id}/share

Set the room access rights

Adds, changes and removes room members in one batch, and returns the resulting access list of the named subjects. Each entry names either an account or a group of the portal, or the email address of somebody who has no account yet, together with the access level to grant; an access of 0 removes the subject from the room. An entry without an access level is ignored, the same subject listed twice keeps the last level, and an empty list is accepted and changes nothing. The caller must be a manager of the room, so an invitation sent by a user or a guest is refused, and an account that is a portal user or a guest cannot be made a room manager. Inviting by email also needs the portal to allow guest invitations. A subject the caller is not allowed to see is dropped without an error, which is why the answer has to be compared with the request. Removing a member who still holds a form role is refused through error unless force is set. notify sends the invitation email with the optional message.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room whose membership changes, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
RoomInvitationRequest	body	RoomInvitationRequest	The membership changes to apply, together with how the people concerned are notified.	[required]

Responses

Status code	Description	Type	Response headers
200	The access entries of the named subjects, plus a warning or an error when something was not applied	RoomSecurityWrapper	-
401	Unauthorized	ErrorApiResponse	-
500	Internal Server Error.	ErrorApiResponse	-
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

RoomSecurityWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

startExternalDbSync

ExternalDbSyncTaskWrapper startExternalDbSync(id)

POST /api/2.0/files/rooms/{id}/externaldbsync

Start external DB sync

Queues a background job that re-exports the collected data of every original form of a form filling room into the external database configured for the portal, and returns the job record. The room must be a form filling room and the caller must be able to edit it, otherwise the call is refused with 403; an unknown room is answered with 404. The export is not done when the response arrives: poll GET api/2.0/files/rooms/{id}/externaldbsync until isCompleted is true, then read forms for the per-form outcome, which stays empty while the job is running. Starting the job again while it is still running returns the same record instead of a second job, so a retry is safe; a finished job is replaced by the new one. One job is kept per room. A form whose data cannot be exported does not stop the others: it comes back in forms with success false and its own error. When the portal has no external database configured the call fails and nothing is queued.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The synchronization job record to poll	ExternalDbSyncTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The portal has no external database configured	-	-
403	The room is not a form filling room, or the caller cannot edit it	-	-
404	No room with this ID is visible to the caller	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

startRoomIndexExport

DocumentBuilderTaskWrapper startRoomIndexExport(id)

POST /api/2.0/files/rooms/{id}/indexexport

Start the room index export

Queues a background job that builds the index of a virtual data room as a spreadsheet, and answers with the job record to poll. The room has to be a virtual data room with indexing switched on, and the caller has to be its manager or a portal administrator; any other kind of room, a room template, and a member invited with a lower access level are refused, while an unknown room is answered as missing. There is one job per account: starting an export while an earlier one is still running answers with that earlier record instead of queuing a second job, and a finished record is replaced by the new one. Poll GET api/2.0/files/rooms/indexexport until isCompleted is true, then read status to tell a completed job from a failed or cancelled one, and take resultFileId and resultFileUrl from the same record. The report is saved as a spreadsheet in the My documents section of the caller, not in the room. Cancel a running job with DELETE api/2.0/files/rooms/indexexport.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The queued export job to poll	DocumentBuilderTaskWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
501	Folder indexing is turned off	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

terminateRoomIndexExport

terminateRoomIndexExport()

DELETE /api/2.0/files/rooms/indexexport

Terminate the room index export

Cancels the room index export of the calling account and drops its job record. No room is named because there is at most one export per account, so the call always acts on the caller's own job and never on somebody else's: an account with nothing running gets a successful answer that changes nothing, which makes the call safe to repeat and makes it useless as a way of stopping an export somebody else started. Afterwards GET api/2.0/files/rooms/indexexport answers with an empty body until a new export is started with POST api/2.0/files/rooms/{id}/indexexport. The cancellation is asynchronous: the background job stops at its next checkpoint, so one that is already saving the file may still finish, and a report that was written before the cancellation stays in the My documents section of the caller and has to be deleted as an ordinary file. The answer carries no body and says nothing about whether an export was running.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The export of the calling account was cancelled, if there was one	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

unarchiveRoom

FileOperationWrapper unarchiveRoom(id, ArchiveRoomRequest)

PUT /api/2.0/files/rooms/{id}/unarchive

Unarchive a room

Queues a background job that moves one room from the Archive section back to the Rooms section, and returns the operation record of that job. The room becomes writable again with the membership, tags, logo and links it had before, while the pinned state of its members is not restored and has to be set again with PUT api/2.0/files/rooms/{id}/pin. The caller must be a manager of the room; a member who was only invited to it is refused, a room template is answered as missing, and a room that was never archived simply stays where it is. The room is not moved when the response arrives: poll GET api/2.0/files/fileops until finished is true, and expect a room that is still archived until then. deleteAfter decides only how long the finished record survives. Calling the operation twice in a row does not corrupt the room, and a deleted or unknown room id is reported as missing.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to move, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
ArchiveRoomRequest	body	ArchiveRoomRequest	The body of the request. It carries only the lifetime of the job record, so an empty object is a normal request.	[optional]

Responses

Status code	Description	Type	Response headers
200	The queued unarchive operation to poll	FileOperationWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

FileOperationWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

unpinRoom

FolderIntegerWrapper unpinRoom(id)

PUT /api/2.0/files/rooms/{id}/unpin

Unpin a room

Removes a room from the pinned group of the calling account and returns the room with the pinned flag cleared. Only the personal ordering of the caller changes: the room itself, its members, their roles and its contents are left exactly as they were, and the room stays in the list, simply among the unpinned ones. Unpinning frees one of the pin slots of the account, which AI rooms count separately, so it is the way out of a refused PUT api/2.0/files/rooms/{id}/pin. Unpinning a room that was never pinned is accepted and changes nothing, so the call can be repeated safely and its answer does not prove that anything was pinned before. Anybody who can read the room may unpin it, while somebody who is not in the room at all is refused and an unknown or deleted room is answered as missing. An archived room cannot be unpinned.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to act on, named by the identifier that `GET api/2.0/files/rooms` reports for it. Rooms kept in the portal itself use whole numbers, while a room backed by a connected third-party account uses the string form of the same listing.	[required] [example: `1`]

Responses

Status code	Description	Type	Response headers
200	The room with its pinned flag cleared for the caller	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateRoom

FolderIntegerWrapper updateRoom(id, UpdateRoomRequest)

PUT /api/2.0/files/rooms/{id}

Update a room

Applies a partial change to one room and returns the whole room as it is after it. Only the fields present in the body are touched, an empty body changes nothing, and a property the body does not define is rejected as an invalid request instead of being ignored. The caller must be a manager of this room: portal administrators do not get in without an invitation, and an archived room is refused. title is trimmed, sanitised the way a room title is sanitised at creation, and a blank value is treated as no change. tags replaces the whole tag set and an empty array clears it, an empty color restores the default and an empty cover removes the cover. A quota of -1 switches the room back to no custom limit, any other negative value restores the portal default, and a positive one is accepted only while the per-room quota feature is on. Turning indexing on renumbers the room contents. chatSettings belongs to an AI room and is rejected anywhere else. Use POST api/2.0/files/rooms/{id}/logo for logo cropping.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room to update, named by the identifier that `GET api/2.0/files/rooms` reports for it.	[required] [example: `1`]
UpdateRoomRequest	body	UpdateRoomRequest	The fields to change. Only the properties present in the object are applied, and a property that the object does not define is rejected instead of being ignored.	[required]

Responses

Status code	Description	Type	Response headers
200	The room as it is after the update	FolderIntegerWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

updateRoomTag

StringWrapper updateRoomTag(UpdateTagRequestDto)

PUT /api/2.0/files/tags

Rename a room tag

Renames a custom room tag in the portal catalog. The rename follows the tag everywhere it is used: every room that carries it keeps it and shows the new name, so nothing has to be re-attached afterwards. Only a portal administrator may rename a tag, and a room manager who is allowed to create tags is still refused here. The old name is matched exactly as it is stored rather than searched for, and a name that is not in the catalog is answered as missing. A new name that another tag already occupies is rejected as an invalid request, because tag names are unique across the portal; both names must be non-blank and within the published length limit. The answer is the new name. Stored queries are not updated for the caller: a tags filter of GET api/2.0/files/rooms that still names the old value stops matching anything. The catalog is read with GET api/2.0/files/tags.

Parameters

Name	In	Type	Description	Notes
UpdateTagRequestDto	body	UpdateTagRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The new name of the renamed tag	StringWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
403	Only a portal administrator can rename a tag	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

uploadRoomLogo

UploadResultWrapper uploadRoomLogo(File)

POST /api/2.0/files/logos

Upload a room logo image

Stores an image in temporary storage and answers with the path to it, which is the first half of setting a room logo. No room changes here: pass the returned path as tmpFile to POST api/2.0/files/rooms/{id}/logo, together with the crop rectangle, to make the image the logo of a room. The image travels as multipart form data, and the first file part of the request is the one that is used while any other part is ignored. It is re-encoded to PNG and scaled down to fit 1280 by 1280 pixels, so a larger picture is accepted and shrunk, while a part that is not a readable image, or one over the portal limit for uploaded images, is refused with 400. Only a room manager or a portal administrator may upload, and everyone else gets 403. Every call produces a new path, and an image that is never used stays in temporary storage until it is cleaned up, so uploading twice is harmless.

Parameters

Name	In	Type	Description	Notes
File	form	File (binary)	The image data.	[optional]

Responses

Status code	Description	Type	Response headers
200	The path of the stored temporary image	UploadResultWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The request carries no image, or the image cannot be used as a logo	-	-
403	Only a room manager or a portal administrator can upload a logo	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

UploadResultWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: multipart/form-data
Accept: application/json

RoomsGroupsApi

addRoomGroup

RoomGroupWrapper addRoomGroup(RoomGroupRequestDto)

POST /api/2.0/files/group

Add a new room group

Creates a room group, a personal collection that gathers rooms the caller already works with under one name and icon; it belongs to the account that created it and is never shown to other members of the portal. Pass the group name, the identifier of one of the built-in covers offered by GET api/2.0/files/rooms/covers, and a list of at least one room - a number for a room stored in the portal, a string for a room on a connected third-party account. Any role may create its own group, a guest included: what is checked is read access to each listed room, not the role of the caller. Repeated identifiers are collapsed, and a value that is not a room identifier at all is rejected as an invalid request. When none of the listed rooms can be read the group is not created; when only some of them can, the group is created with those rooms and the call is still reported as failed, so re-read GET api/2.0/files/group before retrying. A room may sit in several groups, and two groups of the same account may carry the same name. The answer is the stored group with its rooms.

Parameters

Name	In	Type	Description	Notes
RoomGroupRequestDto	body	RoomGroupRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The created room group with the rooms that were linked to it	RoomGroupWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

changeRoomGroupIcon

RoomGroupWrapper changeRoomGroupIcon(id, IconRequest)

POST /api/2.0/files/group/{id}/icon

Change room group icon

Replaces the icon of one of the caller's own room groups and returns the whole group, its name and its rooms left as they were. Send the identifier of one of the built-in covers offered by GET api/2.0/files/rooms/covers; an empty string strips the icon, after which the group comes back with an empty icon, and any other value - including a word that merely reads like one, such as none - is rejected as an invalid request. An uploaded image cannot be used here, unlike the logo of a room. Leaving icon out of the body or sending it as null is accepted and changes nothing, whereas a request that carries no body at all, or a body that is not JSON, is refused. Setting the icon the group already has is accepted as well, so retrying the call is safe. Any role may re-icon its own group, and a group belonging to another account is answered as missing rather than refused, exactly as reading it would be.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room group to re-icon, identified by the value `GET api/2.0/files/group` reports for it. A group of another account cannot be addressed and reads as missing.	[required] [example: `42`]
IconRequest	body	IconRequest	The icon to give the group. A body that leaves the icon out is accepted and changes nothing.	[optional]

Responses

Status code	Description	Type	Response headers
200	The room group with the new icon	RoomGroupWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

deleteRoomGroup

deleteRoomGroup(id, includeMembers)

DELETE /api/2.0/files/group/{id}

Delete a room group

Deletes one of the caller's own room groups. Only the collection goes away: the rooms it gathered, their content and the shares on them are left exactly as they were, and a room that was in no other group simply stops being grouped. Deleting a group of another account is refused, and an identifier that names nothing - because it never existed, or because the group has already been deleted - is answered as missing, so repeating the call after a successful delete does not report success a second time. The operation is destructive and cannot be undone: there is no trash for groups, and rebuilding one means calling POST api/2.0/files/group again with the same name, icon and rooms, which gives it a new identifier. Nothing is returned in the body. The includeMembers parameter is accepted here because the route shares its contract with GET api/2.0/files/group/{id}, and has no effect on what is deleted. Read the group first when the rooms it gathers still have to be recorded somewhere.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room group to act on, identified by the value `GET api/2.0/files/group` reports for it. A group of another account cannot be addressed and reads as missing.	[required] [example: `42`]
includeMembers	query	Boolean	Whether the rooms of the group are listed in the answer: true fills the `rooms` array, false leaves it out and reports only how many there are in `totalRooms`.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	OK	-	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomGroupInfo

RoomGroupWrapper getRoomGroupInfo(id, includeMembers)

GET /api/2.0/files/group/{id}

Get room group info

Returns one room group of the calling account together with the rooms it gathers. Groups are personal: an identifier that belongs to another member is answered the same way as one that was never created or has already been deleted, and a portal administrator is no exception to that rule. Take the identifier from GET api/2.0/files/group, which lists the groups the caller owns. Set includeMembers to false to get the group without the rooms array, which is the cheaper form when only the name, the icon and the number of rooms are needed; totalRooms is filled either way. A room moved to the archive is left out of both rooms and totalRooms while its membership survives, so taking the room out of the archive brings it back into the group. Rooms stored in the portal are listed before rooms on connected third-party accounts. The call is read-only and changes nothing about the group or the rooms it refers to.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room group to act on, identified by the value `GET api/2.0/files/group` reports for it. A group of another account cannot be addressed and reads as missing.	[required] [example: `42`]
includeMembers	query	Boolean	Whether the rooms of the group are listed in the answer: true fills the `rooms` array, false leaves it out and reports only how many there are in `totalRooms`.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The room group with the rooms it gathers	RoomGroupWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

RoomGroupArrayWrapper

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getRoomGroups

RoomGroupArrayWrapper getRoomGroups(includeMembers)

GET /api/2.0/files/group

List room groups

Returns every room group of the calling account, each with the rooms it gathers. Only groups the caller created are listed: groups of other members never appear here, and an account that has never made one gets an empty array back. Set includeMembers to false to leave the rooms array out of every entry and keep the name, the icon and totalRooms alone, which is the cheaper form when the list is only being shown as a menu. Archived rooms are skipped in both the rooms array and the totalRooms count, and reappear once the room is taken out of the archive. The listing is neither paged nor filtered - it always carries the whole set - and the order of the entries is not contractual, so sort them on the client when the order matters. The call is read-only. Use GET api/2.0/files/group/{id} when the identifier of a single group is already known, and POST api/2.0/files/group to add one.

Parameters

Name	In	Type	Description	Notes
includeMembers	query	Boolean	Whether the rooms of each group are listed in the answer: true fills the `rooms` array of every entry, false leaves it out and reports only how many there are in `totalRooms`.	[optional] [example: `true`]

Responses

Status code	Description	Type	Response headers
200	The room groups of the calling account	RoomGroupArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

updateRoomGroup

RoomGroupWrapper updateRoomGroup(id, UpdateRoomGroupRequest)

PUT /api/2.0/files/group/{id}

Update room group

Applies changes to one of the caller's own room groups: a new name, rooms to attach, rooms to detach, or any combination of the three in a single call. A body that carries none of the three ({}) is accepted and changes nothing, while a body that names them and leaves every one of them empty asks for an update that cannot be performed and is rejected as an invalid request. roomsToAdd is resolved the way creation resolves its list: every identifier has to name a room the caller can read, repeats and rooms already in the group are collapsed, and when only part of the list resolves the rest is still attached and the call is reported as failed. roomsToRemove works the other way round - a room already in the group is always detached, even when the caller has since lost access to it, whereas an identifier that is not in the group is resolved first and refused when it names nothing. The steps are applied in order and are not rolled back when a later one fails. A group of another account is answered as missing. The answer is the group as stored after the call.

Parameters

Name	In	Type	Description	Notes
id	path	Integer (int32)	The room group to change, identified by the value `GET api/2.0/files/group` reports for it. A group of another account cannot be addressed and reads as missing.	[required] [example: `42`]
UpdateRoomGroupRequest	body	UpdateRoomGroupRequest	The changes to apply. Carrying none of them leaves the group as it is, and each of them may be sent on its own or together with the others.	[required]

Responses

Status code	Description	Type	Response headers
200	The room group as stored after the change	RoomGroupWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

RoomsPrivacyRoomApi

deleteKeys

deleteKeys(id)

DELETE /api/2.0/privacyroom/keys/{id}

Delete an encryption key

Removes one encryption key pair from the calling user's own key set and answers 204 with no body. The pair is named by the id of an entry of GET api/2.0/privacyroom/keys; the caller's other pairs stay as they are. The call is destructive and cannot be repeated: the key material is gone for good, a second delete of the same id, like an id that was never stored, is answered with 404, and there is no parameter for another user's keys, so an authenticated member only ever deletes their own while a guest is refused. Deleting the last key the caller holds locks them out of the private rooms they belong to, their own rooms included: the rooms and their content survive untouched and stay listed as private, but GET api/2.0/privacyroom/{roomId}/access then refuses the caller until a new key is stored with POST api/2.0/privacyroom/keys. Before DocSpace 4.0 the call answered 200 with the caller's remaining keys, so a client that read that list has to call GET api/2.0/privacyroom/keys instead.

Parameters

Name	In	Type	Description	Notes
id	path	UUID (uuid)	The pair to delete, taken from the `id` of an entry of `GET api/2.0/privacyroom/keys`. Only the caller's own pairs can be named here.	[required] [example: `9924256B-447C-4F19-9dbd-8ad8c39e8ff5`]

Responses

Status code	Description	Type	Response headers
204	The encryption key is deleted. Answered 200 with the remaining keys before DocSpace 4.0	-	-
400	The key identifier is not a valid GUID	-	-
404	The encryption key is not found	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

null (empty response body)

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getUserKeys

EncryptionKeyArrayWrapper getUserKeys()

GET /api/2.0/privacyroom/keys

Get own encryption keys

Returns every encryption key pair the calling user holds, the encrypted private half included, which is the material a client needs in order to decrypt content in a private room. The set is personal and there is no parameter for another user's keys: an authenticated caller reads only their own, and a guest, who cannot own key material at all, always reads an empty set. The call is read-only. An empty answer, whether an empty list or none at all, means no key has been created yet, and until POST api/2.0/privacyroom/keys creates one the user cannot be invited to a private room. Each entry carries the pair's id, its owner in userId, the moment the material was stored in date, the public half, the private half encrypted with the user's password, and the portal-wide crypto engine in cryptoEngineId. For the keys that open a whole private room use GET api/2.0/privacyroom/{roomId}/access, and for the keys a single file is shared with use GET api/2.0/files/file/{fileId}/publickeys; this operation is about the caller alone.

Parameters

This endpoint does not need any parameter.

Responses

Status code	Description	Type	Response headers
200	The encryption keys of the current user	EncryptionKeyArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

getUserKeysForRoom

EncryptionKeyArrayWrapper getUserKeysForRoom(roomId)

GET /api/2.0/privacyroom/{roomId}/access

Get private room access keys

Returns the encryption keys that give access to a private room: one entry per key held by each of its members, which is what a client needs in order to encrypt a file key for everyone allowed to open the room's content. Only the caller's own entries carry privateKeyEnc; another member's entry carries the public half alone, and an entry with no public half is not reported as access at all. The room has to be a private one, a room created without private mode holds no access keys and the call is refused, and it has to still exist: an unknown room, or one already moved to Trash, is reported as missing, while an archived private room still answers. Access follows room membership and not portal role: any member from read access upwards receives the full set, whereas a DocSpace administrator who is not a member is refused, and so is a caller holding no key of their own, the room creator included once they delete their last key. The call is read-only. For the keys of a single file use GET api/2.0/files/file/{fileId}/publickeys.

Parameters

Name	In	Type	Description	Notes
roomId	path	Integer (int32)	The private room whose access keys are read. Take it from the `id` of the room returned by `POST api/2.0/files/rooms` or listed by `GET api/2.0/files/rooms`.	[required]

Responses

Status code	Description	Type	Response headers
200	The encryption keys associated with the privacy room	EncryptionKeyArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	ErrorApiResponse	-
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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: Not defined
Accept: application/json

replaceKey

EncryptionKeyArrayWrapper replaceKey(EncryptionKeyRequestDto)

PUT /api/2.0/privacyroom/keys

Rotate an encryption key

Rotates one encryption key pair of the calling user: the entry whose id matches is overwritten with the submitted publicKey and privateKeyEnc, and the caller's other pairs are left untouched. The pair has to exist already, an id that is not in the caller's set is answered with 404, and a first key is created with POST api/2.0/privacyroom/keys. This is a full replacement rather than a merge: both halves are mandatory, and a request that omits or blanks one of them is rejected as invalid with the stored pair surviving unchanged, so a rotation that means to keep the private half has to send it again. Omitting id targets the all-zero pair, the one a client that never sets an id keeps rotating. Every authenticated member rotates their own keys and only their own, and a guest is refused. The call is mutating, and repeating it with the same body leaves the same state. It answers with every key the caller holds afterwards, and from then on GET api/2.0/privacyroom/{roomId}/access reports the new public half for this member.

Parameters

Name	In	Type	Description	Notes
EncryptionKeyRequestDto	body	EncryptionKeyRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
200	The encryption key is replaced	EncryptionKeyArrayWrapper	`X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`
400	The key material is missing, blank or too large to be stored	-	-
404	The encryption key to replace is not found	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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

Authorization

Basic, OAuth2 (scopes: read, write), ApiKeyBearer, asc_auth_key, Bearer, OpenId

HTTP request headers

Content-Type: application/json
Accept: application/json

setKeys

EncryptionKeyArrayWrapper setKeys(EncryptionKeyRequestDto)

POST /api/2.0/privacyroom/keys

Create an encryption key

Stores a new encryption key pair for the calling user and answers with that user's whole key set. The material is end-to-end: publicKey is the half other members use to encrypt file keys for this user, while privateKeyEnc arrives already encrypted with the user's own password, so the portal keeps it as opaque text. A member must hold at least one key before they can be invited to a private room, which makes this the first call of the private-room flow. Every authenticated member manages their own keys and only their own, there is no parameter for somebody else's, and a guest is refused, which is also why a guest cannot become a member of a private room. The call is mutating and is not safe to repeat: id names the pair inside the caller's set and an id that is already stored is answered with 409, while a request that omits or blanks either half is rejected as invalid and stores nothing. A successful call answers 201 with every key the caller now holds. To change the material of an existing pair use PUT api/2.0/privacyroom/keys.

Parameters

Name	In	Type	Description	Notes
EncryptionKeyRequestDto	body	EncryptionKeyRequestDto		[optional]

Responses

Status code	Description	Type	Response headers
201	The encryption key is created. Answered 200 before DocSpace 4.0; the response body is unchanged	EncryptionKeyArrayWrapper	-
400	The key material is missing, blank or too large to be stored	-	-
409	A key with the same identifier already exists	-	-
401	Unauthorized	ErrorApiResponse	-
429	Too Many Requests.	ErrorApiResponse	`Retry-After`
500	Internal Server Error.	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