HTTP Request

View as Markdown

A RocketRide tool node that lets an AI agent make guarded HTTP requests to public API endpoints.

About HTTP

HTTP is the request-and-response protocol used by web APIs. An HTTP request names a URL, method, headers, credentials, and optional body, while a response carries status, headers, and content.

What it does

This node provides one controlled HTTP client for an agent and has no pipeline lanes. Pick it when the agent must call a public API endpoint directly; use a product-specific tool when that service already has a dedicated node and richer operations. Method switches, URL patterns, the network boundary, and rate limits are enforced before every request. Credentials come either per call or from the node configuration, where ${ROCKETRIDE_*} placeholders resolve on the engine so the secret never reaches the caller.

As a tool

The hidden server-name setting defaults to http, so the registered function is http.http_request by default.

Function	Description
http.http_request	Makes one guarded HTTP request and returns its completed response.

url and method are required. The method must be one of GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS and must be enabled in configuration. Optional inputs include headers, query parameters, path parameters, timeout, advanced authentication and body objects, plus body_json, bearer_token, and basic_auth shortcuts. A completed response—including a non-2xx HTTP response—returns status_code, status_text, headers, body, json, elapsed_ms, and content_type.

When Authentication is configured on the node, that credential is added to every request and per-call credentials (bearer_token, basic_auth, an auth object other than none, or an Authorization header) are rejected, so an agent cannot replace it. Configured default headers are sent too; a per-call header of the same name wins.

Invalid input, disabled methods, whitelist rejection, rate-limit rejection, and transport errors raise tool errors. A parsed JSON field is null when the response type is not JSON-like or cannot be parsed; the raw text remains in body.

Configuration

Use the default method set for a broad but controlled API agent, then limit endpoints and throughput for the services it is allowed to reach. The server name changes the function namespace and should be stable once an agent prompt refers to it.

Allowed methods

GET, POST, PUT, PATCH, and DELETE are enabled by default; HEAD and OPTIONS are disabled. Enable only methods that the intended API flow needs, especially before giving an agent access to a URL where mutation is possible.

URL Whitelist

An empty whitelist allows every public URL; non-public network destinations remain blocked either way. Non-empty patterns are matched against the request URL, so anchor them when the endpoint scope must be exact, for example ^https://api\.example\.com/. Path-parameter replacements are percent-encoded to remain a single URL path segment.

While Authentication is set the whitelist must be non-empty, and every pattern must pin one exact https:// host with escaped dots. Whole-authority forms such as ^https://[^/]+/, plain http://, and alternations are refused at startup, because a configured credential would otherwise travel to any host the agent names. The same whitelist rule applies when any default header is configured.

Authentication

Authentication selects the credential sent with every request: none (default; the caller supplies auth per call), bearer (Bearer token, sent as Authorization: Bearer ...), basic (Basic auth username and Basic auth password), or api_key (API key header name and API key value, for example X-API-Key). Put a ${ROCKETRIDE_*} placeholder in the secret field, such as ${ROCKETRIDE_GITHUB_TOKEN}, and set that variable in the org, team, or user environment; the engine substitutes it when the pipeline is resolved, so the value never reaches the browser or the agent.

Three rules apply as soon as the type is not none. The selected fields must be complete: an empty token or a placeholder that did not resolve fails the node at startup, naming the variable, instead of sending an anonymous request. The URL whitelist must be non-empty, and every pattern must pin one exact https:// host. Per-call credentials (bearer_token, basic_auth, auth other than none, and Authorization / Proxy-Authorization / Cookie / Host headers) are rejected. Fields that belong to another type are ignored with a warning. The credential is only ever sent as a header, never as a query parameter, and never to a redirect target.

Default headers

Rows of header name and value sent with every request, for example Accept: application/vnd.github+json or X-GitHub-Api-Version: 2022-11-28. A per-call header with the same name (matched case-insensitively) replaces the default. Authorization, Proxy-Authorization, Cookie, Host, Content-Type, Content-Length, and Transfer-Encoding are refused here; credentials belong in the Authentication fields, and body headers are derived from the request body. Configuring any default header requires the same pinned https whitelist as Authentication. Blank rows are ignored. A value without a name, a duplicate name, or an unresolved ${ROCKETRIDE_*} placeholder fails startup.

Network boundary

Private, loopback, link-local, and multicast destination addresses are blocked. Redirects are returned to the agent as 3xx responses and are not followed automatically. There is no private-network override: localhost and internal endpoints are intentionally unsupported.

Rate limits

The defaults are 10 requests per second, 100 per minute, and five concurrent requests. The token buckets and concurrency limit reject immediately rather than queue, so an agent must retry later after a limit error. Set all three values explicitly to zero to disable limiting; otherwise each configured value is clamped to at least one.

Authentication

The node needs whatever the target API accepts: a bearer token (for GitHub, a fine-grained personal access token carrying only the permissions the agent's calls need), a Basic username and password, or an API key header. Store the secret as a ROCKETRIDE_* variable in the org, team, or user environment and reference it from the matching Authentication field as ${ROCKETRIDE_NAME}; never paste the value into the pipeline itself.

Per-call credentials remain available while Authentication is none. The simple shortcuts set bearer or Basic authentication when the equivalent advanced object is absent, and the advanced auth object supports none, basic, bearer, and an API key placed in a header or query parameter.

Notes

Request bodies and timeout

body_json serializes objects and arrays as JSON; a string is used verbatim. The advanced body supports raw content, multipart form data, and URL-encoded form data. Timeout defaults to 30 seconds, caps positive values at 300 seconds, and treats zero or negative values as the default.

Upstream docs

• HTTP documentation at MDN

What it does

Exposes a single agent-callable tool, http_request, registered as <serverName>.http_request (default: http.http_request). The agent provides the full request (method, URL, headers, query/path parameters, auth, and body) and receives a structured response containing status, headers, body text, parsed JSON, and timing.

Uses the requests library to execute calls. The node has no lanes; it is attached to an agent purely as a tool.

Four security guardrails are enforced before every request:

• Allowed methods: per-method toggles. GET, POST, PUT, PATCH, DELETE are enabled by default; HEAD and OPTIONS are disabled by default.
• URL whitelist: regex patterns the request URL must match. Empty by default, which allows all public URLs (config validation emits a warning when the whitelist is empty).
• Network boundary: private, loopback, link-local, and multicast destination addresses are blocked. Redirects are returned to the agent as 3xx responses and are not followed automatically. There is no private-network override: localhost and internal endpoints are intentionally unsupported.
• Rate limiting: token-bucket limits per second and per minute, plus a concurrency cap. On by default (10/s, 100/min, 5 concurrent).

A credential configured on the node (bearer, Basic, or API key header; ${ROCKETRIDE_*} placeholders resolve on the engine) is applied to every request. It makes the whitelist mandatory and turns per-call credentials into an error.

---

Configuration

Field	Type	Description
serverName	string	Default "http". Namespace prefix for the tool: .http_request
allowGET	boolean	Default true.
allowPOST	boolean	Default true.
allowPUT	boolean	Default true.
allowPATCH	boolean	Default true.
allowDELETE	boolean	Default true.
allowHEAD	boolean	Default false.
allowOPTIONS	boolean	Default false.
whitelistPattern	string	Default empty.
urlWhitelist	array	Regex patterns for allowed public URLs. A request URL must match at least one pattern. If empty, all public URLs are allowed; non-public network destinations remain blocked. Mandatory and every pattern must pin one exact https host while authType is not none or any default header is set.
authType	string	Default "none". Credential sent with every request: none, bearer, basic, or api_key.
authToken	string	Bearer token for authType: bearer. Secure; use a ${ROCKETRIDE_*} placeholder.
authUsername	string	Username for authType: basic.
authPassword	string	Password for authType: basic. Secure.
authHeaderName	string	Header carrying the key for authType: api_key, e.g. X-API-Key.
authHeaderValue	string	Key sent in that header. Secure.
headerName	string	Default empty. Name column of a defaultHeaders row.
headerValue	string	Default empty. Value column of a defaultHeaders row.
defaultHeaders	array	Headers sent with every request; a per-call header of the same name replaces one. Authorization, Proxy-Authorization, Cookie, Host, Content-Type, Content-Length, and Transfer-Encoding are refused. Requires a pinned https whitelist when any row is set.
rateLimitPerSecond	number	Default 10. Maximum number of HTTP requests allowed per second. Uses a token-bucket algorithm for smooth enforcement.
rateLimitPerMinute	number	Default 100. Maximum number of HTTP requests allowed per minute. Provides a broader throttle beyond the per-second limit.
maxConcurrentRequests	number	Default 5. Maximum number of HTTP requests that can be in-flight simultaneously.

The node ships one profile, Default, which sets serverName to http.

An invalid non-empty whitelist regex now fails configuration validation rather than being skipped, so a typo can no longer silently widen the restriction. Blank or whitespace-only placeholder rows are ignored; a whitelist made only of them allows all public destinations.

---

Available tools

| Tool | Description | |---|---|---| | http_request | Make an HTTP request. Required: "url" and "method". For JSON bodies, pass "body_json" as a JSON object (e.g. {"name": "foo"}), it is serialized automatically. For bearer auth, pass "bearer_token" as a string. For basic auth, pass "basic_auth": {"username": "...", "password": "..."}. Optional: "headers", "query_params", "path_params", "timeout" (seconds, default 30, max 300). |

Required parameters

Parameter	Description
url	Full URL, e.g. https://api.example.com/users/1
method	GET, POST, PUT, PATCH, DELETE, HEAD, or OPTIONS

Convenience shortcuts

These cover the common cases without the verbose auth / body objects. Each shortcut is only applied when the corresponding advanced field is not also set. When the node is configured with authentication, bearer_token, basic_auth, an auth object other than none, and an Authorization header are rejected.

Parameter	Description
body_json	JSON object or array, passed directly, serialized automatically and sent as raw application/json
bearer_token	Token string, sent as an Authorization: Bearer ... header
basic_auth	{username, password} for HTTP basic auth

Optional parameters

Parameter	Description
query_params	Key-value pairs appended to the URL as the query string
headers	Custom request headers
path_params	Replacements for :name placeholders in the URL (e.g. {"id": "123"} replaces :id)
timeout	Request timeout in seconds. Default 30, capped at 300.
auth	Advanced auth config (see Authentication below). Prefer the shortcuts.
body	Advanced body config (see Request bodies below). Prefer body_json.

Response

{
  "status_code": 200,
  "status_text": "OK",
  "headers": { ... },
  "body": "...",
  "json": { ... },
  "elapsed_ms": 142,
  "content_type": "application/json"
}

json is populated automatically when the response Content-Type contains json (or javascript) and the body parses; otherwise it is null and the raw text is in body. elapsed_ms is wall-clock request time in milliseconds.

---

Authentication

The auth object supports type: none, basic, bearer, or api_key.

Type	Fields	Effect
basic	basic: {username, password}	HTTP basic auth
bearer	bearer: {token}	Authorization: Bearer <token> header
api_key	api_key: {key, value, add_to}	Adds key: value as a header (add_to: "header", the default) or query parameter (add_to: "query_param")

For the common cases, the bearer_token and basic_auth shortcuts are simpler and expand to the same thing.

The same three types (API key as a header only) can be fixed in the node config via authType and the matching auth* fields, with ${ROCKETRIDE_*} placeholders resolved on the engine. A configured credential replaces per-call auth entirely and requires an exact-host https whitelist.

---

Request bodies

The body object supports type: none, raw, form_data, or x_www_form_urlencoded.

Type	Fields	Effect
raw	raw: {content, content_type}	Sends content as-is. content_type must be one of application/json (default), application/xml, text/html, text/javascript, text/plain; it becomes the Content-Type header unless one is already set.
form_data	form_data: {key: value, ...}	Sent as a multipart/form-data envelope
x_www_form_urlencoded	urlencoded: {key: value, ...}	Sent as URL-encoded form fields

For JSON payloads, prefer the body_json shortcut, pass the object directly and it is serialized and wrapped as raw application/json automatically.

---

Rate limiting

Three independent limits are enforced per node (shared across all calls):

• Per-second: token bucket, capacity and refill rate equal to rateLimitPerSecond.
• Per-minute: token bucket, capacity rateLimitPerMinute, refilling continuously.
• Concurrency: semaphore capped at maxConcurrentRequests in-flight requests.

The limiter does not queue or block: when a limit is hit the tool call fails immediately with an error telling the agent to retry after a short delay (or to wait for an in-flight request, for the concurrency limit). The concurrency check runs first so a rejected request never consumes rate tokens.

To disable rate limiting entirely, set all three values to 0. Otherwise each non-zero value is clamped to a minimum of 1.

---

-->

Schema

Field	Type	Description	Default
http_request.allowDELETE	boolean	DELETE	true
http_request.allowGET	boolean	GET	true
http_request.allowHEAD	boolean	HEAD	false
http_request.allowOPTIONS	boolean	OPTIONS	false
http_request.allowPATCH	boolean	PATCH	true
http_request.allowPOST	boolean	POST	true
http_request.allowPUT	boolean	PUT	true
http_request.authHeaderName	string	API key header name Header that carries the key when Authentication is API key header, e.g. X-API-Key.	""
http_request.authHeaderValue	string	API key value Value sent in the API key header. A ${ROCKETRIDE_*} placeholder keeps it on the engine.	""
http_request.authPassword	string	Basic auth password Used when Authentication is Basic. A ${ROCKETRIDE_*} placeholder keeps it on the engine.	""
http_request.authToken	string	Bearer token Sent as "Authorization: Bearer " when Authentication is Bearer token. Use a placeholder such as ${ROCKETRIDE_GITHUB_TOKEN} so the secret never leaves the engine.	""
http_request.authType	string	Authentication Credential applied to every request this node sends. Set it here with a ${ROCKETRIDE_*} placeholder (resolved on the engine from the org, team, and user environment) instead of passing tokens per call. When set, the URL whitelist must be non-empty and every pattern must pin one exact https host, and per-call auth is rejected.	"none"
http_request.authUsername	string	Basic auth username Used when Authentication is Basic.	""
http_request.defaultHeaders	array	Default headers Headers sent with every request, e.g. Accept or X-GitHub-Api-Version. A per-call header with the same name (case-insensitive) replaces the default. Authorization, Proxy-Authorization, Cookie, Host, Content-Type, Content-Length, and Transfer-Encoding are not allowed here; credentials belong in the Authentication fields. Non-empty default headers require the same pinned https whitelist as Authentication. Blank rows are ignored.
http_request.headerName	string	Header name	""
http_request.headerValue	string	Header value	""
http_request.maxConcurrentRequests	number	Max concurrent requests Maximum number of HTTP requests that can be in-flight simultaneously.	5
http_request.rateLimitPerMinute	number	Max requests per minute Maximum number of HTTP requests allowed per minute. Provides a broader throttle beyond the per-second limit.	100
http_request.rateLimitPerSecond	number	Max requests per second Maximum number of HTTP requests allowed per second. Uses a token-bucket algorithm for smooth enforcement.	10
http_request.serverName	string	Server name Namespace prefix for the tool: .http_request	"http"
http_request.urlWhitelist	array	URL Whitelist Python regex patterns applied with match() to the final canonical URL after path substitution, regular query parameters, and query-based API-key auth. A request-time source recognizer accepts only exact literal/escaped hosts with supported numeric-port forms, or a deliberate [^/] whole-authority form, followed by an explicit authority boundary. Unsupported or ambiguous authority syntax fails closed even when the regex matches. [] or only blank placeholder rows allows all public destinations; non-public destinations remain blocked. Blank rows mixed with valid patterns are ignored; invalid non-empty regexes, non-string values, and malformed entries fail closed.
http_request.whitelistPattern	string	URL Pattern (regex) Applied with Python regex match() to the final canonical URL after path substitution, regular query parameters, and query-based API-key auth. After matching, a fail-closed source grammar requires a literal HTTP(S) scheme; an exact literal/escaped DNS, IPv4, or bracketed-IPv6 host with an optional exact or [0-9]-based port policy, or a whole-authority [^/] policy; and an explicit path, query, or end boundary. Unsupported or ambiguous authority regex syntax is denied at request time. Example: ^https://api\.example\.com(?::[0-9]+)?(?:/\|$). Scheme-only prefixes are denied; use an empty whitelist to allow all public destinations. Blank placeholder rows are ignored.	""