SuperAgent
Lightweight progressive AJAX HTTP library for Node.js and browsers. SuperAgent provides a fluent chainable API for HTTP requests with built-in JSON/form parsing, file upload, query string serialization, response type detection, and retry support. Still widely used for API testing in Mocha/Chai stacks via supertest (HTTP testing against Express apps without a running server).
Score Breakdown
⚙ Agent Friendliness
🔒 Security
HTTPS enforced. Certificate validation on by default. Isomorphic design means browser and Node.js TLS behavior may differ — test both environments.
⚡ Reliability
Best When
Maintaining existing SuperAgent codebases or when supertest for Express API testing is the primary use case.
Avoid When
Starting a new HTTP client project — use Got, axios, or native fetch with better TypeScript and maintenance track records.
Use Cases
- • Test Express/Koa/Hapi API endpoints without a running server using supertest (SuperAgent-based test helper for HTTP testing)
- • Make cross-platform HTTP requests from both Node.js and browser with the same isomorphic SuperAgent code
- • Build HTTP clients with fluent method chaining — .get(url).query(params).set(header).then(handler) for readable request construction
- • Handle file uploads and multipart forms with SuperAgent's .attach() and .field() methods in agent file processing pipelines
- • Implement retries with .retry(count) for resilient HTTP requests in agent workflows against unreliable third-party APIs
Not For
- • New projects — axios and Got are more actively maintained with better TypeScript support; SuperAgent is legacy
- • High-performance HTTP at scale — use undici or Got for performance-critical Node.js HTTP; SuperAgent has more overhead
- • Edge/serverless environments — SuperAgent's isomorphic approach adds complexity; use native fetch with appropriate polyfills
Interface
Authentication
No built-in auth — HTTP client. Use .set('Authorization', 'Bearer token') for auth headers.
Pricing
SuperAgent is open source and free.
Agent Metadata
Known Gotchas
- ⚠ SuperAgent's .end() callback style is the old API — prefer .then() Promise style or async/await; .end() doesn't return a Promise
- ⚠ 4xx and 5xx responses throw ResponseError by default — use try/catch or .ok(res => res.status < 500) to customize error handling
- ⚠ supertest is a separate package built on SuperAgent for testing Express apps — install 'supertest', not 'superagent', for API testing
- ⚠ Multipart form data (.attach()) and JSON (.send(object)) can't be mixed in the same request — use one or the other; mixing silently uses multipart
- ⚠ .retry() retries on network errors but NOT on HTTP errors (4xx/5xx) by default — use .retry(3, (err, res) => res.status >= 500) for HTTP error retry
- ⚠ SuperAgent 8+ dropped legacy callback-based API and older Node.js support — verify minimum Node.js version when upgrading in existing projects
Alternatives
Full Evaluation Report
Detailed scoring breakdown, competitive positioning, security analysis, and improvement recommendations for SuperAgent.
Scores are editorial opinions as of 2026-03-06.