> ## Documentation Index
> Fetch the complete documentation index at: https://agents.nanonets.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# HTTP Request with a Connector

> Tool that makes one HTTP request with a REST API connector's credential filled in by reference — the agent writes {{secret:NAME}} and never sees the value.

`integration_http_request` (display name **"HTTP Request with a Connector"**) makes one HTTP request to an API, with the credential of one of the workspace's **REST API connectors** filled in by reference. The agent writes a placeholder such as `{{secret:ashby}}`; the platform puts the real value in when it sends the request, and puts the placeholder back in everything the agent sees. The credential never reaches the model, the agent's sandbox, or the sidecar's tool server.

It is also how the sidecar's `http_request` sends a request that carries a secret: the tool server forwards it here instead of holding credentials itself.

## Enablement and authentication

* Off by default — enable it in the agent's Tools panel. Sidecar runs use it through `http_request` without it being listed.
* Credentials come from the workspace's **REST API** connectors (Integrations → REST API): a base URL plus a bearer token, Basic Auth, an **API key sent as the Basic username** (Ashby, Stripe, Greenhouse), or no auth. For an API with no GET endpoint, set the connector's test method to POST (it sends `{}` to the test path). The connector's **name** is the placeholder's `NAME`, matched case-insensitively. Only **active** connectors of the task's own workspace are visible.

## Placeholders

| Placeholder | Stands for |
| - | - |
| `{{secret:NAME}}` | The connector's credential: its bearer token, its API key (API key as Basic username), or for Basic Auth its password — or the username when there is no password. |
| `{{secret:NAME.api_key}}` | The API key. |
| `{{secret:NAME.token}}` | The bearer token. |
| `{{secret:NAME.username}}` | The basic-auth username. |
| `{{secret:NAME.password}}` | The basic-auth password. |

Placeholders may appear in `headers`, `basic_auth`, `params`, the URL's path or query, and the `json` or `body` — never in the host.

## Inputs

* `url` (required): absolute URL. A request that carries a placeholder must be `https`.
* `method`: default `GET`.
* `headers`, `params`: objects of strings.
* `json` (any JSON value) or `body` (raw text) — not both.
* `basic_auth`: `{username, password}`.
* `timeout_s`: default 60, max 300.

## Output

Structured result: `status`, `reason`, `content_type`, `headers` (only `content-type`, `content-length`, `location`, `retry-after`, `link` and `x-ratelimit-*`), `bytes`, and either `body_text` (a text, JSON, XML, CSV or YAML body) or `body_base64` (anything else). The text shown to the agent is the status line plus up to 20,000 characters of the body. Every filled value is replaced by its placeholder in the body, the headers and any error message.

## Security

* **Host-bound credentials**: a connector's credential is sent only to the host of its base URL, and only over `https`. A request to any other host with that placeholder is refused before it is sent.
* **No redirects with a secret**: a request that carries a credential returns a redirect as it is (`status` 3xx, `location` header) rather than following it, so the credential can't be carried to another host. Requests without one follow up to 5 redirects.
* **SSRF**: private, loopback, link-local (cloud metadata) and CGNAT addresses are refused, checked up front and again when each connection is made.
* **Audit**: every request emits an `external_call` event (provider `integration_http_request`), host only; full URLs are never logged.

## Limits

* Bodies over 4 MB are cut to 4 MB, with `truncated: true`.
* No retries: a request is sent once.

## Errors

* Unknown connector name → error listing the workspace's REST API connectors.
* A placeholder sent to a host other than its connector's, or over `http` → refused before sending.
* A connector with no value for the named field (e.g. `.token` on a basic-auth connector) → error.
* A credential shorter than 4 characters (other than an explicit `.username`) → error: it could not be kept out of the answer, so it is not sent.
* A private or internal address → refused.
* An answer with status 400 or above is returned in full but marked as an error.