Nirvanix Logo

Nirvanix Web Services

Ruby Logo Ruby Library for Nirvanix Web Services API

Download the library with RubyGems

sudo gem i nvx-sds

Download the library from the svn repository

svn co svn:// nvx-sds

The latest release and support is always available at Nirvanix Developer Center.

Getting started

After the gems library is installed you will need to:

require 'nvx_sds'

Creating a Session

Most operations using this library will use go through the Session object. The session holds authentication and persistent connection information for the Nirvanix account.

Creating a session can be done using:


To get an account go to and sign up. This will generate a new account and application key that you can use the pass to the session initialize method.

When you are finished with a session always be sure to log that session out to invalidate the active session token.


Uploading a file

To upload a file you will need to create a session and a HttpUpload object. The call takes a local file and streams it to the remote server. Below is an example of an upload:


remote_file = "TestUpload.txt"
remote_path = "/"
overwrite = true
# Get a file in the current directory
local_file = File.expand_path(File.join(File.dirname(__FILE__), '.')) + remote_file

HttpUpload.UploadFile(remote_path, remote_file, local_file, overwrite, session.account_login)

General File operations

There are many different file operations that are available once a file has been uploaded through the API. To get to these operations you can retrieve the root folder. The example below shows this and prints out each folder name.

root_folder = session.GetRootFolder(1, 500, 0, true)
root_folder.folders.each do |folder|

The parameters are:

The maximum number of items reutrned in a single page is 500

The folder sort codes are:

LoadChildren must be called to handle paging, due to memory concerns we didnt want to return too many items in one request, doing so could cause problems for people using shared servers with memory caps or other limitations.

After getting a folder object you can copy, move, rename and delete files or folders you can read more in the Folder RubyDoc entry.

File operations can be completed in a similar manner using the NVXFile object.

Accounting Operations

The session object lets you get or set account information about the account you used to create the session. This is contact information and the username. The session object can also be used to retrieve a MasterAccount object that will give you the ability to create and delete child accounts, setting and getting account notes and impersonation of children under that master account.

The master account has a unique set of children and file system per application key but only one set of account contact information. This means each application key is a unique space under the master account. You can read more about this relationship in the official Nirvanix API Documentation.

As a master account you will not need the password of the child account only the username you wish to impersonate.


There are two transcoding namespaces Audio and Video. The transcode methods let you convert files from one format into another. in the video namespace there is also the ability to extract frames, this is useful for pulling out a certain number of frames from a video or generating thumbnails or preview images.


You can search in three primary ways, file system, Metadata and Tags. Each search method can be called from the session object and returns an array of SearchItem objects.

Unit Tests

The unit test files show almost all functionality in the library. You can execute them yourself by modifying the testconfig.rb file in the tests directory under the Gem. You will need an application key, master account username/password and a child account username/password to run the tests.


There is room for improvement in the error and exception handling. This will be coming in the next release.