send_request
Send HTTP requests for API calls with {{variables}} filled in, secrets masked, and undefined variables failing safely; get status, timing, size, headers, and parsed JSON back.
Instructions
Send an HTTP request through Plunger and get back status, timing, size, headers and the parsed JSON body.
Use this instead of curl for API calls: {{variables}} (including the user's secrets, by name) are filled in
for you, an undefined {{variable}} makes the request fail safely instead of sending the placeholder, secret
values are masked in the result, and the request is recorded in the history the user sees in Plunger.
Send a saved request by name with saved_request, or describe one with method, url, headers and a body.
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| url | No | Full URL. May use {{variables}}, e.g. "{{base}}/users/{{id}}". Required unless saved_request is given. | |
| body | No | A raw text body, sent as-is. Use instead of `json` for non-JSON payloads. | |
| form | No | Form fields, sent as application/x-www-form-urlencoded. | |
| json | No | A JSON body (any JSON value). Sent with Content-Type: application/json. | |
| method | No | GET, POST, PUT, PATCH, DELETE, HEAD or OPTIONS. Defaults to GET. | |
| select | No | Return only these values instead of the whole body, e.g. ["$.data[0].id", "header:Location", "status"]. Saves context on a big response; `json`, `body` and the headers are then left out. `[?(@.name=='Done')]` keeps the array items whose field equals the value. If every path fails the whole response is returned with the reasons; if only some fail, the values that could be read come back and `problems` names the rest. | |
| extract | No | Keep values from the response as variables for later requests, e.g. [{"name": "token", "from": "json:$.access_token"}]. `from` is `json:$.path`, `header:Name` or `status`. A name like token or password is kept as a hidden secret. | |
| headers | No | Request headers, e.g. {"Accept": "application/json", "Authorization": "Bearer {{token}}"}. A list of {"name", "value"} objects or "Name: value" strings is accepted too. | |
| variables | No | Extra or overriding {{variable}} values for this request only. The user's own variables (including secrets) are already available by name; you don't need their values. | |
| insecure_tls | No | Skip TLS certificate checks, e.g. for a local server with a self-signed certificate. | |
| timeout_secs | No | Seconds to wait for a response (1-600). Defaults to the user's setting (20). | |
| saved_request | No | Send a saved request by name (see list_saved_requests). Any other field given here overrides that part of it. | |
| max_body_chars | No | Longest body to return, in characters (default 50000). A longer JSON body comes back as an outline of its shape (keys, types, array lengths) with a hint to use `select`; a longer text body is cut and marked with `body_cut_from_chars`. | |
| include_headers | No | Which response headers to return: `all`, `none`, or `relevant` (location, link, retry-after, content-type, content-disposition, etag, rate-limit headers and set-cookie names). Left out: `all`, or `none` when `select` is used. | |
| follow_redirects | No | Follow redirects (default true). Set false to receive the redirect response itself and read its `Location` header. | |
| use_saved_bearer | No | Attach the Bearer token the user saved in Plunger. Off by default: only turn it on for a host the user asked you to call with their credentials. |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| ok | Yes | True for a 2xx status. | |
| body | No | The body as text, when it is not JSON or is too long to return whole. | |
| hint | No | What to do next, when the response was too big to return whole. | |
| json | No | The body is valid JSON, parsed. Absent for non-JSON bodies, or when the JSON is longer than the size limit (then it is in `body`, cut short). | |
| binary | No | The body isn't text, so it is not included; see `size_bytes` and the Content-Type header. | |
| sha256 | No | For a binary body: its SHA-256, so the agent can check it without receiving the bytes. | |
| status | Yes | ||
| headers | Yes | ||
| outline | No | A JSON body too long to return whole: its shape (keys, types, array lengths, one example each) instead of cut-off text. Ask for the values you need with `select`. | |
| request | Yes | ||
| ttfb_ms | No | Milliseconds until the response headers arrived. | |
| problems | No | Things that did not work in `select` or `extract`, such as a path that is not in the response. | |
| redacted | No | Secrets whose values appeared in the response and were replaced with `[redacted:<name>]`. Names only, never values. | |
| selected | No | With `select`: just the values asked for, by the path given. `json` and `body` are then left out. | |
| body_file | No | With `--out` on the command line: the file the whole body was written to. | |
| final_url | No | Where the request ended up, when it was redirected. | |
| redirects | No | The redirects that were followed, in order (absent when there were none). | |
| elapsed_ms | Yes | ||
| size_bytes | Yes | Bytes of body received. | |
| status_text | Yes | ||
| detected_type | No | For a binary body: what its first bytes say it is (`png`, `pdf`, `zip`, ...), when known. | |
| variables_set | No | With `extract`: the variables that were set from this response (secrets by name only). | |
| truncated_at_10mb | Yes | The response exceeded Plunger's 10 MB read limit; only the first 10 MB were read. | |
| body_cut_from_chars | No | The body was longer than the limit and has been cut; this is its full length in characters. |