# Dropbox

Dropbox is a cloud storage and file hosting service. The Sling Dropbox connector extracts data from the Dropbox API v2, supporting files and folders listing, shared links, shared folders, received files, file requests, and account information.

{% hint style="success" %}
**CLI Pro Required**: APIs require a [CLI Pro token](https://docs.slingdata.io/sling-cli/cli-pro) or [Platform Plan](https://docs.slingdata.io/sling-platform/platform).
{% endhint %}

## Setup

The following credentials and inputs are accepted:

**Secrets:**

* `client_id` **(required)** -> Your Dropbox app key
* `client_secret` **(required)** -> Your Dropbox app secret
* `refresh_token` **(required)** -> A long-lived OAuth2 refresh token

### Getting Your Credentials

1. Go to the [Dropbox App Console](https://www.dropbox.com/developers/apps)
2. Click **Create app**
3. Choose **Scoped access** and **Full Dropbox** access type
4. Name your app and click **Create app**
5. Under the **Permissions** tab, enable these scopes:
   * `account_info.read`
   * `files.metadata.read`
   * `sharing.read`
   * `file_requests.read`
6. Click **Submit** to save permissions
7. Under the **Settings** tab, note the **App key** (`client_id`) and **App secret** (`client_secret`)
8. Generate a refresh token using the OAuth2 authorization flow:

```bash
# Step 1: Open this URL in your browser and authorize the app
# Replace <APP_KEY> with your App key
https://www.dropbox.com/oauth2/authorize?client_id=<APP_KEY>&response_type=code&token_access_type=offline

# Step 2: Exchange the authorization code for a refresh token
curl -X POST https://api.dropboxapi.com/oauth2/token \
  -d code=<AUTH_CODE> \
  -d grant_type=authorization_code \
  -d client_id=<APP_KEY> \
  -d client_secret=<APP_SECRET>
```

The response will contain a `refresh_token` — save this value for your connection configuration.

### Using `sling conns`

{% code overflow="wrap" %}

```bash
sling conns set DROPBOX type=api spec=dropbox secrets='{ client_id: your_app_key, client_secret: your_app_secret, refresh_token: your_refresh_token }'
```

{% endcode %}

### Environment Variable

See [here](https://docs.slingdata.io/sling-cli/environment#dot-env-file-.env.sling) to learn more about the `.env.sling` file.

{% code overflow="wrap" %}

```bash
export DROPBOX='{ type: api, spec: dropbox, secrets: { client_id: "your_app_key", client_secret: "your_app_secret", refresh_token: "your_refresh_token" } }'
```

{% endcode %}

### Sling Env File YAML

See [here](https://docs.slingdata.io/sling-cli/environment#sling-env-file-env.yaml) to learn more about the sling `env.yaml` file.

```yaml
connections:
  DROPBOX:
    type: api
    spec: dropbox
    secrets:
      client_id: "your_app_key"
      client_secret: "your_app_secret"
      refresh_token: "your_refresh_token"
```

## Replication

Here's an example replication configuration to sync Dropbox data to a PostgreSQL database:

```yaml
source: DROPBOX
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: dropbox.{stream_name}

streams:
  current_account:
  files:
  shared_links:
  shared_folders:
  received_files:
  file_requests:
```

**Sync all endpoints:**

```yaml
source: DROPBOX
target: MY_POSTGRES

defaults:
  mode: full-refresh
  object: dropbox.{stream_name}

streams:
  '*':
```

## Endpoints

### Account

| Endpoint          | Description                      | Incremental |
| ----------------- | -------------------------------- | ----------- |
| `current_account` | Current user account information | No          |

### Files & Folders

| Endpoint | Description                       | Incremental |
| -------- | --------------------------------- | ----------- |
| `files`  | All files and folders (recursive) | No          |

### Sharing

| Endpoint         | Description                           | Incremental |
| ---------------- | ------------------------------------- | ----------- |
| `shared_links`   | All shared links                      | No          |
| `shared_folders` | Shared folders the user has access to | No          |
| `received_files` | Files shared with the current user    | No          |

### File Requests

| Endpoint        | Description                       | Incremental |
| --------------- | --------------------------------- | ----------- |
| `file_requests` | File requests created by the user | No          |

To discover available endpoints:

```bash
sling conns discover DROPBOX
```

## Rate Limiting

The Dropbox API enforces rate limits on a per-app and per-user basis. The connector automatically:

* Limits to 5 requests/second (conservative)
* Retries with exponential backoff on 429 (rate limit) responses
* Retries on 5xx server errors with exponential backoff

## Notes

* All Dropbox API v2 endpoints use POST requests internally, even for read operations. The connector handles this automatically.
* The `files` endpoint lists all files and folders recursively from the root of the Dropbox account, including mounted folders.
* The `shared_folders` and `received_files` endpoints may return empty results if the account has no shared content.

If you are facing issues connecting, please reach out to us at <support@slingdata.io>, on [discord](https://discord.gg/q5xtaSNDvp) or open a Github Issue [here](https://github.com/slingdata-io/sling-cli/issues).


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.slingdata.io/connections/api-connections/dropbox.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.