JavaScript Client API Reference Slack

Initialize Minio Client object.

Minio

var Minio = require('minio')

var minioClient = new Minio.Client({
    endPoint: 'play.minio.io',
    port: 9000,
    secure: true,
    accessKey: 'Q3AM3UQ867SPQQA43P2F',
    secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
});

AWS S3

var Minio = require('minio')

var s3Client = new Minio.Client({
    endPoint:  's3.amazonaws.com',
    accessKey: 'YOUR-ACCESSKEYID',
    secretKey: 'YOUR-SECRETACCESSKEY'
})
Bucket operations Object operations Presigned operations Bucket Policy & Notification operations
makeBucket getObject presignedGetObject getBucketNotification
listBuckets getPartialObject presignedPutObject setBucketNotification
bucketExists fGetObject presignedPostPolicy removeAllBucketNotification
removeBucket putObject getBucketPolicy
listObjects fPutObject setBucketPolicy
listObjectsV2 copyObject listenBucketNotification
listIncompleteUploads statObject
removeObject
removeIncompleteUpload

1. Constructor

new Minio.Client ({endPoint, port, secure, accessKey, secretKey})

new Minio.Client ({endPoint, port, secure, accessKey, secretKey})
Initializes a new client object.

Parameters

Param Type Description
endPoint string endPoint is a host name or an IP address.
port number TCP/IP port number. This input is optional. Default value set to 80 for HTTP and 443 for HTTPs.
accessKey string accessKey is like user-id that uniquely identifies your account.
secretKey string secretKey is the password to your account.
secure bool If set to true, https is used instead of http. Default is true.
region string Set this value to override auto bucket region discovery. (Optional)

Example

Create client for Minio

var Minio = require('minio')

var minioClient = new Minio.Client({
    endPoint: 'play.minio.io',
    port: 9000,
    secure: true,
    accessKey: 'Q3AM3UQ867SPQQA43P2F',
    secretKey: 'zuf+tfteSlswRu7BJ86wekitnifILbZam1KYY3TG'
});

Create client for AWS S3

var Minio = require('minio')

var s3Client = new Minio.Client({
    endPoint:  's3.amazonaws.com',
    accessKey: 'YOUR-ACCESSKEYID',
    secretKey: 'YOUR-SECRETACCESSKEY'
})

2. Bucket operations

makeBucket(bucketName, region, callback)

Creates a new bucket.

Parameters

Param Type Description
bucketName string Name of the bucket.
region string Default value is us-east-1 Region where the bucket is created. Valid values are listed below:
us-east-1
us-west-1
us-west-2
eu-west-1
eu-central-1
ap-southeast-1
ap-northeast-1
ap-southeast-2
sa-east-1
cn-north-1
callback(err) function Callback function with err as the error argument. err is null if the bucket is successfully created.

Example

minioClient.makeBucket('mybucket', 'us-east-1', function(err) {
  if (err) return console.log('Error creating bucket.', err)
  console.log('Bucket created successfully in "us-east-1".')
})

listBuckets(callback)

Lists all buckets.

Parameters

Param Type Description
callback(err, bucketStream) function Callback function with error as the first argument. bucketStream is the stream emitting bucket information.

bucketStream emits Object with the format:-

Param Type Description
bucket.name string bucket name
bucket.creationDate Date date when bucket was created.

Example

minioClient.listBuckets(function(err, buckets) {
  if (err) return console.log(err)
  console.log('buckets :', buckets)
})

bucketExists(bucketName, callback)

Checks if a bucket exists.

Parameters

Param Type Description
bucketName string Name of the bucket.
callback(err) function err is null if the bucket exists. err.code is NoSuchBucket in case the bucket does not exist.

Example

minioClient.bucketExists('mybucket', function(err) {
  if (err) {
     if (err.code == 'NoSuchBucket') return console.log("bucket does not exist.")
     return console.log(err)
  }
  // if err is null it indicates that the bucket exists.
  console.log('Bucket exists.')
})

removeBucket(bucketName, callback)

Removes a bucket.

Parameters

Param Type Description
bucketName string Name of the bucket.
callback(err) function err is null if the bucket is removed successfully.

Example

minioClient.removeBucket('mybucket', function(err) {
  if (err) return console.log('unable to remove bucket.')
  console.log('Bucket removed successfully.')
})

listObjects(bucketName, prefix, recursive)

Lists all objects in a bucket.

Parameters

Param Type Description
bucketName string Name of the bucket.
prefix string The prefix of the objects that should be listed (optional, default '').
recursive bool true indicates recursive style listing and false indicates directory style listing delimited by '/'. (optional, default false).

Return Value

Param Type Description
stream Stream Stream emitting the objects in the bucket.

The object is of the format:

Param Type Description
obj.key string name of the object.
obj.size number size of the object.
obj.etag string etag of the object.
obj.lastModified Date modified time stamp.

Example

var stream = minioClient.listObjects('mybucket','', true)
stream.on('data', function(obj) { console.log(obj) } )
stream.on('error', function(err) { console.log(err) } )

listObjectsV2(bucketName, prefix, recursive)

Lists all objects in a bucket using S3 listing objects V2 API

Parameters

Param Type Description
bucketName string Name of the bucket.
prefix string The prefix of the objects that should be listed (optional, default '').
recursive bool true indicates recursive style listing and false indicates directory style listing delimited by '/'. (optional, default false).

Return Value

Param Type Description
stream Stream Stream emitting the objects in the bucket.

The object is of the format:

Param Type Description
obj.key string name of the object.
obj.size number size of the object.
obj.etag string etag of the object.
obj.lastModified Date modified time stamp.

Example

var stream = minioClient.listObjectsV2('mybucket','', true)
stream.on('data', function(obj) { console.log(obj) } )
stream.on('error', function(err) { console.log(err) } )

listIncompleteUploads(bucketName, prefix, recursive)

Lists partially uploaded objects in a bucket.

Parameters

Param Type Description
bucketname string Name of the bucket.
prefix string Prefix of the object names that are partially uploaded. (optional, default '')
recursive bool true indicates recursive style listing and false indicates directory style listing delimited by '/'. (optional, default false).

Return Value

Param Type Description
stream Stream Emits objects of the format listed below:
Param Type Description
part.key string name of the object.
part.uploadId string upload ID of the object.
part.size Integer size of the partially uploaded object.

Example

var Stream = minioClient.listIncompleteUploads('mybucket', '', true)
Stream.on('data', function(obj) {
  console.log(obj)
})
Stream.on('end', function() {
  console.log('End')
})
Stream.on('error', function(err) {
  console.log(err)
})

3. Object operations

getObject(bucketName, objectName, callback)

Downloads an object as a stream.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
callback(err, stream) function Callback is called with err in case of error. stream is the object content stream.

Example

var size = 0
minioClient.getObject('mybucket', 'photo.jpg', function(err, dataStream) {
  if (err) {
    return console.log(err)
  }
  dataStream.on('data', function(chunk) {
    size += chunk.length
  })
  dataStream.on('end', function() {
    console.log('End. Total size = ' + size)
  })
  dataStream.on('error', function(err) {
    console.log(err)
  })
})

getPartialObject(bucketName, objectName, offset, length, callback)

Downloads the specified range bytes of an object as a stream.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
offset number offset of the object from where the stream will start.
length number length of the object that will be read in the stream (optional, if not specified we read the rest of the file from the offset).
callback(err, stream) function Callback is called with err in case of error. stream is the object content stream.

Example

var size = 0
// reads 30 bytes from the offset 10.
minioClient.getPartialObject('mybucket', 'photo.jpg', 10, 30, function(err, dataStream) {
  if (err) {
    return console.log(err)
  }
  dataStream.on('data', function(chunk) {
    size += chunk.length
  })
  dataStream.on('end', function() {
    console.log('End. Total size = ' + size)
  })
  dataStream.on('error', function(err) {
    console.log(err)
  })
})

fGetObject(bucketName, objectName, filePath, callback)

Downloads and saves the object as a file in the local filesystem.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
filePath string Path on the local filesystem to which the object data will be written.
callback(err) function Callback is called with err in case of error.

Example

var size = 0
minioClient.fGetObject('mybucket', 'photo.jpg', '/tmp/photo.jpg', function(err) {
  if (err) {
    return console.log(err)
  }
  console.log('success')
})

putObject(bucketName, objectName, stream, size, contentType, callback)

Uploads an object from a stream/Buffer.

From a stream

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
stream Stream Readable stream.
size number Size of the object (optional).
contentType string Content-Type of the object (optional, default application/octet-stream).
callback(err, etag) function Non-null err indicates error, etag string is the etag of the object uploaded.

Example

The maximum size of a single object is limited to 5TB. putObject transparently uploads objects larger than 5MiB in multiple parts. This allows failed uploads to resume safely by only uploading the missing parts. Uploaded data is carefully verified using MD5SUM signatures.

var Fs = require('fs')
var file = '/tmp/40mbfile'
var fileStream = Fs.createReadStream(file)
var fileStat = Fs.stat(file, function(err, stats) {
  if (err) {
    return console.log(err)
  }
  minioClient.putObject('mybucket', '40mbfile', fileStream, stats.size, function(err, etag) {
    return console.log(err, etag) // err should be null
  })
})
From a "Buffer" or a "string"

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
string or Buffer Stream or Buffer Readable stream.
contentType string Content-Type of the object (optional, default application/octet-stream).
callback(err, etag) function Non-null err indicates error, etag string is the etag of the object uploaded.

Example

var buffer = 'Hello World'
minioClient.putObject('mybucket', 'hello-file', buffer, function(err, etag) {
  return console.log(err, etag) // err should be null
})

fPutObject(bucketName, objectName, filePath, contentType, callback)

Uploads contents from a file to objectName.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
filePath string Path of the file to be uploaded.
contentType string Content-Type of the object.
callback(err, etag) function Non-null err indicates error, etag string is the etag of the object uploaded.

Example

The maximum size of a single object is limited to 5TB. fPutObject transparently uploads objects larger than 5MiB in multiple parts. This allows failed uploads to resume safely by only uploading the missing parts. Uploaded data is carefully verified using MD5SUM signatures.

var file = '/tmp/40mbfile'
minioClient.fPutObject('mybucket', '40mbfile', file, 'application/octet-stream', function(err, etag) {
  return console.log(err, etag) // err should be null
})

copyObject(bucketName, objectName, sourceObject, conditions, callback)

Copy a source object into a new object in the specied bucket.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
sourceObject string Path of the file to be copied.
conditions CopyConditions Conditions to be satisfied before allowing object copy.
callback(err, {etag, lastModified}) function Non-null err indicates error, etag string and lastModified Date are the etag and the last modified date of the object newly copied.

Example

var conds = new Minio.CopyConditions()
conds.setMatchETag('bd891862ea3e22c93ed53a098218791d')
minioClient.copyObject('mybucket', 'newobject', '/mybucket/srcobject', conds, function(e, data) {
  if (e) {
    return console.log(e)
  }
  console.log("Successfully copied the object:")
  console.log("etag = " + data.etag + ", lastModified = " + data.lastModified)
})

statObject(bucketName, objectName, callback)

Gets metadata of an object.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
callback(err, stat) function err is not null in case of error, stat contains the object information listed below:
Param Type Description
stat.size number size of the object.
stat.etag string etag of the object.
stat.contentType string Content-Type of the object.
stat.lastModified string Last Modified time stamp.

Example

minioClient.statObject('mybucket', 'photo.jpg', function(err, stat) {
  if (err) {
    return console.log(err)
  }
  console.log(stat)
})

removeObject(bucketName, objectName, callback)

Removes an object.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
callback(err) function Callback function is called with non null value in case of error.

Example

minioClient.removeObject('mybucket', 'photo.jpg', function(err) {
  if (err) {
    return console.log('Unable to remove object', err)
  }
  console.log('Removed the object')
})

removeIncompleteUpload(bucketName, objectName, callback)

Removes a partially uploaded object.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
callback(err) function Callback function is called with non null value in case of error.

Example

minioClient.removeIncompleteUpload('mybucket', 'photo.jpg', function(err) {
  if (err) {
    return console.log('Unable to remove incomplete object', err)
  }
  console.log('Incomplete object removed successfully.')
})

4. Presigned operations

Presigned URLs are generated for temporary download/upload access to private objects.

presignedGetObject(bucketName, objectName, expiry, cb)

Generates a presigned URL for HTTP GET operations. Browsers/Mobile clients may point to this URL to directly download objects even if the bucket is private. This presigned URL can have an associated expiration time in seconds after which the URL is no longer valid. The default expiry is set to 7 days.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
expiry number Expiry in seconds. Default expiry is set to 7 days.
callback(err, presignedUrl) function Callback function is called with non null err value in case of error. presignedUrl will be the URL using which the object can be downloaded using GET request.

Example

// expires in a day.
minioClient.presignedGetObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) {
  if (err) return console.log(err)
  console.log(presignedUrl)
})

presignedPutObject(bucketName, objectName, expiry, callback)

Generates a presigned URL for HTTP PUT operations. Browsers/Mobile clients may point to this URL to upload objects directly to a bucket even if it is private. This presigned URL can have an associated expiration time in seconds after which the URL is no longer valid. The default expiry is set to 7 days.

Parameters

Param Type Description
bucketName string Name of the bucket.
objectName string Name of the object.
expiry number Expiry in seconds. Default expiry is set to 7 days.
callback(err, presignedUrl) function Callback function is called with non null err value in case of error. presignedUrl will be the URL using which the object can be uploaded using PUT request.

Example

// expires in a day.
minioClient.presignedPutObject('mybucket', 'hello.txt', 24*60*60, function(err, presignedUrl) {
  if (err) return console.log(err)
  console.log(presignedUrl)
})

presignedPostPolicy(policy, callback)

Allows setting policy conditions to a presigned URL for POST operations. Policies such as bucket name to receive object uploads, key name prefixes, expiry policy may be set.

Parameters

Param Type Description
policy object Policy object created by minioClient.newPostPolicy()
callback(err, postURL, formData) function Callback function is called with non null err value in case of error. postURL will be the URL using which the object can be uploaded using POST request. formData is the object having key/value pairs for the Form data of POST body.

Create policy:

var policy = minioClient.newPostPolicy()

Apply upload policy restrictions:

// Policy restricted only for bucket 'mybucket'.
policy.setBucket('mybucket')

// Policy restricted only for hello.txt object.
policy.setKey('hello.txt')

or

// Policy restricted for incoming objects with keyPrefix.
policy.setKeyStartsWith('keyPrefix')

var expires = new Date
expires.setSeconds(24 * 60 * 60 * 10)
// Policy expires in 10 days.
policy.setExpires(expires)

// Only allow 'text'.
policy.setContentType('text/plain')

// Only allow content size in range 1KB to 1MB.
policy.setContentLengthRange(1024, 1024*1024)

POST your content from the browser using superagent:

minioClient.presignedPostPolicy(policy, function(err, postURL, formData) {
  if (err) return console.log(err)

  var req = superagent.post(postURL)
  _.each(formData, function(value, key) {
    req.field(key, value)
  })

  // file contents.
  req.attach('file', '/path/to/hello.txt', 'hello.txt')

  req.end(function(err, res) {
    if (err) {
      return console.log(err.toString())
    }
    console.log('Upload successful.')
  })
})

5. Bucket Policy & Notification operations

Buckets are configured to trigger notifications on specified types of events and paths filters.

getBucketNotification(bucketName, cb)

Fetch the notification configuration stored in the S3 provider and that belongs to the specified bucket name.

Parameters

Param Type Description
bucketName string Name of the bucket.
callback(err, bucketNotificationConfig) function Callback function is called with non null err value in case of error. bucketNotificationConfig will be the object that carries all notification configurations associated to bucketName.

Example

minioClient.getBucketNotification('mybucket', function(err, bucketNotificationConfig) {
  if (err) return console.log(err)
  console.log(bucketNotificationConfig)
})

setBucketNotification(bucketName, bucketNotificationConfig, callback)

Upload a user-created notification configuration and associate it to the specified bucket name.

Parameters

Param Type Description
bucketName string Name of the bucket.
bucketNotificationConfig BucketNotification Javascript object that carries the notification configuration.
callback(err) function Callback function is called with non null err value in case of error.

Example

// Create a new notification object
var bucketNotification = new Notify.BucketNotification();

// Setup a new topic configuration
var arn = Notify.newARN('aws', 'sns', 'us-west-2', '408065449417', 'TestTopic')
var topic = new Notify.TopicConfig(arn)
topic.addFilterSuffix('.jpg')
topic.addFilterPrefix('myphotos/')
topic.addEvent(Notify.ObjectReducedRedundancyLostObject)
topic.addEvent(Notify.ObjectCreatedAll)

// Add the topic to the overall notification object
bucketNotification.addTopicConfiguration(topic)

minioClient.setBucketNotification('mybucket', bucketNotification, function(err) {
  if (err) return console.log(err)
  console.log('Success')
})

removeAllBucketNotification(bucketName, callback)

Remove the bucket notification configuration associated to the specified bucket.

Parameters

Param Type Description
bucketName string Name of the bucket
callback(err) function Callback function is called with non null err value in case of error.
minioClient.removeAllBucketNotification('my-bucketname', function(e) {
  if (e) {
    return console.log(e)
  }
  console.log("True")
})

listenBucketNotification(bucketName, prefix, suffix, events)

Listen for notifications on a bucket. Additionally one can provider
filters for prefix, suffix and events. There is no prior set bucket notification
needed to use this API. This is an Minio extension API where unique identifiers
are regitered and unregistered by the server automatically based on incoming requests.

Returns an EventEmitter, which will emit a notification event carrying the record.

To stop listening, call .stop() on the returned EventEmitter.

Parameters

Param Type Description
bucketName string Name of the bucket
prefix string Object key prefix to filter notifications for.
suffix string Object key suffix to filter notifications for.
events Array Enables notifications for specific event types.

See here for a full example.

var listener = minioClient.listenBucketNotification('my-bucketname', 'photos/', '.jpg', ['s3:ObjectCreated:*'])
listener.on('notification', function(record) {
  // For example: 's3:ObjectCreated:Put event occurred (2016-08-23T18:26:07.214Z)'
  console.log('%s event occurred (%s)', record.eventName, record.eventTime)
  listener.stop()
})

getBucketPolicy(bucketName, objectPrefix, callback)

Get the bucket policy associated with the specified bucket. If objectPrefix
is not empty, the bucket policy will be filtered based on object permissions
as well.

Parameters

Param Type Description
bucketName string Name of the bucket
objectPrefix string Prefix of objects in the bucket with which to filter permissions off of. Use '' for entire bucket.
callback(err, policy) function Callback function is called with non null err value in case of error. policy will be the string representation of the bucket policy (minio.Policy.NONE, minio.Policy.READONLY, minio.Policy.WRITEONLY, or minio.Policy.READWRITE).
// Retrieve bucket policy of 'my-bucketname' that applies to all objects that
// start with 'img-'.
minioClient.getBucketPolicy('my-bucketname', 'img-', function(err, policy) {
  if (err) throw err

  console.log(`Bucket policy: ${policy}`)
})

setBucketPolicy(bucketName, objectPrefix, bucketPolicy, callback)

Set the bucket policy associated with the specified bucket. If objectPrefix
is not empty, the bucket policy will only be assigned to objects that fit the
given prefix.

Parameters

Param Type Description
bucketName string Name of the bucket
objectPrefix string Prefix of objects in the bucket to modify permissions of. Use '' for entire bucket.
bucketPolicy string The bucket policy. This can be: minio.Policy.NONE, minio.Policy.READONLY, minio.Policy.WRITEONLY, or minio.Policy.READWRITE.
callback(err) function Callback function is called with non null err value in case of error.
// Set the bucket policy of `my-bucketname` to `readonly` (only allow retrieval),
// but only for objects that start with 'img-'.
minioClient.setBucketPolicy('my-bucketname', 'img-', minio.Policy.READONLY, function(err) {
  if (err) throw err

  console.log('Set bucket policy to \'readonly\'.')
})

6. Explore Further