The following describes how to upload or download a package with the transferSpec (transfer specification) and the Faspex API v.4.

1. Request a bearer token for transfer activity on the server according to the example in Create an OAuth token.

For example:

curl -X POST -u admin_user

When making your request to the endpoint, copy the your token into the "Bearer" field in the header.

2. Create a package with a POST request to the following endpoint, using the bearer token returned in step 1:


This creates a record of the package in the database and a storage directory for the files. It also generates a package ID that you can use later to GET information about the package.

For example:

curl -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: Bearer 9xh8lVuHfwgRp_51swbxBA" --data '{"recipients": ["admin"], "senders": ["admin"], "title": "asd"}'





Note: The parameters in the --data object are required. See "Create a package" for complete information.

3. Request the transfer specification to allow the transfer. Note: You must specify the direction of the transfer, either send or receive.

Request Format:

api/users/{user_id}|{package_id}/packages/{package_id}/transfer_specs --data '{"direction": "send" | "receive"}'

For example:

curl -H "Accept: application/json" -H "Content-type: application/json" -H "Authorization: Bearer 9xh8lVuHfwgRp_61swbxBA" --data '{"direction": "send"}'
    "source_root": "",
    "destination_root": "/asd - 2fb0b61e-ec57-4171-b540-15eab3179a34.aspera-package/PKG - asd/",
    "paths": [
            "destination": "asd - 2fb0b61e-ec57-4171-b540-15eab3179a34.aspera-package/PKG - asd/"
    "content_protection": null,
    "target_rate_kbps": 20000,
    "target_rate_cap_kbps": 100000,
    "rate_policy": "fair",
    "rate_policy_allowed": "fixed",
    "cipher": "aes-128",
    "cipher_allowed": null,
    "remote_host": "",
    "remote_user": "faspex",
    "ssh_port": 33001,
    "fasp_port": 33001,
    "http_fallback": true,
    "http_fallback_port": 443,
    "https_fallback_port": null,
    "sshfp": null,
    "cookie": "aspera.faspex20:u:6d2fc967-72ef-4252-8f2f-ebe87e104885:amVmZg:eyJfcGtnX3V1aWQiOiIyZmIwYjYxZS1lYzU3LTQxNzEtYjU0MC0xNWVhYjMxNzlhMzQiLCJfcGtnX25hbWUiOiJhc2QiLCJfY3JlYXRlZF91dGMiOiIyMDE3LzEwLzEzIDE4OjQ5OjQ0ICswMDAwIn0:YXNk",
    "tags": {
        "aspera": {
            "faspex": {
                "requestor": {
                    "name": "josh",
                    "first_name": "Josh",
                    "last_name": "James",
                    "email": "",
                    "Department": "Dev",
                    "Location": ""
                "metadata": {
                    "_pkg_uuid": "2fb0b61e-ec57-4171-b540-15eab3179a34",
                    "_pkg_name": "asd",
                    "_created_utc": "2017/10/13 18:49:44 +0000"
                "recipients": [
                        "name": "admin",
                        "first_name": "Aspera",
                        "last_name": "Admin",
                        "email": "",
                        "Department": "SE",
                        "Location": ""

For more information, see the documentation for the Transfer Specifications.

4. To initiate the transfer, authorize it by doing one of the following:

  • Pass the transferSpec to Connect with the Javascript API. For more information, refer to the transferSpec examples, and the Connect API documentation.
  • For a node-to-node transfer, use the ops/transfer endpoint; see the Node API Guide for more information.

5. If you need to edit the transfer by uploading to a subdirectory, you must request a token with the following endpoint:

POST /api/users/{user_id}/packages/{package_id}/issue_token

The issue token that is returned is used to modify the current transferSpec when editing a transfer. For information about generating the token, see "Issue a token for a file upload".

Note: If you seek permission to edit a package transfer for a subdirectory under the root directory; the token (permission) for the root directory is included in the transfer spec which you already requested.

Video player