Module Summary

File size minified:
Browser Support:
by Toby Ho on 2/2/2014

SuperAgent is a light-weight, flexible and expressive Ajax library.

Note: SuperAgent has been loaded on this page! You can open up the dev console to try out the examples. The Github APIs support CORS and so you can make Ajax requests to them directly from here.

The Basics

All of the examples in SuperAgent's documentation alias SuperAgent to request, so I will follow suit. If you are using npm or component

var request = require('superagent');

If you are using it standalone

var request = window.superagent;

Now, to make a simple GET request

var url = '';
request.get(url, function(response){
  console.log('Response ok:', response.ok);
  console.log('Response text:', response.text);

The response object is what you get back from the callback.

Response Object

The response object contains everything you'd need to know about what came back, including:

Having visited the response object, now let's get into the meat of the library - the request object.

Request Object

Let's step back and look at the request object. A request object is returned by any call to the request function or one of its convinience methods - consisting of "get", "post", and other HTTP verbs.

var req = request.get(url);

If you don't supply a callback function, the request will not be sent out until you called the end() method later

  console.log('Got response', resp.text);

There are a number of convinience methods too, let's start with query parameters.

Query Parameters

The query() method sets query parameters on the URL of the request.

req.query({id: 8});

or set it in string format


You can call it multiple times and it will combine all of the parameters. This makes easy to set parameters conditionally - which is harder to do in jQuery:

if (search.category){
  req.query({category: search.category});
if (search.searchTerm){
  req.query({searchTerm: search.searchTerm});

Method Chaining

In the tradition of jQuery, all methods on the request object are chainable (they return back the request object) to allow for a sort of "fluent syntax".

  .query({id: 8})
    console.log('Got post', resp.body)

Sending Parameters

Setting parameters on POST or PUT requests works similarly to query parameters, except you use the send() method to do it:

  .send({name: 'tj', pet: 'tobi'})
    // ...

By default, SuperAgent encodes the request body in JSON, which means in this case, you would see a request like

POST /submit HTTP/1.1
Connection: keep-alive
Content-Length: 26
Content-Type: application/json


You can alternatively use form encoding to mimic submitting an HTML form

  .send({name: 'tj', pet: 'tobi'})
    // ...

then the request would be like

POST /submit HTTP/1.1
Connection: keep-alive
Content-Length: 16
Content-Type: application/x-www-form-urlencoded


Setting Headers

Setting a header is done with the set() method

req.set('Content-Type', 'application/json');

but if you are setting the Content-Type, there's shorthand for that


there's also a shorthand for setting the Accept header


Aborting and Timeouts

You can abort an in-flight request with the abort() method. Or more conveniently, the timeout(ms) method will abort a request after the specified number of milliseconds has passed without getting a response back.

Server-Side Capabilities

SuperAgent also works on the server-side. In addition, it has some server-side specific features such as

Learning More

To learn more about SuperAgent, the best way is to check out the docs.

comments powered by Disqus