New Paper Endpoints Released in Preview

In September 2019, we began to represent Dropbox Paper files as .paper documents in the filesystem. This enabled listing, moving, and exporting paper docs with /files endpoints.

Today, we’ve added new endpoints for Paper—now you can create, update, and even append to paper documents in the filesystem! Paper docs can be added using Markdown, HTML, or plain text.

New and Updated APIs

The following APIs have been added or modified:

/files/paper/create - Use this new endpoint to create new Paper docs
/files/paper/update - Use this new endpoint to overwrite or append Paper docs
/files/export - Use this endpoint to get metadata and a Markdown, HTML, or plain text representation of a Paper doc. This endpoint has been updated to support new Paper export formats and metadata.

Creating a Paper Doc

Creating a paper doc is easy—conventions are similar to uploading binary files. Simply specify your target path and input format with the Dropbox-API-Arg header with your text, Markdown, or HTML as the body.

curl -v -X POST https://api.dropboxapi.com/2/files/paper/create     
--header "Authorization: Bearer YOUR_BEARER_TOKEN"     
--header "Dropbox-API-Arg: {\"path\": \"/Meeting Notes.paper\",\"import_format\": \"plain_text\"}"     
--header "Content-Type: application/octet-stream"      
--data-binary @meeting_notes.txt

The /files/paper /create call will return the URL, which is presentable to end users to visit and begin editing (Note: permissions on the link can be managed through sharing APIs). The call will also return the result_path and file_id, which can be used with other file operators (like /files/move and /files/delete).

Note that if a file already exists at your target destination, create will append a number to the end of the path to prevent a collision.

{
    "url": "https://www.dropbox.com/cloud_docs/view/k93hadJEO3-sRkejKYJi4?fileid_gid=0uVLNNU2EdAAAAAAAABTcw",
    "result_path": "/Meeting Notes (1).paper",
    "file_id": "id:0uVLZNU2SdAAAAAAAAATcw",
    "paper_revision": 2
}

Updating a Paper Doc

Updating a paper document with /files/paper/update is similar. Pass the path, input format, and binary content.

Update also enables you to specify the doc_update_policy. The append and prepend modes allow you to add content to an existing doc. The overwrite mode will overwrite the entire document, and the update mode overwrites after checking that there are no updates the caller has missed.

Dropbox Paper enables live, real-time co-editing. The paper_revision increments for every change to the document. The paper_revision can be passed when using the update mode, which will then error if paper_revision has changed by the time the call reaches Dropbox servers. This provides a mechanism to make sure your programmatic updates do not conflict with any edits made by users. Other update modes to not require the paper_revision.

Note that paper_revision and file revision are different, but related: paper_revision tracks rapid, live updates — which Paper will then batch together to make a file revision. Use /files/export to retrieve the latest paper_revision.

Building with Paper

These new APIs are in preview, available to all developers.

Note that at the time of writing, not all users have access to paper docs in the filesystem—you may need to issue an API call to /users/features/get_values to check for availability on a per-user basis. See our Paper Migration Guide for more information.

As always, we’re available to help! You can post your questions on our developer forum or submit a ticket for more direct support.

Build with Dropbox today at www.dropbox.com/developers.

// Tags

// Copy link

Link copied