# Couchdrop API Overview

Couchdrop has a comprehensive API that covers everything in the platform. The API is stable and we endeavour to maintain backwards compatibility.

#### **Data types**

Interacting with the API is via a HTTPS endpoint. Data is submitted and returned either via form data or JSON. Responses are always in JSON and status codes indicate success or failure. 

####

#### Authentication

With the exception of the authenticate and register routes, all API routes require a valid authentication token. This token is passed as a header field. 

Permanent tokens can be created and managed from the Couchdrop administration interface and temporary tokens can be created with the [Authentication](/domains-and-accounts/authentication) route.

#### Getting Help

Our team is always here to help. If you are having trouble with the API, reach out to <support@couchdrop.io> or your account manager.&#x20;

&#x20;


# Available Endpoints

Couchdrop has two separate endpoints for public API access

| Endpoints           | Name                          | Description                                                                                                                                             |
| ------------------- | ----------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| api.couchdrop.io    | Management Endpoint           | This is the main API endpoint, used for most routes documented in this API guide                                                                        |
| fileio.couchdrop.io | Virtual Filesystem Operations | When interacting with files and folders, this endpoint is used. See [Filesystem Operations](/filesystem-operations/managing-files) for available routes |


# Errors and Response Codes

All API methods return a HTTP status code which indicates success or failure.

It is important that you handle different API response codes properly. &#x20;

| Status Code | Description                                                                                                                                                                                          |
| ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 200         | A status code of 200 indicates success. There should normally be a body returned with this status code that includes the data or result set.                                                         |
| 403         | HTTP 403 means you do not have the correct permissions to perform that operation. It is a fatal error and should not be retried.                                                                     |
| 429         | HTTP 429 means you have exceeded our rate limiting protection mechanisms. In this case, we recommend implementing a exponential backof mechanism and retrying the request in a short period of time. |
| 422         | HTTP 422 is a response returned on error by the fileio service. In this case, there is an upstream error from the cloud storage provider and the error details can be found in the response.         |
| 503         | HTTP 503 normally indicates a capacity issue on our end. Treat this the same as a 429 and implement an exponential back-of mechanism.                                                                |
| 500         | HTTP 500 indicates and unexpected error. Check the body for more details and implement a short retry/exponential backoff mechanism.                                                                  |

&#x20;


# Manage domain/account

General settings allow you to manage your account with Couchdrop. Its also the perfect place to start with API access.

## Get Account

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/account`

This endpoint allows you to view details about your Couchdrop Domain/Org.

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Account details retrieved successfully" %}

```javascript
{
  "account": {
    "api_token": "token", 
    "email_address": "michael@couchdrop.io",
    "subscription_type": "couchdrop_new_enterprise", 
    "username": "mshindo"
  }
}
```

{% endtab %}

{% tab title="403 The token you provided was invalid, or you are not allowed access to this route" %}

```
{
  "err": "Token was not valid"
}
```

{% endtab %}
{% endtabs %}


# Authentication

To authenticate with Couchdrop see the routes below

Authenticating with Couchdrops API requires a username and password and on success returns a new authentication token. This token can then we be used in subsequent API requests. Tokens generated using this route only exist for a short period of time and should not be used for long term API access.&#x20;

For long term access, create and administrative token in Couchdrop's administration interface.&#x20;

API tokens inherit the permissions of the authenticating user.&#x20;

## Authenticate with username and password

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/authenticate`

Authenticate with a POST request

#### Request Body

| Name                                       | Type   | Description                             |
| ------------------------------------------ | ------ | --------------------------------------- |
| username<mark style="color:red;">\*</mark> | String | Username                                |
| password<mark style="color:red;">\*</mark> | String | Password                                |
| system                                     | String | An optional field describing the source |

{% tabs %}
{% tab title="200: OK Authentication succeeded" %}

```javascript
{
    "token":"<API auth token>"
}
```

{% endtab %}

{% tab title="403: Forbidden Access Denied" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="401: Unauthorized 2FA required" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Users

With Couchdrop you can configure additional users. Additional users cannot manage your Couchdrop service, but are able to upload/download and view files.

## Get Users

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/credentials`

This endpoint allows you to get configured users/credentials

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Credentials successfully retrieved." %}

```javascript
{
  "credentials": [
    {
      "id": "905abg1a-f206-11e8-b591-0242bc140002", 
      "permissions_mode": "r", 
      "permissions_path": "/box/michael", 
      "public_key": null, 
      "username": "michael"
    }
  ]
}
```

{% endtab %}
{% endtabs %}

## Create or Modify a User

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/credentials`

This method is used to modify a user. Either the username or id can be supplied. If you wish to change the username, then the id must be specified.&#x20;

#### Headers

| Name                                    | Type   | Description      |
| --------------------------------------- | ------ | ---------------- |
| token<mark style="color:red;">\*</mark> | string | API Access Token |

#### Request Body

| Name                                       | Type    | Description                                  |
| ------------------------------------------ | ------- | -------------------------------------------- |
| id                                         | string  | User identifier, generated by system         |
| username<mark style="color:red;">\*</mark> | string  | Username for user                            |
| password                                   | string  | Password for user                            |
| email\_address                             | string  | Email address for user                       |
| public\_key                                | string  | RSA public key                               |
| permissions\_path                          | string  | Root/home directory                          |
| permissions\_mode                          | string  | Permissions, ie: 'rw'                        |
| permissions\_delete\_allowed               | boolean | Allow user to delete files/folders           |
| allowed\_ips                               | string  | IP address to allow. ie: 8.8.8.8, 1.2.3.4/24 |
| allow\_sftp\_scp\_rsync                    | boolean | Allow access via SFTP/SCP/RSYNC              |
| allow\_ftp                                 | boolean | Allow access via traditional FTP             |
| allow\_upload\_portal                      | boolean | Allow upload via drop.couchdrop.io           |
| allow\_admin                               | boolean | Allow admin access to Couchdrop              |
| allow\_webportal                           | boolean | Allow access via Couchdrop web UI            |
| groups                                     | String  | An array of group ips for group memebership  |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}

## Invite a user to Couchdrop

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/users/invite`

This method creates a new user and sends a invitiation email.&#x20;

#### Headers

| Name                                    | Type   | Description     |
| --------------------------------------- | ------ | --------------- |
| token<mark style="color:red;">\*</mark> | String | API Access Toke |

#### Request Body

| Name           | Type   | Description                   |
| -------------- | ------ | ----------------------------- |
| email\_address | String | Email address of the new user |

## Trigger a password reset email

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/users/<username>/resetpassword`

Trigger and send a password reset email to a user

#### Headers

| Name                                    | Type   | Description            |
| --------------------------------------- | ------ | ---------------------- |
| token<mark style="color:red;">\*</mark> | String | API authentication key |

## Delete A User

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/credentials/<username>/delete`

#### Path Parameters

| Name     | Type   | Description        |
| -------- | ------ | ------------------ |
| username | string | User to be deleted |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


# Groups

Managing groups can be done via the API. The following routes are available.

## Get all groups

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/groups`

Get all user groups in an organisation

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

{% tabs %}
{% tab title="200: OK " %}

```json
{
    "groups":[
        {
            "id":"group_id", 
            "groupname": "name":,
            "allowed_ips":"192.168.1.1, 10.1.1.1/32",
            "allow_sftp_scp_rsync":false,
            "allow_upload_portal": false,
            "allow_ftp": false,
            "allow_admin": true,
            "allow_webportal": true,
            "allow_ftps": true,
            "allow_inboxes": true,
            "allow_shared_links": false,
            "allow_workflows": false
        }
    ]
}
```

{% endtab %}
{% endtabs %}

## Get an individual group by ID

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/group/<group_id>`

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "group": {
        ...
    }
}
```

{% endtab %}
{% endtabs %}

## Create an group

<mark style="color:orange;">`PUT`</mark> `https://api.couchdrop.io/manage/groups`

Create a new group

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

#### Request Body

| Name      | Type   | Description |
| --------- | ------ | ----------- |
| groupname | String | Group Name  |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "group_id":"new_group_id"
}
```

{% endtab %}
{% endtabs %}

## Update an existing group

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/groups`

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

#### Request Body

| Name                                 | Type   | Description                       |
| ------------------------------------ | ------ | --------------------------------- |
| id<mark style="color:red;">\*</mark> | String | Group ID                          |
| groupname                            | String | Group name                        |
| allowed\_ips                         | String | Allowed IP addresses              |
| allow\_sftp\_scp\_rsync              | String | Allow SFTP based access           |
| allow\_upload\_portal                | String | Allow access to the upload portal |
| allow\_ftp                           | String | Allow FTP based access            |
| allow\_admin                         | String | Allow admin access                |
| allow\_webportal                     | String | Allow access to the web portal    |
| allow\_inboxes                       | String | Allow access to inboxs            |
| allow\_shared\_links                 | String | Allow access to shared links      |
| allow\_workflows                     | String | Allow access to workflows         |

## Delete a group by ID

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/groups/<group_id>`

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

## Get all group members

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/groups/<group_id>/users`

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "users": []
}
```

{% endtab %}
{% endtabs %}


# Folder Permissions

After enabling Advanced Permissions, you can configure a folder with granular access to individual users.

## Advanced Folder Permissions

## Get folder permissions

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/fileprops/permissions`

Get permissions for a specific folder.

#### Query Parameters

| Name | Type   | Description                       |
| ---- | ------ | --------------------------------- |
| path | string | Folder to get permission details. |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{"result": [{"username": "user-38f92ce5", 
    "account": "michael", 
    "lstat": true, 
    "upload": false, 
    "ls": true, 
    "download": true, 
    "path": "/test_folder", 
    "id": "38f92ce5-700f-4f4d-8557-df6f5e8d9b80 "}]}
```

{% endtab %}

{% tab title="403 Authentication Invalid" %}

```
```

{% endtab %}
{% endtabs %}

## Add/Update folder permissions

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/fileprops/permissions`

Add new or update existing folder properties.

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name     | Type    | Description                          |
| -------- | ------- | ------------------------------------ |
| path     | string  | Folder to grant user permissions on. |
| username | string  | User to grant permissions on.        |
| download | boolean | Grant Download permissions to user.  |
| upload   | boolean | Grant Upload permissions to user.    |
| delete   | boolean | Grant Delete permissions to user.    |
| lstat    | boolean | Grant LSTAT permissions to user.     |
| ls       | boolean | Grant LS permissions to user.        |

{% tabs %}
{% tab title="200 Successfully added permissions for user." %}

```
{}
```

{% endtab %}

{% tab title="403 Authentication Invalid." %}

```
```

{% endtab %}
{% endtabs %}

## Delete folder permissions

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/fileprops/permissions/<permission_id>`

Delete permissions from a specific folder.

#### Path Parameters

| Name           | Type   | Description                        |
| -------------- | ------ | ---------------------------------- |
| permission\_id | string | ID of the permission to be deleted |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Successfully deleted permission." %}

```
{}
```

{% endtab %}

{% tab title="403 Authentication Invalid." %}

```
```

{% endtab %}
{% endtabs %}


# Folder Properties

With Couchdrop you can configure folders with advanced user permissions, webhook and email notifications, as well as web portal uploads.

## Folder Properties

## Get folder properties

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/fileprops`

Get all current folder properties.

#### Query Parameters

| Name | Type   | Description           |
| ---- | ------ | --------------------- |
| path | string | Path to file / folder |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Successfully retrieved folder properties" %}

```
{"result": {"account": "test",
             "advanced_permissions_enabled": False,
             "email_upload_address": "d18ae434-bc66-4c54-b95b-762dbb5e2d28@mail.couchdrop.io",
             "email_upload_enabled": True,
             "id": "12b7c994-bd45-4dd4-b02b-2f13248deba5",
             "notifications__email": "admin@couchdrop.io",
             "notifications__email_download": False,
             "notifications__email_failures": False,
             "notifications__email_upload": False,
             "notifications__webhook_download": False,
             "notifications__webhook_failure": False,
             "notifications__webhook_upload": False,
             "notifications__webhook_uri": "",
             "path": "/mount0",
             "portal_enabled": False,
             "portal_url": "https://upload.couchdrop.io/2d769df4-08a7-4ff3-a166-831229363281"}}
```

{% endtab %}

{% tab title="403 Authentication Invalid." %}

```
{
  "err": "Token was not valid"
}
```

{% endtab %}
{% endtabs %}

## Add/Update folder properties

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/fileprops`

Add new or update existing folder properties.

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name                               | Type    | Description                                                                       |
| ---------------------------------- | ------- | --------------------------------------------------------------------------------- |
| path                               | string  | Folder to apply properties to.                                                    |
| portal\_enabled                    | boolean | Enable web upload portal.                                                         |
| notifications\_\_email             | string  | Address to send email notifications.                                              |
| notifications\_\_email\_upload     | boolean | Send email when files are uploaded.                                               |
| notifications\_\_email\_download   | boolean | Send email when files are downloaded.                                             |
| notifications\_\_email\_failures   | boolean | Send email when operation fails.                                                  |
| notifications\_\_webhook\_upload   | boolean | Send webhook when files are uploaded.                                             |
| notifications\_\_webhook\_download | boolean | Send webhook when files are downloaded.                                           |
| notifications\_\_webhook\_failure  | boolean | Send webhook when operation fails.                                                |
| notifications\_\_webhook\_uri      | string  | URI to send webhooks notifications.                                               |
| advanced\_permissions\_enabled     | boolean | Enable advanced permissions. (Blocks all access to folder by default if enabled.) |

{% tabs %}
{% tab title="200 Successfully updated folder properties." %}

```
{}
```

{% endtab %}

{% tab title="403 Authentication Invalid." %}

```
{
  "err": "Token was not valid"
}
```

{% endtab %}
{% endtabs %}


# Shared Links

Shared Links can be created to provide external users with access to files. Links can be set up securely with a password requirement as well as a time for access via the link to expire.

## Get Shared Links

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/sharedlinks`

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Returns list of shared links " %}

```
{
  "result": [
              {"account": "admin",
                "expiry": 86400,
                "id": "94a4235b-c4ae-4ded-b31a-c7d0e29844b9",
                "password": "P@ssw0rd",
                "path": "/google/folder1"},
              {"account": "admin",
                "expiry": 0,
                "id": "a6f1cd25-bba2-453f-b9cd-d369c6ce5693",
                "password": "",
                "path": "/onedrive/accounts.pdf"}
             ]
 }
```

{% endtab %}
{% endtabs %}

## Add Shared Link

<mark style="color:orange;">`PUT`</mark> `https://api.couchdrop.io/manage/sharedlinks`

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 Returns newly created shared link object" %}

```
{
    "result": {
             "account": "admin",
             "expiry": 0,
             "id": "e2a460ed-af5b-4af4-bcf5-c07accab8dde",
             "password": "",
             "path": "/"
             }
}
```

{% endtab %}
{% endtabs %}

## Update Shared Link

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/sharedlinks`

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name     | Type   | Description                                                   |
| -------- | ------ | ------------------------------------------------------------- |
| id       | string | Shared link identifier, generated by the system               |
| expiry   | string | Expiration time for shared link (epoch time ie: '1606087502') |
| password | string | Password to protect shared link                               |
| path     | string | Path to file / folder that will be shared                     |

{% tabs %}
{% tab title="200 " %}

```
{}
```

{% endtab %}
{% endtabs %}

## Delete Shared Link

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/sharedlinks/<link_id>`

#### Path Parameters

| Name     | Type   | Description                     |
| -------- | ------ | ------------------------------- |
| link\_id | string | ID of shared link to be deleted |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

{% tabs %}
{% tab title="200 " %}

```
{}
```

{% endtab %}
{% endtabs %}


# Storage Connections

Couchdrop connects to external storage engines. Managing storage engines and mappings can be done using the API.

**Note about OAuth**

Some storage provides require OAuth based authentication. Currently this cannot be done using the API.

#### Getting existing storage connections

## Get all storage connections

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/account/storage`

Returns a list of all storage connections configured in Couchdrop

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "storage":[
        {...}
    ]
}
```

{% endtab %}
{% endtabs %}

#### Create or Update a storage connection

## Create/Update Storage

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/account/storage`

This method is used to create and/or update storage settings. For param details, see the sub-artices.&#x20;

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

#### Request Body

| Name                                          | Type   | Description                                                                                                                                     |
| --------------------------------------------- | ------ | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| id                                            | String | ID of existing storage connection to update. If not specified, Couchdrop will create a new storage entity.                                      |
| path<mark style="color:red;">\*</mark>        | String | Path to mount storage as in Couchdrop                                                                                                           |
| store\_type<mark style="color:red;">\*</mark> | String | Store type. See available store types below.                                                                                                    |
| subpath                                       | String | Map this folder/path to Couchdrop. If not specified, we will map the root directory of the storage connection into the folder specified in path |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "result":{
        ...
    }
}
```

{% endtab %}
{% endtabs %}

The store types and their require auth is below. Api authentication can not be provided with OAuth without the assistance of support.&#x20;

| store\_type          | Name/Provider                                                                            | Auth Type             |
| -------------------- | ---------------------------------------------------------------------------------------- | --------------------- |
| azure                | Azure Files - [Azure Connections](/administration/storage-connections/azure-connections) | Static Keys           |
| azureblob            | Azure Blob - [Azure Connections](/administration/storage-connections/azure-connections)  | Static Keys           |
| googledrive          | Individual Google Drive                                                                  | OAuth                 |
| googledrive\_domain  | Google Workspace                                                                         | API Domain Delegation |
| gcloud               | Google GCS - [GCS Connections](/administration/storage-connections/gcs-connections)      | Static Keys           |
| dropboxfull          | Personal Dropbox                                                                         | OAuth                 |
| dropboxfullbusiness  | Team Dropbox                                                                             | OAuth                 |
| digitalocean         | Digital Ocean Spaces                                                                     | Static Keys           |
| wasabi               | Wasabi S3 Storage                                                                        | Static Keys           |
| seagate\_lyve\_cloud | Seagate S3 Storage                                                                       | Static Keys           |
| sftp                 | SFTP - [SFTP Connections](/administration/storage-connections/sftp-connections)          | Username/Password     |
| ftp                  | FTP/s - [FTP Connections](/administration/storage-connections/ftp-connections)           | Username/Password     |
| s3                   | AWS S3 - [S3 Connections](/administration/storage-connections/s3-connections)            | Static Keys           |
| s3\_compatible       | Custom S3 - [S3 Connections](/administration/storage-connections/s3-connections)         | Static Keys           |
| box                  | Box                                                                                      | OAuth                 |
| backblazeb2          | Backblaze B2 Storage                                                                     | Static Key            |
| onedrive             | Microsoft Onedrive                                                                       | OAuth                 |
| sharepoint           | Microsoft Sharepoint                                                                     | OAuth                 |
| filebase             | Filebase                                                                                 | Keys                  |
| egnyte               | Egnyte                                                                                   | OAuth                 |
| idrive               | IDrive S3                                                                                | Keys                  |
| sharefile            | Citrix Sharefile                                                                         | OAuth                 |
| huddle               | Ideagen Huddle                                                                           | OAuth                 |
| hosted               | Couchdrop Hosted Storage                                                                 | --                    |

#### Removing a storage connection

## Remove a storage connection

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/account/storage`

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API Token   |

#### Request Body

| Name                                 | Type   | Description           |
| ------------------------------------ | ------ | --------------------- |
| id<mark style="color:red;">\*</mark> | String | Storage connection ID |


# SFTP Connections

Configuring a connection to an external SFTP can be done with basic connectivity details as outlined below.

#### Connection Params

<table><thead><tr><th width="296.3333333333333">Param Key</th><th>Example Value</th><th>Description</th></tr></thead><tbody><tr><td>endpoint__sftp_hostname</td><td>sftp.google.com</td><td>The hostname or ip address we are connecting to</td></tr><tr><td>endpoint__sftp_port</td><td>22</td><td>Port for the connection</td></tr><tr><td>endpoint__sftp_username</td><td>admin</td><td>The username for the remote connection</td></tr><tr><td>endpoint__sftp_password</td><td>passwordthatissecure</td><td>(Optional) The password for the remote connection</td></tr><tr><td>endpoint__sftp_key</td><td>--- BEGIN RSA KEY ---</td><td>(Optional) A private key in PEM format.</td></tr><tr><td>endpoint__sftp_key_password</td><td>password</td><td>(Optional) The private key password</td></tr></tbody></table>


# S3 Connections

Configuring a connection to S3 or a compatible S3 provider can be done with basic connectivity details as outlined below.

#### Connecting to Amazon S3

The following params are required to connect to Amazon AWS S3.

<table><thead><tr><th width="328.3333333333333">Key</th><th width="185">Example</th><th>Description</th></tr></thead><tbody><tr><td>endpoint__amazon_s3_access_key_id</td><td>AKIAIOSFODNN7</td><td>The IAM access key from the AWS management interface. </td></tr><tr><td>endpoint__amazon_s3_access_secret_key</td><td>AKIAIOSFODNN7AKIAIOSFODNN7AKIAIOSFODNN7</td><td>The corresponding secret for the key provided above.</td></tr><tr><td>endpoint__amazon_s3_bucket</td><td>bucket-1</td><td>The bucket name</td></tr></tbody></table>

####

#### To connect to another S3 provider

Couchdrop will connect to any S3 provider.&#x20;

| Key                                             | Example                                 | Description           |
| ----------------------------------------------- | --------------------------------------- | --------------------- |
| endpoint\_\_s3\_compatible\_endpoint\_url       | <https://bucket1.s3.provider.com>       | The connection URL    |
| endpoint\_\_s3\_compatible\_bucket              | bucket1                                 | The bucket name       |
| endpoint\_\_s3\_compatible\_access\_key\_id     | AKIAIOSFODNN7                           | The access key id     |
| endpoint\_\_s3\_compatible\_access\_secret\_key | AKIAIOSFODNN7AKIAIOSFODNN7AKIAIOSFODNN7 | The access key secret |


# FTP Connections

Configuring a connection to an external FTP can be done with basic connectivity details as outlined below.

| Param                     | Example        | Description                                     |
| ------------------------- | -------------- | ----------------------------------------------- |
| endpoint\_\_ftp\_hostname | ftp.google.com | The hostname or ip address of the remote server |
| endpoint\_\_ftp\_port     | 20             | The port of the remote server                   |
| endpoint\_\_ftp\_username | admin          | The username of the remote user                 |
| endpoint\_\_ftp\_password | password123    | The password of the remote user                 |
| endpoint\_\_ftp\_tls      | true           | Enable or disable TLS                           |


# Azure Connections


# GCS Connections


# Other


# Automations

With Couchdrop you can configure Automations which can be created to perform actions on files and folders automatically. These workflows can be action or schedule based.


# Scheduled Automations


# Create/Update

Create or update a schedule workflow

## Create a schedule workflow

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/workflow/schedules`

&#x20;

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

#### Request Body

| Name                         | Type              | Description                                                                                                                                                                                                                                                                                                                                                                          |
| ---------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
|                              | String            | If id is provided the existing workflow with this id will be updated.                                                                                                                                                                                                                                                                                                                |
| enabled                      | Boolean           | Enable or disable the workflow                                                                                                                                                                                                                                                                                                                                                       |
| name                         | String            | Workflow name in the system                                                                                                                                                                                                                                                                                                                                                          |
| conditions                   | JSON Array String | <p>Conditions that need to be met for this workflow to action upon.</p><p></p><p>E.g.</p><p>\[{ "condition\_type": "and", "filename\_pattern": "\*.bz2", "id": "98fe1b8c-8516-4dbc-be1f-0bdce1cc131b", "negate": false, "type": "filename\_matches" } ]</p>                                                                                                                          |
| actions                      | JSON Aray String  | <p>Action that will run on the files/folders that match the conditions.</p><p></p><p>E.g.</p><p>\[ { "actions": \[ { "email\_address": "<user1@couchdrop.io>", "id": "51856312-fa6c-469e-86da-0a3028611069", "type": "email" } ], "decompress\_to": "/myfolder/decompressed/", "decompress\_type": "bz2", "id": "1ce2e380-a4bc-4d05-a8e5-c47e76461419", "type": "decompress" } ]</p> |
| source\_path                 | String            | <p>Path for which this workflow should run. </p><p>E.g. /myfolder/compressed/</p>                                                                                                                                                                                                                                                                                                    |
| schedule\_config             | JSON String       | <p>Schedule configuration when the workflow should run in JSON format.</p><p>E.g.</p><p>{"interval":"daily","time":"15:14"}</p>                                                                                                                                                                                                                                                      |
| notification\_email\_address | String            | email address for notification emails                                                                                                                                                                                                                                                                                                                                                |
| notification\_email\_success | Boolean           | Send email on successful workflow execution                                                                                                                                                                                                                                                                                                                                          |
| notification\_email\_failure | Boolean           | Send email on failed workflow execution                                                                                                                                                                                                                                                                                                                                              |

{% tabs %}
{% tab title="200: OK Returns the new workflow in JSON format" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Get all schedule workflows

Get all configured schedule workflow configurations

## Get all configured schedule workflows

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/workflow/schedules`

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK Json object with all workflows in a JSON array. " %}

```javascript
{
    "result": [{...}, {...}]
}
```

{% endtab %}
{% endtabs %}


# Get schedule workflow

Get a specific schedule workflow configuration.

## Get specific schedule workflow configuration

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/workflow/schedules/<workflow_id>`

#### Path Parameters

| Name         | Type   | Description |
| ------------ | ------ | ----------- |
| workflow\_id | String | Workflow ID |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "result": {...}
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid authentication" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Trigger schedule workflow

Trigger specific schedule workflow for testing purposes.

## Trigger specific schedule workflow for testing purposes.

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/workflow/schedules/<workflow_id>/trigger`

#### Path Parameters

| Name         | Type   | Description |
| ------------ | ------ | ----------- |
| workflow\_id | String | Workflow ID |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "result": {...}
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid authentication" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Delete Scheduled Workflow

Delete a schedule workflow

## Delete a schedule workflow

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/workflow/schedules/<workflow_id>`

#### Path Parameters

| Name         | Type   | Description                               |
| ------------ | ------ | ----------------------------------------- |
| workflow\_id | String | Id of the workflow that should be deleted |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK Successfully delete the workflow" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden Authentication invalid" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Event Automations


# Create/Update

Create or update an action workflow

## Create an action workflow

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/workflow/events`

&#x20;

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

#### Request Body

| Name       | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| ---------- | ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|            | String            | If id is provided the existing workflow with this id will be updated.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| enabled    | Boolean           | Enable or disable the workflow                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| name       | String            | Workflow name in the system                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| conditions | JSON Array String | <p>Conditions that need to be met for this workflow to action upon.</p><p></p><p>E.g.</p><p>\[ { "condition\_type": "and", "id": "e6fde778-66cc-48ce-89ba-0fc7c41645e9", "transaction\_type": "upload", "type": "transaction" }, { "condition\_type": "and", "directory": "/myfolder/compressed/", "id": "c96fc558-904e-4a80-993d-2d8ebc42f3fe", "negate": false, "type": "directory\_matches" }, { "condition\_type": "and", "filename\_pattern": "\*.bz2", "id": "98fe1b8c-8516-4dbc-be1f-0bdce1cc131b", "negate": false, "type": "filename\_matches" } ]</p> |
| actions    | JSON Aray String  | <p>Action that will run on the files/folders that match the conditions.</p><p></p><p>E.g.</p><p>\[ { "actions": \[ { "email\_address": "<user1@couchdrop.io>", "id": "51856312-fa6c-469e-86da-0a3028611069", "type": "email" } ], "decompress\_to": "/myfolder/decompressed/", "decompress\_type": "bz2", "id": "1ce2e380-a4bc-4d05-a8e5-c47e76461419", "type": "decompress" } ]</p>                                                                                                                                                                            |
| delay      | Integer           | Delay of the workflow execution in seconds.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| position   | Integer           | Position of this workflows run order if multiple workflows are configured. Starts with 0                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |

{% tabs %}
{% tab title="200: OK Returns the new workflow in JSON format" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden " %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Get action workflow

Get a specific action workflow configuration.

## Get specific action workflow configuration

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/workflow/events/<workflow_id>`

#### Path Parameters

| Name         | Type   | Description |
| ------------ | ------ | ----------- |
| workflow\_id | String | Workflow ID |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "result": {...}
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid authentication" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Get all action workflows

Get all configured action workflow configurations

## Get all configured action workflows

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/workflow/events`

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK Json object with all workflows in a JSON array. " %}

```javascript
{
    "result": [{...}, {...}]
}
```

{% endtab %}
{% endtabs %}


# Trigger action workflow

Trigger specific action workflow.

## Trigger specific action workflow.

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/public/workflow/<workflow_id>/trigger`

#### Path Parameters

| Name         | Type   | Description |
| ------------ | ------ | ----------- |
| workflow\_id | String | Workflow ID |

#### Headers

| Name          | Type   | Description                                                                                                                                                                                        |
| ------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Authorization | String | <p>Access token generated in the workflow settings, if required. Must be specified as a Bearer token, in the format<br>Bearer \<token><br>e.g. <br>Bearer 23ed462a-1f53-4326-b77b-58a3c94ec274</p> |

#### Request Body

| Name       | Type        | Description                                                                                                                               |
| ---------- | ----------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| path       | String      | Path to file / folder that will be used in the action. Optional: will default to the home directory of the user who created the workflow. |
| parameters | JSON String | JSON object mapping values to custom variables configured on the workflow, if there are any. Optional.                                    |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "result": {...}
}
```

{% endtab %}

{% tab title="403: Forbidden Invalid authentication" %}

```json
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Delete Action Workflow

Delete an action workflow

## Delete an action workflow

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/workflow/events/<workflow_id>`

#### Path Parameters

| Name         | Type   | Description                               |
| ------------ | ------ | ----------------------------------------- |
| workflow\_id | String | Id of the workflow that should be deleted |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | String | API Access Token |

{% tabs %}
{% tab title="200: OK Successfully delete the workflow" %}

```javascript
{
    // Response
}
```

{% endtab %}

{% tab title="403: Forbidden Authentication invalid" %}

```javascript
{
    // Response
}
```

{% endtab %}
{% endtabs %}


# Actions

When configuring an automation, you are required to configure a set of actions. These actions apply to the files matching the conditions of the automation.

#### The action object

Both Schedule automations and Event automations require actions. Actions are passed as JSON objects in an array. See the [Scheduled Automations](/administration/automations/scheduled-automations) nad [Event Automations](/administration/automations/event-automations) docs to see how to include them when configuring the automations .

Here is an example of what an action object looks like.

```json
[
    {
        "type":"<action_type>",
        ....
    }
]
```

Actions have variable params, which can be found below. An example of a copy action is here

```
{
    "type":"copy",
    "copy_to":"/new/destination/"
}
```

#### Available Action Types

As of writing this document, we support the following action types.&#x20;

| Action Type  | Description                            |
| ------------ | -------------------------------------- |
| webhook      | Fire a webhook of to a remote endpoint |
| rename       | Rename the file                        |
| delete       | Delete the file                        |
| copy         | Copy/duplicate the file                |
| move         | Move the file to a new location.       |
| email        | Send an email notification             |
| compress     | Compress the file                      |
| decompress   | Decompress the file                    |
| unarchive    | Unarchive the file                     |
| pgp\_encrypt | Encrypt the file with PGP              |
| pgp\_decrypt | Decrypt a file encrypted with PGP      |


# Webhook

The webhook action sends a HTTP/HTTPS webhook to the destination specified.

**Required Fields**

| Key          | Description                               |
| ------------ | ----------------------------------------- |
| type         | The action type. Must be set as "webhook" |
| webhook\_url | <https://endpoint.com/webhook>            |

**Example**

```
{
    "type":"webhook",
    "webhook_url":"https://endpoint.com/webhook"
}
```

The webhook body will follow the general webhook structure defined [Webhooks](/webhooks/using-webhooks)


# Rename

The rename action renames a file.

**Required Fields**

| Key        | Description                              |
| ---------- | ---------------------------------------- |
| type       | The action type. Must be set as "rename" |
| rename\_to | example.txt                              |

**Example**

```
{
    "type":"rename",
    "rename_to":"example.txt"
}
```

The "rename\_to" field can include custom path as detailed in [Paths](/administration/automations/actions/paths)


# Copy

The copy action duplicates a file, copying it to a new destination

**Required Fields**

| Key      | Description                            |
| -------- | -------------------------------------- |
| type     | The action type. Must be set as "copy" |
| copy\_to | example.txt                            |

**Example**

```
{
    "type":"copy",
    "copy_to":"example.txt"
}
```

The "copy\_to" field can include custom path as detailed in [Paths](/administration/automations/actions/paths)


# Move

The move action copies a file then removes the original object. Effectively moving the file.

**Required Fields**

| Key      | Description                            |
| -------- | -------------------------------------- |
| type     | The action type. Must be set as "move" |
| move\_to | example.txt                            |

**Example**

```
{
    "type":"move",
    "move_to":"/destination_folder/"
}
```

The "move\_to" field can include custom path as detailed in [Paths](/administration/automations/actions/paths)


# PGP Encrypt

The PGP encrypt action can be used to encrypt files as part of a workflow.

**Required Fields**

| Key                                     | Description                                                                                                         |
| --------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| type                                    | The action type. Must be set as "pgp\_encrypt"                                                                      |
| pgp\_encrypt\_pub\_key                  | The public key you want to encrypt the file with.                                                                   |
| pgp\_sign\_with\_private\_key           | (Optional) If you want to sign the file with a private key after encrypting it, set this field to your private key. |
| pgp\_sign\_with\_private\_key\_password | (Optional) If you are signing the file with a private key, normally you need to specify a password for your key.    |

**Example**

```
{
    "type":"pgp_encrypt",
    "pgp_encrypt_pub_key":"--- BEGIN KEY ---... --- END KEY ---"
}
```


# Paths

Certain operations work on paths. Couchdrop has a bunch of path variables available that can be used to craft relevant paths.

When working with paths, we need to determine whether the path provided is a folder or absolute filename.

If the path provided ends with a "/", then we will assume that the path is a directory and include it and the original filename,&#x20;

For example:

| Source File             | Configured Path | Result                   |
| ----------------------- | --------------- | ------------------------ |
| /directory/filename.txt | /newdir/        | /newdir/filename.txt     |
| /directory/filename.txt | filename2.txt   | /directory/filename2.txt |

You can use dynamic variables in the path to compose a useful destination filename. Available variables are:

| Variable         | Example Result            | Desc                          |
| ---------------- | ------------------------- | ----------------------------- |
| {EXISTING\_NAME} | filename.txt              | Take the filename             |
| {TIMESTAMP}      | 160331234                 | A unix timestamp              |
| {YYYY}           | 2050                      | The current year              |
| {YY}             | 50                        | The current year in shorthand |
| {MM}             | 03                        | The month                     |
| {DD}             | 10                        | The day of the month          |
| {USER}           | donald                    | The user on the event         |
| {EVENT.\*}       | {EVENT.username} - donald | Any attribute on the event    |

&#x20;

An example of a dynamic path used in a copy operation:

```
{
    "type":"copy",
    "copy_to":"/processed_files/{USER}/{YY}/{MM}/{DD}/{EXISTING_FILENAME}"
}
```


# Conditions

When configuring an automation, you can set additional conditions on it which are required to match before the automation will fire.

| Type Key                  | Description                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| filename\_matches         | Filenames must match this expression. The expression can be a wildcard or a regular expression |
| filename\_matches\_negate | Filenames must not match the following.                                                        |
| modtime                   | The file must have a last modified time that matches the conditions.                           |


# Symlinks/Shortcuts

Symbolic links or Shortcuts provide a versatile and easy way to work with directories in multiple locations. A symlink/shortcut can point to any folder in the Couchdrop virtual file system.

Managing symbolic links can be done through the admin interface or via the API.&#x20;

## Get all symbolic links in the organisation

<mark style="color:blue;">`GET`</mark> `https://api.couchdrop.io/manage/symlinks`

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    result: [
        {"source": "/link", "destination":"/dropbox/folder1", "id":"id1"},
        {"source": "/link2", "destination":"/dropbox/folder2", "id":"id2"}
    ]
}
```

{% endtab %}
{% endtabs %}

## Create a new symbolic link

<mark style="color:orange;">`PUT`</mark> `https://api.couchdrop.io/manage/symlinks`

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "result":{
        "id": "id1"
    }
}
```

{% endtab %}
{% endtabs %}

## Modify an existing symbolic link

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/symlinks`

#### Request Body

| Name                                          | Type   | Description                                                                                  |
| --------------------------------------------- | ------ | -------------------------------------------------------------------------------------------- |
| id<mark style="color:red;">\*</mark>          | String | ID of the symbolic link you are modifying                                                    |
| source<mark style="color:red;">\*</mark>      | String | The source path for the link. This is the path where the link will appear in the filesystem. |
| destination<mark style="color:red;">\*</mark> | String | The destination path. Where the link points to in the real filesystem                        |

## Delete an existing link

<mark style="color:red;">`DELETE`</mark> `https://api.couchdrop.io/manage/symlinks/<link_id>`

#### Path Parameters

| Name     | Type   | Description                             |
| -------- | ------ | --------------------------------------- |
| link\_id | String | The ID of the object you want to delete |


# Auditing and Reporting

Couchdrop has comprehensive auditing across all operations. Audit events can be pulled from the API

## Get audit events

<mark style="color:green;">`POST`</mark> `https://api.couchdrop.io/manage/files`

#### Query Parameters

| Name     | Type   | Description        |
| -------- | ------ | ------------------ |
| page     | Number | Page number        |
| pagesize | Number | Required page size |

#### Headers

| Name                                    | Type   | Description |
| --------------------------------------- | ------ | ----------- |
| token<mark style="color:red;">\*</mark> | String | API token   |

#### Request Body

| Name      | Type    | Description                                                             |
| --------- | ------- | ----------------------------------------------------------------------- |
| transfers | Boolean | Example filter. See filters below for more details of available filters |

{% tabs %}
{% tab title="200: OK " %}

```javascript
{
    "files":[{
        "time":<timestamp>,    
        "filename":"",
        "filename_relative":"",
        "authenticated_user":"",
        "event_type":"", 
        "success":true,
        "total_size":0,
        "additional_info": "",
        "message": "a message"
    }],
    "pagination":{
        "total_records": total_records,
        "page": page,
        "page_size": pagesize,
        "total_pages": total_pages
    }
}
```

{% endtab %}
{% endtabs %}

#### Complex Filters

The API allows you to filter and search for specific events and event types. Filters are supplied as POST body params in JSON.&#x20;

| Filter Param        | Description                                                                 | Example value     |
| ------------------- | --------------------------------------------------------------------------- | ----------------- |
| transfers           | Include UPLOAD and DOWNLOAD events                                          | true              |
| authentication      | Include authentication events.                                              | true              |
| malware             | Include malware events                                                      | true              |
| admin               | Include admin and management events                                         | true              |
| filesystem          | Include filesystem events like LS/LSTAT/RENAME                              | true              |
| workflow            | Include workflow events                                                     | true              |
| authenticated\_user | Filter events to a specific user                                            | "user1"           |
| transaction\_id     | Filter events to a specific transaction id                                  | "\<uuid>"         |
| filename            | Filter events to a specific filename                                        | "example.txt"     |
| search              | Wildcard search on the filename and message field                           | "downloaded file" |
| workflow\_id        | Filter events to those to those generated by a specific workflow/automation | "\<uuid>"         |

#### Specifying a time frame filter&#x20;

You can restrict results to a specific time period, this can be done using relative or absolute time. Time filtering is sent to the API in the same way as the [#complex-filters](#complex-filters "mention") above.&#x20;

| Filter param        | Description                                                                   | Example                                                                                                             |
| ------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------- |
| date                | Filter type                                                                   | <p>Accepted values: </p><ul><li>hour</li><li>2hours</li><li>day</li><li>week</li><li>month</li><li>custom</li></ul> |
| custom\_start\_date | When "date" is set to "custom" this is required. A unix timestamp is required | 1674767806                                                                                                          |
| custom\_end\_date   | End date for above                                                            | 1674769100                                                                                                          |


# Using webhooks

Couchdrop provides configurable webhooks on all file events. Webhooks can be sent to a HTTPS endpoint and always contain a JSON body with the event details.

## An example event body

Fields included in the body are variable and additional fields will be added over time, below is an example of a upload or download event

```
{
"account":"devaccount1",
"filename":"/storage/testfile.txt",
"authenticated_user":"user1",
"event_type":"upload",
"ip_address":"8.8.4.4",
"success": true,
"total_size":173331,
"additional_info":"",
            
"system":"sftp",
"transaction_id":"<randomuuid>",
}
```

{% hint style="info" %}
Get in touch with support for more information or to request particular fields be added to the webhooks
{% endhint %}


# Listing files/folders

### List files and folders

Listing files and folder can be done using the LS method. This method returns a list of all objects in a folder.&#x20;

## /file/ls

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/ls`

List files and directories in a given path

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name | Type   | Description |
| ---- | ------ | ----------- |
| path | string | Target Path |

{% tabs %}
{% tab title="200 A list of objects describing files and folders" %}

```
{
    "ls":[
        {
            "filename": "document1.txt",
            "size:": 10234,
            "modtime": 1578531065,
            "is_dir": false
        },
        {
            "filename": "folder1",
            "size:": 0,
            "modtime": 0,
            "is_dir": true
        }
    ]
}
```

{% endtab %}

{% tab title="403 " %}

```
{"error": "you do not have the right permissions"}
```

{% endtab %}

{% tab title="500 " %}

```
{"error": "we encountered an error"}
```

{% endtab %}
{% endtabs %}

#### Get file/folder details

You can use the LSTAT method to get details on an individual file or folder

## /file/lstat

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/lstat`

Retrieve properties for a file or folder.&#x20;

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name | Type   | Description                    |
| ---- | ------ | ------------------------------ |
| path | string | Target path of file or folder. |

{% tabs %}
{% tab title="200 " %}

```
{
    "lstat": {
        "filename": "document1.txt",
        "size:": 10234,
        "modtime": 1578531065,
        "is_dir": false
    }
}
```

{% endtab %}
{% endtabs %}

&#x20;


# Downloading a file

How to stream a file with Couchdrop

## Download a file

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/download`

Download a file

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name | Type   | Description        |
| ---- | ------ | ------------------ |
| path | string | Full path to file. |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}


# Uploading a File

Uploading a file is the most common use case for our API. Files are uploaded in binary form as the post body.

## Upload a File

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/upload`

This endpoint allows you to upload files

#### Query Parameters

| Name    | Type   | Description                                                                                     |
| ------- | ------ | ----------------------------------------------------------------------------------------------- |
| path    | string | Path to upload destination                                                                      |
| size    | number | File size                                                                                       |
| modtime | number | Last modified time. (Not all storage providers support the specification of modtimes on upload) |

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name | Type   | Description           |
| ---- | ------ | --------------------- |
| data | object | File object to upload |

{% tabs %}
{% tab title="200 Cake successfully retrieved." %}

```
{}
```

{% endtab %}

{% tab title="403 Permission denied" %}

```
{"error": "you cannot write to that folder"}
```

{% endtab %}
{% endtabs %}


# Rename files/folders

## Renaming a file

## /file/rename

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/rename`

Rename a file

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name     | Type   | Description      |
| -------- | ------ | ---------------- |
| path\_to | string | Destination Path |
| path     | string | Source Path      |

{% tabs %}
{% tab title="200 " %}

```
{
    "rename": true
}
```

{% endtab %}
{% endtabs %}

&#x20;


# Deleting files/folders

## Removing a file

## /file/remove

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/remove`

Remove a file

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name | Type   | Description |
| ---- | ------ | ----------- |
| path | string | Filename    |

{% tabs %}
{% tab title="200 " %}

```
{
    "remove": true
}
```

{% endtab %}
{% endtabs %}

&#x20;


# Create a folder

## Creating/Deleting Folders

## Create a folder

<mark style="color:green;">`POST`</mark> `https://fileio.couchdrop.io/file/mkdir`

Creates a new folder at the specified path

#### Headers

| Name  | Type   | Description      |
| ----- | ------ | ---------------- |
| token | string | API Access Token |

#### Request Body

| Name | Type   | Description           |
| ---- | ------ | --------------------- |
| path | string | Path to new directory |

{% tabs %}
{% tab title="200 " %}

```
```

{% endtab %}
{% endtabs %}