Ir para o conteúdo
NimbusNexus

API de Request Bins

A API REST por trás do Request Bins: crie bins e encontre-os pela URL; renomeie, desative e exclua bins; encaminhe o que eles registram para o seu próprio servidor e teste o encaminhamento; leia e busque as requisições que eles registraram, em um bin ou em todos eles, agrupe por caminho as requisições de um bin, e esvazie-os; e consulte seu plano e seu uso, com o que o crédito comprou. Cada operação abaixo mostra a requisição na linguagem escolhida no topo da página. O Request Bins ainda não tem SDK, então TypeScript, Python e Go usam o cliente HTTP habitual de cada linguagem.

As chamadas usam uma chave de API de Request Bins, criada no console da sua conta. Ler requisições capturadas com uma chave exige um plano pago; o início rápido guia você pelo primeiro bin, e a referência explica o que a URL de um bin responde, as funções e os limites de cada plano.

Base URL
https://bins.nimbusnexus.net
Authentication
Authorization: Bearer <API key>
Version
Request Bins 0.1.21 · OpenAPI spec

Before the examples

The examples read your API key from BINS_API_KEY.

Shell
export BINS_API_KEY="<your-api-key>"

Bins

GET/v1/bins

List Bins

The workspace's bins, newest first. url or slug returns at most one, or none.

Parameters

NameInTypeDescription
limitqueryinteger—
offsetqueryinteger—
urlquerystring | nullOnly the bin this public URL names.
slugquerystring | nullOnly the bin with this slug.

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/bins" \
  -H "Authorization: Bearer $BINS_API_KEY"
POST/v1/bins

Create Bin

Create a bin. Its URL is answered and recorded at once.

Request body

FieldTypeDescription
labelstring—
expires_in_minutesinteger | null—

Responses

  • 201Successful Response
  • 401error.code = unauthorized
  • 402error.code = quota_exceeded | workspace_frozen | workspace_suspended
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X POST "https://bins.nimbusnexus.net/v1/bins" \
  -H "Authorization: Bearer $BINS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
GET/v1/bins/{bin_id}

Read Bin

Parameters

NameInTypeDescription
bin_id*pathstring—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/bins/<bin_id>" \
  -H "Authorization: Bearer $BINS_API_KEY"
PATCH/v1/bins/{bin_id}

Patch Bin

Rename a bin, switch it off (disabled: it answers and records nothing) and on (enabled), or set its forward_url (RFC-0027): every request it then records is also sent on to that URL, and the request's detail shows what the server answered.

More

forward_pipeline (RFC-0030) runs on every forward before it is sent: header and auth steps (a credential from a secret, for a target that authenticates its caller), filters, and, with forward_pipeline_changes_body, steps that rewrite the body. Checked whole when it is saved: a 422 invalid_pipeline names the first problem's step, path and reason. Deciding where a secret goes is an owner's or admin's (403 role): saving a pipeline whose auth step names one, and moving the URL of a bin whose pipeline does.

active, the earlier word for enabled, is still accepted for status and is deprecated: the bin comes back enabled, and the changelog will announce the date active is refused from.

Parameters

NameInTypeDescription
bin_id*pathstring—

Request body

FieldTypeDescription
labelstring | null—
status"enabled" | "disabled" | "active" | null`enabled` records what the bin is sent; `disabled` answers and records nothing. `active` is a deprecated spelling of `enabled`: it is still accepted, the bin comes back `enabled`, and the changelog will announce the date it is refused from.
forward_urlstring | null—
forward_pipelineobject | null—
forward_pipeline_changes_bodyboolean | null—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled | workspace_frozen | workspace_suspended
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error
  • 503error.code = unavailable

Example

curl -X PATCH "https://bins.nimbusnexus.net/v1/bins/<bin_id>" \
  -H "Authorization: Bearer $BINS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE/v1/bins/{bin_id}

Delete Bin

Delete a bin: its URL stops recording at once, its slug is never issued again, and its captured requests are removed shortly after.

Parameters

NameInTypeDescription
bin_id*pathstring—

Responses

  • 204Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X DELETE "https://bins.nimbusnexus.net/v1/bins/<bin_id>" \
  -H "Authorization: Bearer $BINS_API_KEY"
POST/v1/bins/{bin_id}/forward-pipeline/test

Test Forward Pipeline

Run a forward pipeline once on one of the bin's requests and send nothing: the editor's Test. pipeline need not be saved (omitted, the bin's own runs); it is checked as a save checks it, but a step that changes the body needs no confirmation here. Its auth steps add the workspace's secrets, shown masked (Bearer ••••). The answer is what a forward would send, Request Bins' own headers included, or which step dropped or failed it.

Parameters

NameInTypeDescription
bin_id*pathstring—

Request body

FieldTypeDescription
pipelineobject | null—
request_idstring | null—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled | workspace_frozen | workspace_suspended
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error
  • 503error.code = unavailable

Example

curl -X POST "https://bins.nimbusnexus.net/v1/bins/<bin_id>/forward-pipeline/test" \
  -H "Authorization: Bearer $BINS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "pipeline": {
      "version": 1,
      "steps": [
        {
          "headers": {
            "set": {
              "X-Source": "request-bins"
            }
          }
        }
      ]
    }
  }'
POST/v1/bins/{bin_id}/forward-test

Test Forward

Send a small JSON event ({"type": "request_bins.forward_test", …}) to the bin's forward URL now and return what it answered, so the URL is checked before real traffic depends on it. A few a minute per bin. The forwarder sends it, as it sends every forward: 503 forwarder_unavailable means it did not take the test within a few seconds, so nothing was sent. The bin's forward pipeline runs on the event first, as on every forward (RFC-0030), so the test also checks the credential its auth step adds; pipeline shows what it sent, masked.

Parameters

NameInTypeDescription
bin_id*pathstring—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled | workspace_frozen | workspace_suspended
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 429error.code = rate_limited
  • 500error.code = internal_error
  • 503error.code = unavailable

Example

curl -X POST "https://bins.nimbusnexus.net/v1/bins/<bin_id>/forward-test" \
  -H "Authorization: Bearer $BINS_API_KEY"
GET/v1/pipeline-templates

List Pipeline Templates

transform-core's gallery (RFC-0030): ready-made forward pipelines to start one from. A Slack, Discord or Microsoft Teams message (a request a bin captured is shown whole), and the body with only the fields listed or without its personal data. Each changes the body, so saving one needs forward_pipeline_changes_body. The same for every workspace; saving one makes a copy that is the bin's own.

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/pipeline-templates" \
  -H "Authorization: Bearer $BINS_API_KEY"

Secrets

GET/v1/secrets

List Secrets

The workspace's secrets, newest first, by name and id: never a value.

Parameters

NameInTypeDescription
limitqueryinteger—
offsetqueryinteger—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/secrets" \
  -H "Authorization: Bearer $BINS_API_KEY"
POST/v1/secrets

Create Secret

Store a credential for a forward pipeline's auth step to add: a bearer token, a password, an API key. Sealed when it is written and never returned; a pipeline names it by the id this answers. Wherever forwarding is: Starter, Pro and Custom.

Request body

FieldTypeDescription
namestring—
value*string—

Responses

  • 201Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled | workspace_frozen | workspace_suspended
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error
  • 503error.code = unavailable

Example

curl -X POST "https://bins.nimbusnexus.net/v1/secrets" \
  -H "Authorization: Bearer $BINS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "value": "example"
  }'
GET/v1/secrets/{secret_id}

Read Secret

Parameters

NameInTypeDescription
secret_id*pathstring—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/secrets/<secret_id>" \
  -H "Authorization: Bearer $BINS_API_KEY"
PATCH/v1/secrets/{secret_id}

Patch Secret

Rename a secret, or replace its value: every forward through a pipeline that names it sends the new one from its next attempt on.

Parameters

NameInTypeDescription
secret_id*pathstring—

Request body

FieldTypeDescription
namestring | null—
valuestring | null—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = workspace_frozen | workspace_suspended
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error
  • 503error.code = unavailable

Example

curl -X PATCH "https://bins.nimbusnexus.net/v1/secrets/<secret_id>" \
  -H "Authorization: Bearer $BINS_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'
DELETE/v1/secrets/{secret_id}

Delete Secret

Delete a secret, for good. Refused (409 secret_in_use) while a bin's forward pipeline names it: change those pipelines first.

Parameters

NameInTypeDescription
secret_id*pathstring—

Responses

  • 204Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 409error.code = conflict
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X DELETE "https://bins.nimbusnexus.net/v1/secrets/<secret_id>" \
  -H "Authorization: Bearer $BINS_API_KEY"

Captured requests

GET/v1/bins/{bin_id}/paths

List Paths

A bin's requests grouped by path, the most recently used path first: how many were sent to each, with which methods, and when the last came. Only the newest 10,000 requests are counted (capped says the bin holds more); list one path's requests with path= on GET /v1/bins/{bin_id}/requests.

Parameters

NameInTypeDescription
bin_id*pathstring—
methodqueryarray of stringOnly requests sent with this method; repeat it for any of several. Case-insensitive.
limitqueryinteger—
offsetqueryinteger—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/bins/<bin_id>/paths" \
  -H "Authorization: Bearer $BINS_API_KEY"
GET/v1/bins/{bin_id}/requests

List Requests

A bin's captured requests, newest first. Poll with since set to the newest received_at already seen; walk back with until. A search (q, or a header or field) continues with until set to the page's next_until; its offset skips requests before it reads.

Parameters

NameInTypeDescription
bin_id*pathstring—
sincequerystring | nullOnly requests received after this instant (strict).
untilquerystring | nullOnly requests received at or before this instant.
methodqueryarray of stringOnly requests sent with this method; repeat it for any of several. Case-insensitive.
pathquerystring | nullOnly requests sent to exactly this path: what followed the slug, from its `/`, as the list shows it, without the query string. Case-sensitive.
qquerystring | nullOnly requests containing this text, ignoring case, in the path and query string, a header (as `name: value`) or the body; `in`, `header` and `field` narrow where. A search reads at most 16 MiB of requests per call, newest first: when it stops before the oldest, `next_until` is set and `next_offset` is not.
inquery"all" | "path" | "headers" | "body"Where `q` looks: `all`, or only `path` (the path and query string), `headers` (each as `name: value`) or `body`.
headerquerystring | nullOnly this header's values, its name ignoring case; any of them when it was sent more than once. Without `q`, the requests that carry it at all.
fieldquerystring | nullOnly this field of a JSON body, as `data.object.id` or `items[0].sku`: a string as itself, a number as JSON writes it, an object or array as JSON text. Without `q`, the requests whose body has it at all. A body that is not JSON, or was cut at 1 MiB, has no fields.
limitqueryinteger—
offsetqueryinteger—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/bins/<bin_id>/requests" \
  -H "Authorization: Bearer $BINS_API_KEY"
DELETE/v1/bins/{bin_id}/requests

Empty Bin

Delete every captured request in a bin. The bin keeps its URL and keeps recording.

Parameters

NameInTypeDescription
bin_id*pathstring—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X DELETE "https://bins.nimbusnexus.net/v1/bins/<bin_id>/requests" \
  -H "Authorization: Bearer $BINS_API_KEY"
GET/v1/requests

List All Requests

Every captured request in the workspace's live bins, newest first, each with its bin_id: what has arrived anywhere, in one call rather than one per bin. It takes the same filters, search and paging as GET /v1/bins/{bin_id}/requests, and the same credentials: any seat, and an API key on a plan that includes reading captures.

Parameters

NameInTypeDescription
sincequerystring | nullOnly requests received after this instant (strict).
untilquerystring | nullOnly requests received at or before this instant.
methodqueryarray of stringOnly requests sent with this method; repeat it for any of several. Case-insensitive.
pathquerystring | nullOnly requests sent to exactly this path: what followed the slug, from its `/`, as the list shows it, without the query string. Case-sensitive.
qquerystring | nullOnly requests containing this text, ignoring case, in the path and query string, a header (as `name: value`) or the body; `in`, `header` and `field` narrow where. A search reads at most 16 MiB of requests per call, newest first: when it stops before the oldest, `next_until` is set and `next_offset` is not.
inquery"all" | "path" | "headers" | "body"Where `q` looks: `all`, or only `path` (the path and query string), `headers` (each as `name: value`) or `body`.
headerquerystring | nullOnly this header's values, its name ignoring case; any of them when it was sent more than once. Without `q`, the requests that carry it at all.
fieldquerystring | nullOnly this field of a JSON body, as `data.object.id` or `items[0].sku`: a string as itself, a number as JSON writes it, an object or array as JSON text. Without `q`, the requests whose body has it at all. A body that is not JSON, or was cut at 1 MiB, has no fields.
limitqueryinteger—
offsetqueryinteger—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/requests" \
  -H "Authorization: Bearer $BINS_API_KEY"
GET/v1/requests/{request_id}

Read Request

One captured request in full: headers in arrival order, the query, the body, and its forwards with what the target answered (RFC-0027).

Parameters

NameInTypeDescription
request_id*pathstring—

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 402error.code = not_entitled
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/requests/<request_id>" \
  -H "Authorization: Bearer $BINS_API_KEY"

Plan and usage

GET/v1/plan

Read Plan

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/plan" \
  -H "Authorization: Bearer $BINS_API_KEY"
GET/v1/usage

Read Usage

Responses

  • 200Successful Response
  • 401error.code = unauthorized
  • 403error.code = forbidden
  • 404error.code = not_found
  • 413error.code = payload_too_large
  • 422error.code = validation_error
  • 500error.code = internal_error

Example

curl -X GET "https://bins.nimbusnexus.net/v1/usage" \
  -H "Authorization: Bearer $BINS_API_KEY"