Paper Documents Get Create, Update, and Append APIs

Dropbox Paper files have been represented as .paper documents in the filesystem since September 2019, which allowed developers to list, move, and export them through the existing /files endpoints. Today, that coverage expands: new APIs let you create, update, and append content to Paper documents directly, using Markdown, HTML, or plain text.

Creating Paper Documents

The create operation follows the same conventions as uploading binary files. You specify the destination path and input format in the Dropbox-API-Arg header, with the document content (as text, Markdown, or HTML) in the request 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 returns a URL that can be shared with end users for editing. Permissions on that link can be managed through the sharing APIs. The response also includes a result_path and file_id, which work with other file operations such as /files/move and /files/delete.

If a file already exists at the target path, the create call appends a number to the path to avoid 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 and Appending Content

The /files/paper/update endpoint works similarly: pass the path, input format, and binary content. It also supports a doc_update_policy parameter with four modes:

  • append — add content to the end of an existing document
  • prepend — add content to the beginning
  • overwrite — replace the entire document
  • update — overwrite, but only if no changes have been missed

Paper supports real-time co-editing, so each change to a document increments its paper_revision. When using update mode, you can pass the paper_revision you last saw; if the document has changed by the time the request reaches Dropbox servers, the call returns an error. This prevents programmatic updates from silently clobbering user edits. The other update modes do not require a paper_revision.

Note that paper_revision is distinct from the standard file revision. Paper batches the rapid, live revisions into a single file revision./files/export returns the current paper_revision.

Availability and Rollout

These new Paper APIs are in preview and available to all developers. Not every user currently has access to Paper documents in the filesystem, so you may need to check per-user availability via /users/features/get_values before relying on these endpoints. The Paper Migration Guide has more details on the rollout.