Request Bins reference

Request Bins has two sides. Bin URLs on nnbin.net take requests from anyone and record them. The API at https://bins.nimbusnexus.net/v1 creates and manages bins and reads what they recorded, for your workspace only. This page covers both, then who may do what and each plan's limits. The overview explains the product, and the quickstart walks through it.

Bin URLs

What a bin URL answers

The 200 is the same for every outcome on purpose. A sender that gets an error may stop sending or switch its webhook off, and a different answer for a live bin would let anyone probe for bins. Whether a request was recorded is something the bin's owner reads in the API or the console, never the sender.

A 200 carries an X-Request-ID header, and the captured request's request_id holds the same value, so a sender's log line can be matched to what the bin recorded.

What a bin records

• Body: a body of any size is accepted. Its full size is counted in size_bytes; the first 1 MiB is passed on for storage, and the first 64 KiB of that is stored. truncated is true when the stored body is shorter than size_bytes. The body is stored as the bytes that arrived, never parsed or changed.
• Headers: in arrival order with duplicates kept, up to 256 of them; a name is cut at 256 characters and a value at 8,192. The values of Authorization, Proxy-Authorization, Cookie, Set-Cookie and X-API-Key are replaced with [redacted] before anything is stored. Every other header is kept as sent.
• Path: cut at 2,048 characters.
• Content type: the Content-Type header, as content_type.
• Source address: the address that sent the request, as source_ip.

Repeats

A request with the same method, path and body as one the bin already holds isn't stored again, even when its query string or headers differ. Instead, that request's seen_count goes up by one, and its received_at, expires_at and request_id move to the latest arrival, while its query string and headers stay those of the first arrival. Headers are left out of the match because a provider's retry carries a new signature and timestamp. A repeat counts toward the month's requests.

When nothing is recorded

The sender gets 200 in every case below. What the bin shows:

last_refused_summary shows the last refused request as METHOD /path, and last_refused_at when it came. Refused requests don't count toward the month.

Suspension

Two gates suspend a bin whose traffic looks like collection from strangers rather than a few known senders:

• Distinct senders: a bin heard from more distinct addresses than the plan allows: 50 on Free, 200 on Starter, 500 on Pro and 2,000 on Custom.
• Browser form posts: a request with a browser header (Origin, Referer, Sec-Fetch-Site or Sec-Fetch-Mode) and a form content type (application/x-www-form-urlencoded or multipart/form-data) is a browser form post. A bin that receives more of them than the plan allows (3 on Free, 5 on Starter and Pro, 10 on Custom), from at least three addresses, is suspended. browser_post_count, last_browser_form_origin and last_browser_form_at show what it has seen.

The request that trips a gate is recorded, and the ones after it aren't. A suspended bin answers 200 and records nothing, whatever its status. suspended_code says why:

Treat suspended_code as an open string and keep a default for a value you don't know; suspended_reason says the same in words. A bin can be suspended for several causes at once, and each is lifted on its own: settling a charge never lifts an abuse suspension, and lifting one never brings back a bin the plan no longer allows.

To report a bin URL that is being abused, write to [email protected] with the full URL. The page at https://nnbin.net/ says the same.

Browsers

Bin URLs send no CORS headers. A web page can send a bin a simple request, such as a form post, but can't read the answer, and a request that needs a preflight stops at its OPTIONS, which is what the bin records. robots.txt asks search engines not to crawl bin URLs.

The API

The base URL is https://bins.nimbusnexus.net/v1. Requests and answers are JSON. Send a key as Authorization: Bearer <key> or X-API-Key: <key> (Getting access). Timestamps are ISO 8601 in UTC, and one you send without an offset is read as UTC. Errors use the shape in Errors.

read, write and admin are explained under Who can do what.

Create a bin

POST /v1/bins takes a JSON body, {} when you set nothing:

A bin's lifetime can't be changed after it is created. When the workspace already holds its plan's bins, the answer is 402 quota_exceeded, with details.metric bins, details.limit and details.current. Bins held back by a plan downgrade don't count.

Find a bin

GET /v1/bins lists the workspace's bins, newest first. With url (a bin URL, with or without a path after the slug) or slug (in any case), it returns that one bin, or an empty list. Deleted and expired bins are never listed, and reading one answers 404.

Lists are paged with limit (1 to 200, default 50) and offset (0 to 10,000). The answer is {"items": [...], "next_offset": <offset>}: pass next_offset back as offset for the next page. It is null on the last page, and past offset 10,000.

The bin object

Change or delete a bin

PATCH /v1/bins/{id} takes label, status (active or disabled), or both, and answers with the bin. Disabling stops recording and keeps what the bin holds. A disabled bin still counts toward the plan's bins.

DELETE /v1/bins/{id} deletes a bin for good. Its URL stops recording at once, though senders still get 200; its slug is never issued again, to you or anyone; and what it recorded is deleted shortly after. Its place among the plan's bins frees at once.

DELETE /v1/bins/{id}/requests empties a bin: every request it holds is deleted and request_count goes back to 0. The bin keeps its URL and keeps recording.

Captured requests

GET /v1/bins/{id}/requests lists a bin's requests, newest first:

Each item:

GET /v1/requests/{id} returns one request with every field above, and:

With an API key, both routes need a paid plan: on Free they answer 402 not_entitled, with details.feature read_api. The console reads them on every plan. A request past its expires_at, or in a bin that has been emptied, deleted or has expired, answers 404.

Plan and usage

GET /v1/plan says which limits apply:

{
  "plan": "starter",
  "enforced_as": "starter",
  "ceilings": {
    "max_bins": 5,
    "monthly_requests": 25000,
    "retention_days": 7,
    "bin_ttl_minutes": 0,
    "bin_ttl_max_minutes": 10080,
    "read_api": 1,
    "bin_max_sources": 200,
    "bin_max_browser_posts": 5,
    "bin_share_pct": 50
  },
  "past_due": false,
  "suspended": false,
  "system": false
}

plan is the plan on record, empty when the workspace has none; enforced_as is the plan whose limits apply, free when there is none. ceilings holds the limits by name (Plans and limits). past_due is true while a charge is unsettled, and suspended once the grace period after it has ended. system is for NimbusNexus's own workspace.

GET /v1/usage says how much of them is used:

{
  "period": "2026-10-01",
  "requests": 1834,
  "monthly_requests": 25000,
  "bins": 2,
  "max_bins": 5,
  "bin_request_ceiling": 12500
}

period is the month, as its first day. requests counts what the workspace's bins recorded this month, against monthly_requests. bins counts the bins held, against max_bins. bin_request_ceiling is the most one bin may record this month.

Who can do what

A refused action answers 403 forbidden with details.reason role, and details.required names the role it needs: member to create or change a bin, admin to delete or empty one. For a key, member means the write or admin scope, and admin means admin. The API also takes keys with the write scope, which create and change bins but don't delete or empty them; the account console creates Read and Read & write keys.

Request Bins serves whole workspaces. A guest seat, or a key limited to one project, is refused on every route with 403 project_confined.

A workspace has Request Bins once an owner or admin has opened the console, or added it from Add a product. Until then, other members are refused with 403 product_not_enabled. Keys aren't affected.

Plans and limits

GET /v1/plan reports lifetimes in minutes, with 0 meaning until deleted (bin_ttl_minutes) or no plan limit (bin_ttl_max_minutes), and read_api as 1 or 0. Prices are on the overview.

• The month is a calendar month in UTC: period in GET /v1/usage. Every request a bin records counts, repeats included. A refused or rate-limited request doesn't.
• Past the month's requests, or past one bin's share of them (bin_request_ceiling), bins answer 200 and record nothing until the next month, and refused_count shows it. No API call is refused for it.
• Retention and lifetime are separate clocks. A request is deleted when the plan's retention runs out or when its bin ends, whichever comes first.
• Notices: when the workspace reaches 80% and then 100% of the month's requests, it is told by email, which goes to the workspace owner unless you choose another address, and by a webhook with the event type binsd.quota.threshold_reached if you set one up. Both are under Notifications in your account console.
• While a payment is overdue, creating and changing bins is refused with 402 workspace_frozen, and bins keep recording. If the grace period ends, the workspace is suspended: the same refusals come as 402 workspace_suspended, and bins answer 200 and record nothing. Deleting and reading still work, and nothing is deleted.
• On a smaller plan, bins over its max_bins are held back, newest first, as plan_downgrade, and come back, oldest first, once the plan allows them.

Errors

The API's errors use the shape described in Errors, with the codes Inboxes sends for the same situations:

The API sends no 409 and no 429.

What's next

• Quickstart — create a bin and read what it recorded.
• Request Bins API — every operation, with the request in curl, TypeScript, Python or Go.
• Errors — the error shape, every details key, and a pattern for handling them.
• Product overview — prices, and what Request Bins does not do.