Dropbox API
Dropbox is a file hosting service operated by the American company Dropbox, Inc., headquartered in San Francisco, California, U.S. that offers cloud storage, file synchronization, personal cloud, and client software.
OpenAPI Specification
openapi: 3.0.0
info:
title: Dropbox API Reference
description: >+
The powerful, yet simple, Dropbox API allows you to manage and control
content and team settings programmatically and extend Dropbox capabilities
in new and powerful ways. This is a collection that includes requests to all
endpoints in the Dropbox API.
The Dropbox API is divided in two groups of endpoints: User Endpoints and
Business Endpoints. Operations that would most likely be executed by a user,
such as file operations, are in the User Endpoints folder. Operations that
would most likely be executed by a team administrator, such as adding users
to groups, live in the Business Endpoints folder.
If you are new to Dropbox Business and Team Administration, please have a
look at the [Dropobox Admin
Guide](https://help.dropbox.com/guide/admin/how-to-get-started#dropbox-admin-guide).
If you want more information on how to use our API please refer to our
[Developer Portal](https://www.dropbox.com/developers).
# What's in the collection?
The endpoints are organized in the following folders:
* account
* auth
* check
* contacts
* file_properties
* file_requests
* files
* sharing
* team
* team_log
* users
# Authorization
## OAuth 2.0 for API Access
Dropbox uses OAuth 2.0, an open specification, to authorize access to data.
To get an OAuth token from Dropbox to enable Postman to access your Dropbox
account via the API you’ll need to create a new app on the DBX Platform.
## Creating an App on the DBX Platform
Navigate to https://www.dropbox.com/developers/apps and select “Create app”
1. Choose an API
2. Choose the type of access you need
3. Give your app a name
4. Choose the Dropbox account that will own your app
For reference, please use the [Dropbox OAuth
guide](https://www.dropbox.com/lp/developers/reference/oauth-guide)
## Generating an Access Token
Once you select “Create app” a page will load that displays information
about your newly created app. To generate an access token scroll down to
“OAuth 2” and click “Generate” beneath “Generated access token.” The token
will display as a long string of characters. Copy this token for use with
the Postman Collection.
## Adding an Access Token to the requests
In the Postman client, click on the three dots to the right of the
collection name to "View more actions."
Then, click "Edit."
Click on the "Variables" tab and, in the row for the `access_token`
variable, paste your access token in the `CURRENT VALUE` column. The default
value is `your-access-token-here`.
For information on sessions and variables in Postman see the blog post at
https://blog.postman.com/sessions-faq/.
# Notes
* Dropbox also has a Postman Collection in the API Network to help
administrators with team management workflows. It is called [Dropbox Team
Admin Workflows]().
version: 1.0.0
servers:
- url: https://api.dropbox.com
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
security:
- bearerAuth: []
tags:
- name: Account
- name: Auth
- name: Check
- name: Contacts
- name: File_properties
description: >
This namespace contains helpers for property and template metadata
endpoints.
These endpoints enable you to tag arbitrary key/value data to Dropbox
files.
The most basic unit in this namespace is the :type:`PropertyField`. These
fields encapsulate the actual key/value data.
Fields are added to a Dropbox file using a :type:`PropertyGroup`. Property
groups contain a reference to a Dropbox file and a
:type:`PropertyGroupTemplate`. Property groups are uniquely identified by
the combination of their associated Dropbox file and template.
The :type:`PropertyGroupTemplate` is a way of restricting the possible key
names and value types of the data within a property group. The possible
key names and value types are explicitly enumerated using
:type:`PropertyFieldTemplate` objects.
You can think of a property group template as a class definition for a
particular key/value metadata object, and the property groups themselves
as the instantiations of these objects.
Templates are owned either by a user/app pair or team/app pair. Templates
and their associated properties can't be accessed by any app other than
the app that created them, and even then, only when the app is linked with
the owner of the template (either a user or team).
User-owned templates are accessed via the user-auth
file_properties/templates/*_for_user endpoints, while team-owned templates
are accessed via the team-auth file_properties/templates/*_for_team
endpoints. Properties associated with either type of template can be
accessed via the user-auth properties/* endpoints.
Finally, properties can be accessed from a number of endpoints that return
metadata, including `files/get_metadata`, and `files/list_folder`.
Properties can also be added during upload, using `files/upload`.
- name: File_requests
description: >
This namespace contains endpoints and data types for file request
operations.
- name: Files
description: >
This namespace contains endpoints and data types for basic file
operations.
- name: Sharing
description: >
This namespace contains endpoints and data types for creating and managing
shared links and shared folders.
- name: Team
- name: Team > Devices
- name: Team > Groups
- name: Team > Legal_holds
- name: Team > Linked_apps
- name: Team > Member_space_limits
- name: Team > Members
- name: Team > Namespaces
- name: Team > Reports
- name: Team > Team_folder
- name: Team_log
- name: Users
description: |
This namespace contains endpoints and data types for user management.
paths:
/2/account/set_profile_photo:
post:
tags:
- Account
summary: Dropbox set_profile_photo
description: >-
[set_profile_photo](https://www.dropbox.com/developers/documentation/http/documentation#account-set_profile_photo)
scope: `account_info.write`
Sets a user's profile photo.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"photo\": {\n \".tag\": \"base64_data\",
\n \"base64_data\":
\"SW1hZ2UgZGF0YSBpbiBiYXNlNjQtZW5jb2RlZCBieXRlcy4gTm90IGEgdmFsaWQgZXhhbXBsZS4=\"\n }\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
profile_photo_url: >-
https://dl-web.dropbox.com/account_photo/get/dbaphid%3AAAHWGmIXV3sUuOmBfTz0wPsiqHUpBWvv3ZA?vers=1556069330102&size=128x128
/2/auth/token/from_oauth1:
post:
tags:
- Auth
summary: Dropbox token/from_oauth1
description: >-
[token/from_oauth1](https://www.dropbox.com/developers/documentation/http/documentation#auth-token-from_oauth1)
scope: `None`
Creates an OAuth 2.0 access token from the supplied OAuth 1.0 access
token.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"oauth1_token\": \"qievr8hamyg6ndck\", \n \"oauth1_token_secret\": \"qomoftv0472git7\"\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
oauth2_token: >-
9mCrkS7BIdAAAAAAAAAAHHS0TsSnpYvKQVtKdBnN5IuzhYOGblSgTcHgBFKFMmFn
/2/auth/token/revoke:
post:
tags:
- Auth
summary: Dropbox token/revoke
description: >-
[token/revoke](https://www.dropbox.com/developers/documentation/http/documentation#auth-token-revoke)
scope: `None`
Disables the access token used to authenticate the call.
responses:
'200':
description: Successful response
content:
application/json: {}
/2/check/app:
post:
tags:
- Check
summary: Dropbox app
description: >-
[app](https://www.dropbox.com/developers/documentation/http/documentation#check-app)
scope: `None`
This endpoint performs App Authentication, validating the supplied app
key and secret, and returns the supplied string, to allow you to test
your code and connection to the Dropbox API. It has no other effect. If
you receive an HTTP 200 response with the supplied query, it indicates
at least part of the Dropbox API infrastructure is working and that the
app key and secret valid.
requestBody:
content:
'*/*':
schema:
type: string
example: '"{\n \"query\": \"foo\"\n}"'
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
result: foo
/2/check/user:
post:
tags:
- Check
summary: Dropbox user
description: >-
[user](https://www.dropbox.com/developers/documentation/http/documentation#check-user)
scope: `None`
This endpoint performs User Authentication, validating the supplied
access token, and returns the supplied string, to allow you to test your
code and connection to the Dropbox API. It has no other effect. If you
receive an HTTP 200 response with the supplied query, it indicates at
least part of the Dropbox API infrastructure is working and that the
access token is valid.
requestBody:
content:
'*/*':
schema:
type: string
example: '"{\n \"query\": \"foo\"\n}"'
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
result: foo
/2/contacts/delete_manual_contacts:
post:
tags:
- Contacts
summary: Dropbox delete_manual_contacts
description: >-
[delete_manual_contacts](https://www.dropbox.com/developers/documentation/http/documentation#contacts-delete_manual_contacts)
scope: `contacts.write`
Removes all manually added contacts. You'll still keep contacts who are
on your team or who you imported. New contacts will be added when you
share.
responses:
'200':
description: Successful response
content:
application/json: {}
/2/contacts/delete_manual_contacts_batch:
post:
tags:
- Contacts
summary: Dropbox delete_manual_contacts_batch
description: >-
[delete_manual_contacts_batch](https://www.dropbox.com/developers/documentation/http/documentation#contacts-delete_manual_contacts_batch)
scope: `contacts.write`
Removes manually added contacts from the given list.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"email_addresses\": [\n \"[email protected]\", \n \"[email protected]\"\n ]\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: Successful response
content:
application/json: {}
/2/file_properties/properties/add:
post:
tags:
- File_properties
summary: Dropbox properties/add
description: >-
[properties/add](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-properties-add)
scope: `files.metadata.write`
Add property groups to a Dropbox file. See `templates/add_for_user` or
`templates/add_for_team` to create new templates.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"path\": \"/my_awesome/word.docx\", \n \"property_groups\": [\n {\n \"template_id\":
\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\", \n \"fields\":
[\n {\n \"name\": \"Security
Policy\", \n \"value\":
\"Confidential\"\n }\n ]\n }\n ]\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: Successful response
content:
application/json: {}
/2/file_properties/properties/overwrite:
post:
tags:
- File_properties
summary: Dropbox properties/overwrite
description: >-
[properties/overwrite](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-properties-overwrite)
scope: `files.metadata.write`
Overwrite property groups associated with a file. This endpoint should
be used instead of `properties/update` when property groups are being
updated via a "snapshot" instead of via a "delta". In other words, this
endpoint will delete all omitted fields from a property group, whereas
`properties/update` will only delete fields that are explicitly marked
for deletion.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"path\": \"/my_awesome/word.docx\", \n \"property_groups\": [\n {\n \"template_id\":
\"ptid:1a5n2i6d3OYEAAAAAAAAAYa\", \n \"fields\":
[\n {\n \"name\": \"Security
Policy\", \n \"value\":
\"Confidential\"\n }\n ]\n }\n ]\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: Successful response
content:
application/json: {}
/2/file_properties/properties/remove:
post:
tags:
- File_properties
summary: Dropbox properties/remove
description: >-
[properties/remove](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-properties-remove)
scope: `files.metadata.write`
Permanently removes the specified property group from the file. To
remove specific property field key value pairs, see `properties/update`.
To update a template, see `templates/update_for_user` or
`templates/update_for_team`. To remove a template, see
`templates/remove_for_user` or `templates/remove_for_team`.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"path\": \"/my_awesome/word.docx\", \n \"property_template_ids\": [\n \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"\n ]\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: Successful response
content:
application/json: {}
/2/file_properties/properties/search:
post:
tags:
- File_properties
summary: Dropbox properties/search
description: >-
[properties/search](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-properties-search)
scope: `files.metadata.read`
Search across property templates for particular property field values.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"queries\": [\n {\n \"query\":
\"Compliance Bot - Beta\", \n \"mode\":
{\n \".tag\": \"field_name\", \n \"field_name\": \"Security\"\n }, \n \"logical_operator\": \"or_operator\"\n }\n ], \n \"template_filter\": \"filter_none\"\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
- name: Authorization
in: header
schema:
type: string
example: 'Bearer YOUR_ACCESS_TOKEN'
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
matches:
- id: id:a4ayc_80_OEAAAAAAAAAXz
path: /my_awesome/word.docx
is_deleted: false
property_groups:
- template_id: ptid:1a5n2i6d3OYEAAAAAAAAAYa
fields:
- name: Security Policy
value: Confidential
/2/file_properties/properties/search/continue:
post:
tags:
- File_properties
summary: Dropbox properties/search/continue
description: >-
[properties/search/continue](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-properties-search-continue)
scope: `files.metadata.read`
Once a cursor has been retrieved from `properties/search`, use this to
paginate through all search results.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"cursor\":
\"ZtkX9_EHj3x7PMkVuFIhwKYXEpwpLwyxp9vMKomUhllil9q7eWiAu\"\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
matches:
- id: id:a4ayc_80_OEAAAAAAAAAXz
path: /my_awesome/word.docx
is_deleted: false
property_groups:
- template_id: ptid:1a5n2i6d3OYEAAAAAAAAAYa
fields:
- name: Security Policy
value: Confidential
/2/file_properties/properties/update:
post:
tags:
- File_properties
summary: Dropbox properties/update
description: >-
[properties/update](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-properties-update)
scope: `files.metadata.write`
Add, update or remove properties associated with the supplied file and
templates. This endpoint should be used instead of
`properties/overwrite` when property groups are being updated via a
"delta" instead of via a "snapshot" . In other words, this endpoint will
not delete any omitted fields from a property group, whereas
`properties/overwrite` will delete any fields that are omitted from a
property group.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"path\": \"/my_awesome/word.docx\", \n \"update_property_groups\": [\n {\n \"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\", \n \"add_or_update_fields\": [\n {\n \"name\": \"Security Policy\",
\n \"value\":
\"Confidential\"\n }\n ],
\n \"remove_fields\": []\n }\n ]\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: Successful response
content:
application/json: {}
/2/file_properties/templates/add_for_team:
post:
tags:
- File_properties
summary: Dropbox templates/add_for_team
description: >-
[templates/add_for_team](https://www.dropbox.com/developers/documentation/http/teams#file_properties-templates-add_for_team)
scope: `files.team_metadata.write`
Add a template associated with a team. See `properties/add` to add
properties to a file or folder.
Note: this endpoint will create team-owned templates.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"name\": \"Security\", \n \"description\": \"These
properties describe how confidential this file or folder is.\",
\n \"fields\": [\n {\n \"name\": \"Security
Policy\", \n \"description\": \"This is the security
policy of the file or folder described.\\nPolicies can be
Confidential, Public or Internal.\", \n \"type\":
\"string\"\n }\n ]\n}"
security:
- bearerAuth: []
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
template_id: ptid:1a5n2i6d3OYEAAAAAAAAAYa
/2/file_properties/templates/add_for_user:
post:
tags:
- File_properties
summary: Dropbox templates/add_for_user
description: >-
[templates/add_for_user](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-templates-add_for_user)
scope: `files.metadata.write`
Add a template associated with a user. See `properties/add` to add
properties to a file. This endpoint can't be called on a team member or
admin's behalf.
requestBody:
content:
'*/*':
schema:
type: string
example: >-
"{\n \"name\": \"Security\", \n \"description\": \"These
properties describe how confidential this file or folder is.\",
\n \"fields\": [\n {\n \"name\": \"Security
Policy\", \n \"description\": \"This is the security
policy of the file or folder described.\\nPolicies can be
Confidential, Public or Internal.\", \n \"type\":
\"string\"\n }\n ]\n}"
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
template_id: ptid:1a5n2i6d3OYEAAAAAAAAAYa
/2/file_properties/templates/get_for_team:
post:
tags:
- File_properties
summary: Dropbox templates/get_for_team
description: >-
[templates/get_for_team](https://www.dropbox.com/developers/documentation/http/teams#file_properties-templates-get_for_team)
scope: `files.team_metadata.write`
Get the schema for a specified template.
requestBody:
content:
'*/*':
schema:
type: string
example: '"{\n \"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"\n}"'
security:
- bearerAuth: []
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
name: Security
description: >-
These properties describe how confidential this file or folder
is.
fields:
- name: Security Policy
description: >-
This is the security policy of the file or folder
described.
Policies can be Confidential, Public or Internal.
type:
.tag: string
/2/file_properties/templates/get_for_user:
post:
tags:
- File_properties
summary: Dropbox templates/get_for_user
description: >-
[templates/get_for_user](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-templates-get_for_user)
scope: `files.metadata.read`
Get the schema for a specified template. This endpoint can't be called
on a team member or admin's behalf.
requestBody:
content:
'*/*':
schema:
type: string
example: '"{\n \"template_id\": \"ptid:1a5n2i6d3OYEAAAAAAAAAYa\"\n}"'
parameters:
- name: Content-Type
in: header
schema:
type: string
example: application/json
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
name: Security
description: >-
These properties describe how confidential this file or folder
is.
fields:
- name: Security Policy
description: >-
This is the security policy of the file or folder
described.
Policies can be Confidential, Public or Internal.
type:
.tag: string
/2/file_properties/templates/list_for_team:
post:
tags:
- File_properties
summary: Dropbox templates/list_for_team
description: >-
[templates/list_for_team](https://www.dropbox.com/developers/documentation/http/teams#file_properties-templates-list_for_team)
scope: `files.team_metadata.write`
Get the template identifiers for a team. To get the schema of each
template use `templates/get_for_team`.
security:
- bearerAuth: []
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
template_ids:
- ptid:1a5n2i6d3OYEAAAAAAAAAYa
/2/file_properties/templates/list_for_user:
post:
tags:
- File_properties
summary: Dropbox templates/list_for_user
description: >-
[templates/list_for_user](https://www.dropbox.com/developers/documentation/http/documentation#file_properties-templates-list_for_user)
scope: `files.metadata.read`
Get the template identifiers for a team. To get the schema of each
template use `templates/get_for_user`. This endpoint can't be called on
a team member or admin's behalf.
responses:
'200':
description: OK
headers:
X-Dropbox-Request-Id:
schema:
type: integer
example: '1234'
Content-Type:
schema:
type: string
example: application/json
content:
application/json:
schema:
type: object
example:
template_ids:
- pti
# --- truncated at 32 KB (380 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/dropbox/refs/heads/main/openapi/dropbox-openapi-original.yml