PutRelativeFile

POST /wopi/files/(file_id)

Creates a new file on the host based on the current file.

This operation works as follows:

  1. The WOPI host checks if a file is currently locked or not.
  2. If the file is currently locked and the X-WOPI-Lock value does not match the lock currently on the file, the host must return 409 Conflict (“lock mismatch”) and include the X-WOPI-Lock response header containing the value of the current lock on the file. In the case where the file is unlocked, the host must set X-WOPI-Lock to the empty string.
  3. If the file is unlocked, the host takes the file name from the X-WOPI-SuggestedTarget header and modifies it in order to make the request succeed:
    • If the header contains only a file extension (starts with a period), then the resulting file name will consist of this extension and the initial file name without extension.
    • If the header contains a full file name, then it will be a name for the resulting file.
  4. Finally, the host creates a new file that has a legal name and does not overwrite any existing files, while preserving the file extension.

Parameters

NameDescriptionType
file_idThe file ID that must be URL safe.string

Query parameters

NameDescriptionType
access_tokenAn access token that the host will use to determine whether the request is authorized.string

Request headers

NameDescriptionTypePresence
X-WOPI-OverrideThe requested operation from the WOPI server (PUT_RELATIVE).stringrequired
X-WOPI-SuggestedTargetA file extension or a full file name, including the file extension in the format of the UTF-7 encoded string.stringrequired
X-WOPI-SizeThe size of the file in bytes.integeroptional
X-WOPI-FileConversionIndicates that the request is being made in the context of binary document conversion.booleanoptional

Request body

The request body must contain the full file contents in the binary format.

Response headers

NameDescriptionTypePresence
X-WOPI-LockThe lock ID identifying the current lock on the file. This header must always be included when responding to the request with 409 Conflict. It should not be included when responding to the request with 200 OK.stringoptional
X-WOPI-LockFailureReasonThe cause of the lock failure. This header may be included when responding to the request with 409 Conflict. It must only be used for logging purposes.stringoptional

Response body

NameDescriptionTypePresence
NameThe file name, including extension, without a path.stringrequired
UrlURI of the form http://server/<...>/wopi/files/(file_id)?access_token=(access token), of the newly created file on the host.stringrequired
HostViewUrlURI to a host page that loads the view WOPI action for the newly created file.stringoptional
HostEditUrlURI to a host page that loads edit action for the newly created file.stringoptional