Guide · Open source

How to use superagent: install and send HTTP requests

Updated 2026-10-29 · written with AI from the project's own documentation and checked against our catalogue data

Superagent is a small JavaScript library for sending HTTP requests, such as fetching data from a web server or posting data to it. It works with the same API in Node.js and in the browser. This guide shows you how to install it, send a JSON request with custom headers, use the callback, promise and async/await styles, and extend requests with plugins.

superagentforwardemail/superagent · ★ 16.6k · MIT Install options & downloads

Quick start

1Check your Node.js version. Confirm you have Node.js v14.18.0 or newer before installing superagent.
2Install the package. Run npm install superagent or yarn add superagent in your project folder.
3Require superagent. In your Node.js file, load it with const superagent = require('superagent').
4Build a request. Chain .post() or .get(), then add .send() for a JSON body and .set() for headers.
5Choose a response style. Use .end() with a callback, .then() and .catch(), or async/await with try and catch.
6Add plugins if needed. Attach plugins such as superagent-no-cache with .use() on the requests that need them.

Install superagent with npm or yarn

Superagent is installed as a package. It requires Node.js v14.18.0 or newer. Run one of the install commands from your project folder.

npm: use the npm install command shown below.
yarn: use the yarn add command shown below.

npm install superagent
yarn add superagent

Send a JSON POST request in Node.js

Load superagent with require, then chain methods to describe the request. The .send() method sends a JSON body, .set() adds a header, and .end() sends the request and receives the result through a callback. The README example posts to /api/pet with a name and species.

.send({ ... }) sends a JSON post body.
.set('X-API-Key', 'foobar') adds a custom header.
.end((err, res) => ...) runs when the request finishes.

const superagent = require('superagent');

superagent
  .post('/api/pet')
  .send({ name: 'Manny', species: 'cat' })
  .set('X-API-Key', 'foobar')
  .set('accept', 'json')
  .end((err, res) => {
    // Calling the end function will send the request
  });

Use promises or async/await instead of callbacks

You can also use .then() and .catch() to handle the result, or an async function with try and catch. Choose whichever style fits your code. The README shows all three styles for the same kind of request.

then/catch: superagent.post('/api/pet').then(console.log).catch(console.error)
async/await: wrap the call in try and catch and use await superagent.post('/api/pet').

(async () => {
  try {
    const res = await superagent.post('/api/pet');
    console.log(res);
  } catch (err) {
    console.error(err);
  }
})();

Use superagent in the browser

For the browser, the README provides a minified build of about 50 KB (gzipped) that you can load with a script tag from jsDelivr or unpkg, or from the dist folder in the installed package. When loaded this way, superagent is exposed as window.superagent. If you use a bundler such as browserify, webpack or rollup, follow the same usage as the Node example.

The README recommends a polyfill for browsers that lack some features. It lists WeakRef and BigInt, which are not supported in some older browsers such as Opera 85 and iOS Safari 12.2-12.5.

Script tag: load superagent from jsDelivr or unpkg.
Bundler: use the same code as the Node section.

<script src="https://cdn.jsdelivr.net/npm/superagent"></script>

Extend requests with plugins

Superagent is designed to be extended through plugins. You attach a plugin to one request with .use(), so it only affects that request. The README example uses a prefix plugin and a no-cache plugin on a GET request with a query string.

The README lists existing plugins, such as superagent-mock for returning fixtures, superagent-cache for caching and superagent-throttle for throttling requests. The README asks plugin authors to name packages superagent-*.

.query({ ... }) adds a query string.
.use(plugin) applies a plugin to the current request only.

const nocache = require('superagent-no-cache');
const superagent = require('superagent');
const prefix = require('superagent-prefix')('/static');

superagent
  .get('/some-url')
  .query({ action: 'edit', city: 'London' })
  .use(prefix)
  .use(nocache)
  .end((err, res) => {
    // Do something
  });

Check supported platforms before you adopt it

The README lists Node v14.18.0 or newer as the minimum for Node. For browsers, it links to a .browserslistrc file that lists supported versions, which you can view with npx browserslist. If your project must run on older environments, check this list first.

The README also notes that breaking changes in past major versions were mostly in rarely used features and in stricter error handling. Read the GitHub releases page for the current changelog before upgrading.

Node: v14.18.0 or newer.
Browsers: versions listed in .browserslistrc.
Changelog: the GitHub releases page.

What people use it for

Posting a JSON object with a custom API key header to a web API.
Fetching data from a server with a query string using .query().
Using one HTTP client in both a Node.js back end and a browser front end.
Adding caching or path prefixes to specific requests with plugins.
Simulating API responses in tests with a plugin such as superagent-mock.

Frequently asked questions

How do I install superagent?

Run npm install superagent or yarn add superagent in your project folder. The README lists these two commands as the install methods.

What Node.js version does superagent need?

The README lists Node v14.18.0 or newer as the supported minimum. Older Node versions are not listed as supported.

Is superagent free to use?

The project is licensed under the MIT licence. The README does not state any pricing.

Can superagent run in the browser?

Yes. The README says it uses the same API in Node.js and browsers, and it provides a browser-ready build that you can load with a script tag or through a bundler.

How does superagent compare to axios or got?

The source lists axios, node-fetch, got and ky as comparable projects, but it does not compare features, sizes or performance with them. Test the options against your own needs.

How do I add a plugin to superagent?

Install a plugin package and attach it to a request with .use(). The plugin then affects only that request, as shown in the README example with superagent-no-cache.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

Superagent suits JavaScript developers who want one HTTP client API for Node.js and browsers, with JSON bodies, headers, plugins and several response styles. If you only need the built-in fetch API and want zero dependencies, or your environment is older than the listed minimums, consider another option.

Install options & downloads