Search Results


The upload API call provides a simple mechanism for remotely uploading files to the CloudShark appliance. The upload call returns the associated capture session which can then be used to link directly to the decode session. The capture session is returned in JSON format.

Optional parameters include filename, tags, comments and an tls keylog file. If filename is not specified, the file will be named after the browser’s User Agent and a unique timestamp. The additional_tags is a comma separated list of tags the file will be saved with. File comments may also be added at upload time by sending the comments parameter. See the curl examples below for a demonstration. NOTE that when using the PUT method, optional parameters must be appended to the URL rather than being specified as multipart/form-encoded data.

POST Usage

POST /api/v1/<token>/upload

Required parameters: the upload method requires either a url or file parameter. The form will either indicate url=http://some-host/some-file.cap or file= File contents must be encoded as multipart/form-data.

PUT Usage

Support for the PUT method was introduced in CloudShark 1.5.

PUT /api/v1/<token>/upload

Upload with PUT supports receiving a binary stream of data that is the contents of the file.

The optional keylog parameter cannot be specified when using the PUT method.


CloudShark returns the result of the upload call in JSON. It is an object representing the newly created capture session, or containing any errors that prevented the file from being imported.


Here is the full HTTP response with headers.

HTTP/1.1 200 OK
Server: nginx/0.9.4
Date: Tue, 16 Aug 2011 14:48:34 GMT
Content-Type: text/javascript; charset=utf-8
Transfer-Encoding: chunked
Connection: keep-alive


The session id can be used to build a URL directly to the decode session.

If the upload fails for any reason, the HTTP response may be either 4xx or 5xx. In this case the JSON body will contain the HTTP status along with an array of exceptions explaining the failure.

{"status":404,"exceptions":["API Token is missing or invalid"]}

Additional Parameters

Optional parameters can be set at the time of upload via the API:

  • additional_tags - a comma-separated list of tags to apply to the capture file
  • filename - specify the filename of the capture in CloudShark
  • comments - file-level comments
  • keylog - tls keylog file


Below are some examples of calling the upload API in a few different languages. We are big fans of Ruby here at CloudShark, but we wanted to show how this can be implemented a variety of ways.


Curl can be used to upload local files and files available at specific URLs with a CloudShark API token. One of the nice things about curl is that it will do all the form encoding for you with the handy -F flag. A few simple examples are shown below.

Curl with a local file:

curl -F file=@filename.cap<api-key>/upload

Curl with a URL:

curl -F url=http://path/to/capture/file<api-key>/upload

Curl with a URL and HTTP authentication:

curl -F url=http://username:password@path/to/capture/file<api-key>/upload

Include additional tags and change the filename:

curl -F file=@filename.cap -F additional_tags=tag1,tag2,tag3 -F filename=new_filename.cap<api-key>/upload

Curl using POST and TLS Keylog file:

curl -F file=@filename.cap -F keylog=@keylogfile<api-key>/upload

Curl using PUT instead of POST:

curl --upload-file filename.cap<api-key>/upload

Curl using PUT and adding comments:

curl --upload-file filename.cap<api-key>/upload?comments=captured+from+NOC+23


Be careful to URL-encode all your parameter values when using curl. For example anything that includes spaces should be sent with + (plus-sign) instead. Also if specifying multiple URL parameters separated with the & sign, be sure to escape it so bash doesn’t interpret it as the end of the command.


While bash is not the best language to invoke a web API, it is possible to write simple scripts to upload files. Here is an example of using tcpdump to generate a capture file and then upload it to CloudShark.

# bash script to use CloudShark Token API

UPLOAD=traffic-`date +%F-%H%M%S`.cap

# -- generate a capture file using tcpdump
echo "Generate a capture file"
tcpdump -i eth0 -c 100 -w $UPLOAD

# -- build a curl command
JSONID=`curl -F "file=@$UPLOAD" -F "additional_tags=script" $CLOUDSHARKURL | python -mjson.tool | grep id`

if [ "$JSONID" != "" ]; then

   # -- find the CloudShark ID for this session
   ID=`echo $JSONID | sed 's/:/ /1' | awk -F" " '{ print $2 }'| sed 's/\"//g'`

   echo "Uploaded $UPLOAD to CloudShark"

   # -- show a URL using the capture session in CloudShark
   echo "Please visit https://cloudshark.myhost.example/captures/$ID"
   echo "Could not upload capture to CloudShark"


For Ruby, Net::HTTP can be used to generate a POST. There is also a multipart form gem ‘multipart-post’ that makes it easy to POST. You will need to install the ‘mulipart-post’ gem first.

gem install multipart-post

Here is a simple example uploading an existing capture file.

#!/usr/bin/env ruby

require 'rubygems'
require 'json'
require 'net/http/post/multipart'

cloudshark = ""
apikey = "6d4ca6e11916dfc64c4d98c0c9fcea72"

url = URI.parse('http://' + cloudshark + '/api/v1/' + apikey + '/upload/')

# -- upload traffic.cap"./traffic.cap") do |cap|
  req = url.path,
    "file" =>, "application/octet-stream", "traffic.cap")
  res = Net::HTTP.start(, url.port) do |http|

  puts "Received response #{res.body}"

  # -- parse the JSON response
  result = JSON.parse(res.body)

  # -- check for the session id
  if result.has_key? 'id'
    id = result["id"]
    puts "New capture uploaded with session id #{id}"
    puts "Access URL http://#{cloudshark}/captures/#{id}"
    puts "Capture file was not uploaded"


Windows PowerShell

Windows 8 users can natively capture packets using the netsh capture interface. With the Microsoft Message Analyzer tool, this proprietary format can be converted back into a pcap file and then uploaded using all native powershell cmdlets. With this one additional Microsoft download, a Windows 8 system is capable of pure packet capture and upload to CloudShark.

# CloudShark PowerShell Demo Script
# Free to distribute; Send us improvements and we'll credit and post!
# To use this script you must:
# (1) be in an Admin PowerShell
# (2) you must allow unsigned scripts: run
#     Set-ExecutionPolicy RemoteSigned
# (3) You must have Message Analyzer installed
# (Restart the Admin PowerShell after installing Message Analyzer
#     to load the New-PefTraceSession cmdlets)

# Set this to your CloudShark host
# Set this to your CloudShark upload API token

# Size of the capture file, in megabytes.

# Clean up any previous session data
If (Test-Path "C:\Users\$env:username\Desktop\OutFile.Cap"){
    Remove-Item "C:\Users\$env:username\Desktop\OutFile.Cap"

If (Test-Path "C:\Users\$env:username\Desktop\trace.etl"){
    Remove-Item "C:\Users\$env:username\Desktop\trace.etl"
netsh trace stop

# Start a new capture
netsh trace start capture=yes traceFile=C:\Users\$env:username\Desktop\trace.etl maxSize=$maxsize

$s = New-PefTraceSession -Path "C:\Users\$env:username\Desktop\OutFile.Cap" -SaveOnStop
$s | Add-PefMessageProvider -Provider "C:\Users\$env:username\AppData\Local\Temp\NetTraces\NetTrace.etl"
$s | Start-PefTraceSession

Invoke-RestMethod -uri http://$cloudshark/api/v1/$tok/upload -method PUT -inFile C:\Users\$env:username\Desktop\OutFile.Cap