httpbin 0.9.2

Docs

Docs & self-hosting

What httpbin is, how to call it, how to run it on your own infrastructure, and the recipes that cover most day-to-day testing.

What httpbin is

httpbin is an HTTP request and response service. You send a request to an endpoint and it echoes back what it received: method, headers, query arguments, form data, cookies, and origin. Nothing is stored between requests.

Use it when you need to:

  • Test an HTTP client or library without standing up a real server.
  • Confirm the exact headers, auth, or body your code sends.
  • Exercise a specific status code, redirect, or cookie flow.
  • Seed CI tests and examples with a stable public target.

If you only need a couple of endpoints, browse the catalog grouped by tag on endpoints.html, or send a request directly from the playground.

Base URL

Every endpoint is relative to the base URL:

base url 
https://httpbin.org

So /get is https://httpbin.org/get. When you self-host, replace the base with your own origin.

Run it locally

Run httpbin with Docker and point your clients at it:

bash 
docker run -p 80:80 kennethreitz/httpbin

The service is then reachable at http://localhost:80. If port 80 is taken, map another host port:

bash 
docker run -p 8080:80 kennethreitz/httpbin

With that mapping the base URL becomes http://localhost:8080.

Self-hosting: httpbin is stateless and runs as a single container, so your data never leaves your infra. Run it on a private network or CI runner when you need to send tokens, credentials, or payloads you would not send to a public service.

Getting started

Make one request with curl:

bash 
curl https://httpbin.org/get

You get a JSON document describing the request:

json 
{
  "args": {},
  "headers": {
    "Accept": "*/*",
    "Host": "httpbin.org",
    "User-Agent": "curl/8.4.0"
  },
  "origin": "203.0.113.7",
  "url": "https://httpbin.org/get"
}

Send a body next. This shows the same echo for a POST:

bash 
curl -X POST https://httpbin.org/post \
  -H "Content-Type: application/json" \
  -d '{"name": "alice"}'

In a browser, open any endpoint directly, for example https://httpbin.org/get?name=alice&age=30. To build and inspect a request without writing code, use the playground.

Recipes

Short, copyable examples for the tasks that come up most often.

Testing auth headers

Basic auth is verified against the credentials in the path. A correct pair returns authenticated: true:

bash 
curl -u user:pass https://httpbin.org/basic-auth/user/pass

Bearer tokens are echoed back so you can confirm the header your client sent:

bash 
curl -H "Authorization: Bearer $TOKEN" https://httpbin.org/bearer

See the Auth group for the full set.

Inspecting request headers

Send the headers you care about and read them back from the response:

bash 
curl -H "X-Debug: 1" -H "Accept: application/json" https://httpbin.org/headers

This verifies that a client, proxy, or framework sets exactly the headers you expect. More in the Request inspection group.

Returning a given status code

Print the response status without following or fetching a full body:

bash 
curl -i https://httpbin.org/status/418

Any code is accepted, so you can drive a specific error branch in your client:

bash 
curl -i -X DELETE https://httpbin.org/status/204

Full list on the Status codes group.

Generating dynamic data

Return a random UUID for fixtures and unique IDs:

bash 
curl https://httpbin.org/uuid

Return a fixed number of random bytes, for testing binary handling:

bash 
curl https://httpbin.org/bytes/16

Stream newline-delimited JSON for testing streaming parsers:

bash 
curl https://httpbin.org/stream/5

There are also /range and /drip for partial and delayed bodies. See Dynamic data.

Setting and reading cookies

Set a cookie; httpbin stores it in your cookie jar and redirects to the read endpoint:

bash 
curl -L -c cookies.txt "https://httpbin.org/cookies/set?session=abc123"

Send it back and confirm what the server received:

bash 
curl -b "session=abc123" https://httpbin.org/cookies

Use /cookies/delete to remove one. See the Cookies group.

Following redirects

Inspect the redirect chain by showing headers and not following:

bash 
curl -i https://httpbin.org/redirect/3

Follow it to the end to test your client's redirect handling:

bash 
curl -L https://httpbin.org/redirect/3

The Redirects group also covers absolute, relative, and to-redirect endpoints.

FAQ

Does httpbin store my requests?

No. It is stateless. Nothing is written between requests, and cookies only exist when you send them back yourself. There is no account, session, or history.

Is it safe to send real credentials?

Not to the public instance. Whoever runs the server sees the request, including any tokens or payloads you send. For anything sensitive, self-host it so your data never leaves your infra.

Are there rate limits?

The public instance is best-effort and meant for interactive testing and light loads. Treat it as shared infrastructure: avoid sustained or high-volume traffic, and run your own instance for CI, load tests, or production use.

Where do I go next?

Browse the full catalog on endpoints.html, or send a request and read the response in the playground.