Skip to content
This repository


Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP

Single-file HTTP client for NodeJS. With multipart support.

branch: master

Fetching latest commit…


Cannot retrieve the latest commit at this time

Octocat-spinner-32 bin
Octocat-spinner-32 lib
Octocat-spinner-32 test
Octocat-spinner-32 .gitignore
Octocat-spinner-32 package.json


Async HTTP client for NodeJS. Supports HTTPS, basic authentication, proxied requests, multipart form uploads and gzip/deflate compression. Really simple stuff, around ~250 lines of code.


var client = require('needle');

client.get(url, [options], callback);, data, [options], callback);
client.put(url, data, [options], callback);
client.delete(url, [options], callback);

Callback receives three arguments: (error, response, body)


  • timeout: Returns error if response takes more than X. Defaults to 10000 (10 secs).
  • compressed: Whether to ask for a deflated or gzipped response or not. Defaults to false.
  • parse: Whether to parse XML or JSON response bodies automagically. Defaults to true.
  • multipart: Enables multipart/form-data encoding. Defaults to false.
  • username: For HTTP basic auth.
  • password: For HTTP basic auth. Requires username to be passed, obviously.
  • agent: Uses an http.Agent of your choice, instead of the global (default) one.
  • proxy: Sends request via HTTP proxy. Eg. proxy: ''


Simple GET.

client.get('', function(err, resp, body){

  console.log("Got status code: " + resp.statusCode);


You can also skip the 'http://' part if you want, by the way.

HTTPS + querystring

client.get('', function(err, resp, body){

  // boom! works.


GET with options

var options = {
  username: 'you',
  password: 'secret',
  compressed: true,
  timeout: false,
  headers: {
    'X-Secret-Header': "Even more secret text"

client.get('', options, function(err, resp, body){

  // used HTTP auth


GET through proxy

client.get('', { proxy: 'http://localhost:1234' }, function(err, resp, body){

  // request passed through proxy



var data = {
  foo: 'bar',
  nested: {
    params: {
      are: {
        also: 'supported'
}'', data, function(err, resp, body){

  // if you don't pass any data, needle will throw an exception.


Multipart POST: passing file path

var data = {
  foo: bar,
  image: { file: '/home/tomas/linux.png', content_type: 'image/png' }

var options = {
  multipart: true,
  timeout: 5000
}'', data, options, function(err, resp, body){

  // in this case, if the request takes more than 5 seconds
  // the callback will return a [Socket closed] error


Multipart POST 2: passing data buffer

var buffer = fs.readFileSync('/path/to/');
var data = {
  zip_file: { buffer: buffer, filename: '', content_type: 'application/octet-stream' },
}'', data, {multipart: true}, function(err, resp, body){

  // if you see, when using buffers we need to pass the filename for the multipart body.
  // you can also pass a filename when using the file path method, in case you want to override
  // the default filename.



Written by Tomás Pollak, with the help of contributors.


(c) 2012 Fork Ltd. Licensed under the MIT license.

Something went wrong with that request. Please try again.