A package is a bundle of files and folders (like a ZIP file or TAR file). Packages can be sent to people. Files and folders, on the other hand, can be shared with other people; when a file or folder is sent to someone, it is put into a package.

There are essentially two ways to send a package:

  1. Create a package, transfer files and folders into it, then send the notification manually.
  2. Create a package, then configure Files to send the notification automatically after the transfer of files and folders is complete.

    To use this second option, the following must be true:

    • Transfers must be tagged with the following
      {"aspera": {"files": {"package_id": the-package-id}}}
    • When you send your request, the value set for the transfers_expected parameter must match the current number of transfers.

    For example:

    1. Create a Package (POST to /packages)
    2. Start to transfer Files and Folders into the Package
    3. Before the transfer finishes the client can PUT {"sent": true, "transfers_expected": 1}. This tells Files to automatically send the package when that 1 transfer has finished.

  3. Endpoint Request Format

    The request format for the the endpoint is the following:

    https://api.asperafiles.com/api/v1/{method}
    .

    For example:

    https://api.asperafiles.com/api/v1/packages

    Request Parameters for Packages

    • active_download_count - (read-only)
    • archived
    • average_rate - (read-only) in kbps
    • bytes_transferred - (read-only)
    • complete - (read-only) whether all transfers into the package have completed successfully and all contents are present
    • content_expires_at - (read-only) When contents should expire according to policy
    • content_retention_duration - in seconds, must be more restrictive than workspace settings (read-write)
    • contents_file_id - (read-only) the location of the "contents" folder in the Package. This is the folder that will contain all the files and folders that are being sent.
    • created_at - (read-only) when the package was created
    • delete_package_content_after_download_duration - in seconds, must be more restrictive than workspace settings(read-write)
    • deleted - (read-only) if package was deleted
    • deleted_at - (read-only) when the package contents were deleted
    • deleted_by_admin - (read-only)
    • deleted_by_user_id - (read-only)
    • expired_at
    • expired
    • failed_download_count - (read-only)
    • failed - (read-only)
    • file_count - (read-only) total number of files in the package, if available
    • file_id - (read-only) the location of the folder containing the top-level .asp-package folder on the node
    • files_completed - (read-only)
    • files_expected - (read-only)
    • folders_completed - (read-only)
    • folders_expected - (read-only)
    • full_download_count - (read-only)
    • id - (read-only) a short, unique string that also corresponds with the the name of the top-level .asp-package folder on disk
    • message_id - (read-only) A custom Message of type "package" that will be sent instead of the default system-generated Message. To associate a message with this package, create a message referencing this package.
    • metadata - JSON array containing an ordered list of metadata
    • name - (required) name with illegal characters stripped out or substituted
    • node_id - (read-only)
    • note
    • partial_download_count - (read-only)
    • read
    • received - (read-only)
    • recipients
    • sender
    • sent (read-only, except when setting to true on a draft package). Set this to true to "freeze" the Package and send its Message to the recipients.
    • sent_at - (read-only) when the package was sent
    • size - (read-only) total size of the package in bytes, if available
    • time_remaining - (read-only) in seconds
    • workspace_id - specifies the workspace this package belongs to, if any

    Query Parameters (for GET):

    • archived
    • completed_at
    • complete
    • deleted
    • dropbox_id
    • embed%5B%5D=message
    • embed%5B%5D=node
    • embed%5B%5D=organization
    • embed%5B%5D=workspace
    • expired
    • failed
    • name
    • q - Search package_addressees.email, package_addressees.first_name, package_addressees.last_name, packages.name
    • read
    • received
    • sent_at
    • sent
    • size
    • workspace_id

    Notes

    • The folder structure of a package on disk is as follows:
      • {id}.asp-package
        • contents
          • contained files and folders go here
        • metadata and other package-related files can go here
    • Uploads of package content should go directly into the named, innermost folder.
    • Downloads of the entire package should be of the named, innermost folder (renamed on download to the package name itself).
    • To get package transfers to properly register, they should be tagged as follows: {"aspera": {"files": {"package_id": the-package-id}}}

    Get sent and received packages

    GET /packages

    This method returns all packages that the user has sent or received.

    Response Example

    {
       "active_download_count":null,
       "archived":false,
       "average_rate":0.0137914,
       "bcc":false,
       "bcc_recipients":[
    
       ],
       "bytes_transferred":4,
       "complete":true,
       "completed_at":"2017-08-01T22:30:46.000Z",
       "content_expires_at":"2017-08-10T22:30:46.000Z",
       "content_retention_duration":777600,
       "contents_file_id":"694378",
       "created_at":"2017-08-01T22:30:28.000Z",
       "delete_after_download":true,
       "delete_package_content_after_download_duration":86400,
       "deleted":false,
       "deleted_after_download":false,
       "deleted_at":null,
       "deleted_by_admin":false,
       "deleted_by_user_id":null,
       "download_notification_recipients":[
    
       ],
       "draft":false,
       "draft_expires_at":null,
       "expiration_reason":null,
       "expired":false,
       "expired_at":null,
       "failed":false,
       "failed_download_count":null,
       "file_count":2,
       "file_count_from_disk":true,
       "file_id":"694377",
       "files_completed":2,
       "files_expected":2,
       "folders_completed":0,
       "folder_count":0,
       "folders_expected":0,
       "full_download_count":null,
       "has_content":true,
       "id":"yPAf-DKmA",
       "metadata":null,
       "name":"from Express",
       "node_id":"95",
       "note":null,
       "package_sent":true,
       "partial_download_count":null,
       "read":true,
       "recalled_at":null,
       "received":true,
       "sender":{
          "email":"yseliverstov@asperasoft.com",
          "id":"599",
          "name":"Yuriy Seliverstov",
          "type":"user"
       },
       "sent":true,
       "sent_at":"2017-08-01T22:30:28.000Z",
       "size":4,
       "time_remaining":0,
       "transfers_expected":2,
       "updated_at":"2017-08-01T22:30:46.000Z",
       "upload_notification_recipients":[
    
       ],
       "upload_started":true,
       "upload_started_at":"2017-08-01T22:30:44.000Z",
       "workspace_id":"1203",
       "recipients":[
          {
             "email":"yseliverstov@asperasoft.com",
             "id":"599",
             "name":"Yuriy Seliverstov",
             "type":"user"
          }
       ]
    }

    Create a package

    POST /packages

    This method creates a package into which files can be uploaded.

    Query Parameters: None

    Required: workspace_id

    Example Request Body:

    {
      "recipients": [{"type": "user", "id": "3"}],
      "name": "Vacation",
      "metadata": [
        {"name": "Location", "values": ["Hawaii"]},
        {"name": "Date", "values": ["3/21/2015"]}
      ]
    }

    Example Response:

    201 Created

    {
       "id":"1xaEzw",
       "created_at":"2014-04-15T18:51:32.137Z",
       "sender":{
          "id":"2",
          "name":"Jacob Erlich",
          "email":"jacob@asperasoft.com",
          "type":"user"
       },
       "recipients":[
          {
             "type":"user",
             "id":"3",
             "name":"Jimmy Song",
             "email":"jimmy@asperasoft.com"
          }
       ],
       "name":"Vacation",
       "metadata":[
          {
             "name":"Location",
             values:[
                "Hawaii"
             ]
          },
          {
             "name":"Date",
             values:[
                "3/21/2015"
             ]
          }
       ],
       "sent":false,
       "received":false,
       "archived":false,
       "read":false,
       "complete":false,
       "failed":false
    }

    Get information for a package

    GET /packages/{id} This method retrieves information for a package with a particular ID.

    Query Parameters

    Get the download_count resource

    GET /package/{id}/download_counts This method returns the download_count resource, which is a read-only aggregate metric containing the number of downloads (copies) a user has made.

    Request Parameters: None

    Request Body: None

    Note: The download count is affected by modifications to the transfer, such as a recalled package.

    Response Attributes

    Parameter Name Type Required/Optional Description
    archived boolean optional Package is archived
    completed_at ISO data format optional Time package notification completed
    complete boolean optional Package is complete
    deleted boolean optional Package is deleted
    dropbox_id string optional Dropbox ID
    embed[]=message boolean optional Message is embedded
    embed[]=node boolean optional Node server is embedded
    embed[]=organization boolean optional Organization is embedded
    embed[]=workspace boolean optional Workspace is embedded
    expired boolean optional Package is expired
    failed boolean optional Package failed
    name string required Package name
    read boolean optional Package has been read
    received boolean optional Package has been received
    sent_at ISO date format optional Date and time package sent
    sent boolean optional Package sent
    size unsigned integer optional Package size
    workspace_id string required Workspace ID
    Attribute Name Type Required/Optional Description
    active boolean optional Active download
    failed boolean optional Failed download
    full boolean optional Corresponds to the Download All button in Files UI; tags a transfer as a full download for Aspera files. Does not guarantee that all files in the package will transfer. Tracks whether all users have downloaded this package and counts how many full download counts are in a package.
    package_id string required Package ID
    partial boolean optional Partial download
    user_id string required User ID for download

    Success Response: 200 OK

    Update package transfers

    POST /packages/123/increment_transfers_expected

    This method updates the total number of transfers for a package by adding an additional transfer count to the previously requested number of transfers.

    The previous state of the package (success or fail) is now reset, with the exception of any current (open) transfers.

    Request Parameters:

    Attribute Name Type Required/Optional Description
    previous_transfers_expected unsigned integer required The value of the transfers_expected attribute returned for the GET /packages method
    count unsigned integer optional Number of expected transfers

    Note: If you recall a package for editing, this will affect the value for the previous_transfers_expected parameter.

    Example Request Body:

    {
      "previous_transfers_expected": 3,
      "count": 2
    }

    Success Response:

    200 OK

    Example Response:

    {
      "transfers_expected": 5
    }

    Note: The transfers_expected attribute is the sum of previous_transfers_expected and count.

    Error Response Codes:

    409 Conflict - Indicates that the previous_transfers_expected value submitted in the request is wrong. The transfers_expected attribute returned in the response contains the value which should have been submitted with the previous_transfers_expected parameter.

    Example Error Response:

    {
      "transfers_expected": 4
    }

    Troubleshooting: You can retry the request with the returned value for transfers_expected, or--if you do not get any response --you can either call GET /packages/{id} to get the updated value of transfers_expected or simply resend the failed request.

    Send or recall a package

    PUT /packages/{id}

    This method allows the user to send a package or recall a package so it can be edited.

    Sending packages: A package can be marked as “sent” at any point during or after the transfer. This finalizes the package and prevents it from being modified further. The recipients will not receive the package until it is marked as “sent” and all expected uploads (“transfers expected”) are complete. Email notifications are sent after transfer completion.

    Parameters: Set sent” set to “true”. Set “transfers_expected” to the desired value (integer). Files needs this value to determine when the package upload has completed.

    Attributes: The recalled_at attribute is automatically set to the current timestamp.

    Recalling packages: Recalling a package allows you to edit package contents. Email notifications are sent after transfer completion.

    Parameters: Set “draft” to “true”. To save the recalled package (lock it for further editing) after editing, set “draft” to “false”. Email notifications are sent after retransfer completion; the type of notification differs according to a number of factors, including whether the recipient is pre-existing or new.

    Request Parameters:

    Attribute Name Type Required/Optional Description
    draft required boolean Package is in draft form, which means that it is in an "unsent" state. If the value is true true the package is recalled, if false, the package is sent.
    sent optional, default is false boolean Package is sent. If this parameter is set this to true, the draft package and its message are sent to the recipients. Value cannot be changed from true once the package has been sent.
    package_sent required boolean If true, package is out for transfer. Specific to user who sends the package; package contents become read-only. If set to false, the package is recalled and can be edited.
    transfers_expected required unsigned integer Number of desired transfers

    Example Request Body:

    The following example is a request to send a package.

    PUT /packages/123

    {
      "sent": true,
      "transfers_expected": 3
    }

    Success Response Codes:

    204 No Content - indicates that the server has accepted your changes.

    Response Attributes

    The following are the only response attributes returned with a recalled package.

    Attribute Name Type Required/Optional Description
    name string required Package name
    size unsigned integer optional Package size
    sender string optional Package sender
    created_at ISO date format optional Date and time package created
    sent boolean optional Package sent
    delete_after_download boolean optional Delete package after download
    delete_package_content_after_download_duration boolean required, if delete_after_download is set to true Interval after download before package content is deleted
    deleted boolean optional Package is deleted
    deleted_after_download required boolean Package deleted after download
    deleted_at ISO date format optional Date and time package deleted
    deleted_by_admin boolean optional Package deleted by admin
    deleted_by_user_id boolean optional Package deleted by user ID
    expiration_reason string optional Reason for package expiration
    expired boolean optional Package is expired
    expired_at ISO date format optional Date and time package expired
    content_expires_at ISO date format optional Date and time package expires

    Note: The following information identifies the status of a package returned in the response:

    • Draft package (not yet sent) - “sent” is set to “false” and “draft” is set to “true”
    • Sent package - “sent” is set to “true” and “draft” is set to “false”
    • Recalled package - “sent” is set to “true” and “draft” is set to “true”

    Example Request:

    Send a package notification (create and send a message about a package after the upload completes):

    PUT /api/v1/packages/1xaEzw

    Request Body:

    {
      "sent": true,
      "transfers_expected": 3
    }
    
    

    Example Response: 204 No Content

    {
      "id":"1xaEzw",
      "created_at":"2014-04-15T18:51:32.137Z",
      "sender":{
        "id":"2",
        "name":"Jason Erlich",
        "email":"jason@asperasoft.com",
        "type" :"user"
      },
      "recipients": [{
        "type":"user",
        "id":"3",
        "name":"Jimmy Song",
        "email":"jimmy@asperasoft.com"
      }],
      "name":"Vacation",
      "sent":true,
      "received":false,
      "archived":false,
      "read":false,
      "complete":true,
      "failed":false
      "message_id":"37"
      "size":10245312,
      "file_count":207,
      "full_download_count": 3,
      "partial_download_count": 2,
      "failed_download_count": 0,
      "active_download_count": 3,
    }
    
    
      },
      {
        "package_id": "1xaEzw",
        "user_id": "1XrL",
        "partial": 5,
        "full": 0,
        "failed": 3,
        "active": 92182
      }
    ]

    Delete package

    DELETE /packages/{id}
    This method deletes a package with a particular ID. Package doesn’t actually delete package from system, just marks them as deleted for filtering.

    Success Response: 204 No Content

Video player

Video

×

Reset your Password Password resets are handled on the Support Site

×