/streams

Start ascp4 sessions that stream data from source to destination, and modify and cancel an in-progress stream. To retrieve stream transfer information, make a GET request to /ops/transfers/{stream_id}, using the ID returned in the POST /streams response.

The /streams endpoint can also be used to start and manage regular ascp4 transfers, in order to make use of options like read_threads and write_threads that are not available for transfers that are started with a POST request to /ops/transfers.

Requirements
  • Available as of Enterprise Server version 3.7.3.
  • The server must have a FASPStream license.
  • If using UDP or TCP providers, the transfer user must have a UDP or TCP restriction set in aspera.conf on the server rather than a docroot.
Access Control
  • HTTP Basic Auth
    Provide an access key ID and secret. /streams does not support Node API credential authorization.
  • Bearer token
    With bearer token authentication, actions are restricted to the tenant space defined by the bearer token and the permissions set on the content.
Headers

All requests to this endpoint use the same headers.

Header Name Required Description Values
Content-Type Optional The format of the request data. application/json
Accept Optional The format of the response data. application/json
X-Aspera-AccessKey Required
(for bearer token authorization)
The access key ID that was used to create the bearer token. Access key ID.
Authorization Required
(for bearer token authorization)
The bearer token. "Bearer token_string"
Status Codes and Errors
Code Description Notes
200 OK Success Stream started or modified successfullyl.
400 Bad Request Error Request contains a formatting or syntax error.
403 Error A restriction for the UDP or TCP provider might not exist for the transfer user on the server.
404 Not Found Error Invalid stream ID used in a PUT or CANCEL request.
500 Internal Server Error Error The server configuration is invalid.

Endpoint Actions

Start a Stream

Start a data stream that uses ascp4 for the transfer.

URL
POST https://{domain}:9092/streams

Sample Request
curl -i -u user:secret -X POST https://{domain}:9092/streams \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -H "X-Aspera-AccessKey: 438ofhsdt4elt2349572r3o8fhkfh" \
     -H "Authorization: Bearer 32953nawo35u38rh28935ywafnll3w5rh38a5hr23iarho3irh23irh"
     -d @request_body.json

Where request_body.json contains the following:
{
    "remote_host": "10.0.0.2",
    "remote_user": "xfer",
    "source": "udp://10.0.0.2:40020",
    "destination": "udp://10.0.0.2:40021"
    "ssh_port": 22,
    "direction": "send",
    "dgram_size": 65535,
    "target_rate_kbps": 1234,
    "min_rate_kbps" : 0,
    "compression" : "none",
    "read-threads" : 1,
    "write-threads" : 1,
    "title": "UDP-to-UDP"
  }

Request Body
Name Required Type Description
remote_host Required String The IP address or qualified domain name of the remote host.
remote_user Optional String The transfer user on the remote node for SSH authentication. Default: xfer.
source Required String The source of the stream as a URI path and port. For example, udp://233.3.3.3:3000 or tcp://233.5.5.5000. For regular ascp4 transfers, the full path to the source file or directory.
destination Required String The destination of the stream as a URI path and port. For example, udp://233.3.3.3:3000 or tcp://233.5.5.5000. For regular ascp4 transfers, the full path to the source file or directory.
ssh_port Optional Unsigned integer SSH port. Default: 33001.
direction Required String Transfer direction, either send or receive.
dgram_size Optional Unsigned integer The size of a datagram. Default: 1492. Valid range: 296 to 65535.
target_rate_kbps Optional Unsigned integer The target rate for the stream, in Kbps.
min_rate_kbps Optional Unsigned integer The minimum rate for the stream, in Kbps. Available as of 3.8.0.
compression Optional String Compress file data inline. Value can be none, lz4, or zlib. Default: lz4. Available as of 3.8.0.
read-threads Optional Unsigned integer The number of storage read threads to use on the source. Default: 1. Must be set to 1 for streaming transfers, whereas regular ascp4 transfers can use more. Available as of 3.8.0.
write-threads Optional Unsigned integer The number of storage write threads to use on the destination. Must be set to 1 for streaming transfers, whereas regular ascp4 transfers can use more. Available as of 3.8.0.
Sample Response
The response is the same as that for a POST request to /ops/transfers.
HTTP/1.1 200 OK
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8

{
"id" : "4ed0d533-47cd-499b-85cd-8b0c54b96035",
"title" : null,
"tags" : {"aspera":{"xfer_id":"4ed0d533-47cd-499b-85cd-8b0c54b96035","xfer_retry":15}},
"token" : null,
"cookie" : null,
"direction" : "send",
"remote_host" : "localhost",
"remote_user" : "root",
"remote_access_key" : null,
"source_root" : "/",
"destination_root" : "/",
"fasp_port" : 33001,
"ssh_port" : 33001,
"rate_policy" : "fair",
"symlink_policy" : "",
"target_rate_kbps" : -1,
"cipher" : "aes-128",
"content_protection" : null,
"content_protection_password" : null,
"overwrite" : "diff",
"retry_duration" : "",
"create_dir" : false,
"precalculate_job_size" : false,
"delete_source" : false,
"remove_after_transfer" : false,
"remove_empty_directories" : false,
"multi_session" : 1,
"multi_session_threshold" : null
}

Response
Element Type Description
id String Unique transfer ID.
title String Name of the transfer, if any.
tags JSON Application-generated tags to describe the transfer. Can be used to filter GET requests.
xfer_id String Transfer ID (same as id).
xfer_retry Unsigned integer The number of retry attempts.
token String The transfer authorization token.
cookie String The cookie generated by the application or provided in the POST request.
direction String The direction of the transfer.
remote_host String IP or fully qualified domain name of the remote server.
remote_user String Transfer user name.
remote_access_key String Remote access key for the transfer.
source_root String The file ID of the source root directory.
destination_root String The file ID of the destination root directory.
fasp_port Unsigned integer The port that is used for data transfer.
ssh_port Unsigned integer The port that is used for the SSH connection.
rate_policy String The transfer's rate policy.
target_rate_kbps Unsigned integer The target rate for the transfer, in Kbps.
cipher String The encryption algorithm that is used to encrypt data in transit.
content_protection String The client-side encryption-at-rest action: encrypt or decrypt.
content_protection_password String The passphrase for the client-side encryption-at-rest action, if any.
overwrite String The overwrite policy.
resume_policy String The resume policy
retry_duration Unsigned integer The duration of retry attempts.
create_dir Boolean If directories are created on the destination. Default: false.
precalculate_job_size Boolean If the job size is calculated before transfer. Default: false.
delete_source Boolean If all source files, empty directories and the source argument itself are removed after they are successfully transferred. Default: false.
remove_after_transfer Boolean If the source files are removed after they are successfully transferred. Default: false
remove_empty_directories Boolean If empty directories on the source are deleted after the files within them are successfully transferred. Default: false.
multi_session Unsigned integer The number of simultaneous transfer sessions allowed.
multi_session_threshold Unsigned integer The file size above which files are split across sessions.

Modify a Stream

Modify the transfer specification of an active transfer by submitting a partial or complete request body with the new values.

URL
PUT https://{domain}:9092/streams/{id}

Sample Request
curl -i -u user:secret -X PUT https://{domain}:9092/streams/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json" \
     -d '{"target_rate_kbps":0}'

Request Body
Element Required Type Description
status Optional String The new value for the status. To cancel a transfer, set to "canceled", "cancelled", or "stopped". To pause a transfer, set to "paused". To resume a paused transfer, set to "running" or "resume".
target_rate_kbps Optional Unsigned integer The new target transfer rate, in Kbps.
min_rate_kbps Optional Unsigned integer The new minimum transfer rate, in Kbps.
rate_policy Optional String The new rate policy to apply to the transfer. Allowed values: "fixed", "fair", or "low".
Sample Response

The response is the same as for a POST request and returns the updated values.


Cancel a Stream

Cancel the specified transfer. This is a shortcut to sending a PUT request to /streams/{id} with {"status" : "canceled"} in the request body.

URL
CANCEL https://{domain}:9092/streams/{id}

Sample Request
curl -i -u user:secret -X CANCEL https://{domain}:9092/streams/{id} \
     -H "Content-Type: application/json" \
     -H "Accept: application/json"

Sample Responses

Success:

HTTP/1.1 204 No Content
Cache: no-cache
Connection: close
Content-Type: application/json; charset=utf-8
Content-Length: 0

Error:

{
   "error":{
      "code":404,
      "reason":"Not Found",
      "user_message":"Transfer not found")
   }
}


Response
The response body contains no content if the request is successful.
Element Type Description
error JSON object Error response.
code Double HTTP error code.
reason String HTTP error message.
user_message String Error description.
Video player

Video

×