# HTTP Request Node — Connector Mode

Use this walkthrough when the target service has an IS connector and you want managed auth (OAuth / API key) handled by an existing IS connection.

**Prerequisite:** a healthy IS connection for the target connector. Step 2 verifies this. If none exists, propose manual mode as the fallback and confirm the switch with the user before finalizing — do not switch modes without that confirmation.

Before starting, read [impl.md](impl.md) for the node type, registry validation, and the "always use `node configure`" rule. Follow Steps 1–5 in order.

## Step 1 — Add the node

```bash
uip maestro flow node add <ProjectName>.flow core.action.http.v2 \
  --label "<HTTP node label>" --output json
```

> **Inside a loop body?** Add `--parent <LOOP_NODE_ID>` to set `parentId`. Without it, the node runs outside the loop context and outputs are null. See [loop/impl.md](../loop/impl.md).

The CLI copies the manifest into `definitions[]`, adds the node instance, registers `variables.nodes`, and inserts a `layout.nodes` placeholder — byte-for-byte from the registry. Save the returned `<nodeId>` — Steps 2 and 3 reuse it. Leave `inputs` empty; Step 3 populates `inputs.detail`. Do not hand-author the definition — see [impl.md — Add the node](impl.md#add-the-node).

## Step 2 — Identify target connection

**Connector mode only works if the connector supports the HTTP request activity** — verify by running `uip is connectors get "<target-connector-key>"` and checking the `HasHttpRequest` flag. If the flag is false, **STOP** — a connection cannot help. Use the recovery question below (switch to manual mode / skip / something else; the create-a-connection option does not apply) and do not switch modes without confirmation.

```bash
uip is connections list "<target-connector-key>" --all-folders --output json
```

`--all-folders` is mandatory for discovery. Selection rules, empty-result recovery, and ping verification live in the platform skill — do not duplicate them here.

> **MUST READ before any `uip is connections ...` call:** [/uipath:uipath-platform — connections.md](../../../../../uipath-platform/references/integration-service/connections.md).

Record the chosen connection's `Id` and `FolderKey` — Step 3 needs both.

> **HTTP-specific recovery — no usable connection.** If platform-skill recovery yields nothing (empty after `--all-folders` + `--refresh`, user declines to create one), the HTTP node has unique fallback options. Ask the user to confirm the path — **manual mode is the recommended auto-fallback**, pre-selected, since it unblocks the node without a connection:
>
> - **Switch this node to manual mode** *(recommended)* — abandon this walkthrough and follow [impl-manual.md](impl-manual.md). Manual changes the auth model (you supply auth yourself), so this needs explicit confirmation.
> - **Create a new connection now** — `uip is connections create "<target-connector-key>"` starts the OAuth flow. User completes browser auth themselves, then re-run `uip is connections list` to pick up the new connection.
> - **Skip this node**.
> - **Something else**.
>
> Auto-try the fallback, but do not finalize a mode switch without the user's confirmation; do not invent a placeholder ID; do not skip the node without explicit selection. See the dropdown question rule in [SKILL.md](../../../../SKILL.md).

## Step 3 — Configure the node

> **STOP — open the platform skill before configuring.** Before composing `url` / `query` / `body`, read [/uipath:uipath-platform — http-request.md](../../../../../uipath-platform/references/integration-service/http-request.md) and resolve every value you don't already have (IDs from names, required body fields, endpoint path, response shape).
>
> - **If the target connector is listed in that skill's `vendor-docs-registry.json`:** you MUST follow its **Step 0 (Ground Against the Vendor's API Docs)** — read the `docsUrl` + `notes` and confirm the exact endpoint with the `http-request` probe before running `node configure`. Pass the endpoint path verbatim: vendor method names can contain literal dots (Slack ``chat.postMessage`) — the dot is part of the path segment.
> - **If the connector is NOT listed:** the registry-grounding step does not apply — resolve missing values via the `http-request` probe / vendor docs as usual.

```bash
uip maestro flow node configure <ProjectName>.flow <nodeId> \
  --detail '{
    "authentication": "connector",
    "targetConnector": "<target-connector-key>",
    "connectionId": "<target-connection-id>",
    "folderKey": "<folder-key>",
    "method": "GET",
    "url": "/api/endpoint",
    "query": {"param1": "value1"}
  }' --output json
```

> **Connector mode supports `application/json` request and response bodies only.**

The CLI:

- Builds the full `inputs.detail` (connector, connectionId, bodyParameters, essentialConfiguration)
- Auto-fills both `bodyParameters.path` and `bodyParameters.url` from the single `url` value you pass
- Generates `bindings_v2.json`
- Creates a connection resource file under `resources/solution_folder/connection/`

**Dynamic values:** connector input fields do not resolve `{$vars.x}` brace-templates — use `=js:` expressions for any dynamic `url` / `headers` / `body` / `query`. Pass the `=js:` string verbatim in `--detail`. Full rationale and examples: [impl.md — Dynamic values](impl.md#dynamic-values-in-url--headers--body--query).

## Step 4 — (Optional) Response branches

Skip unless you need to route downstream paths based on response content (e.g., `items.length > 0` vs empty). For generic call-failure handling use the `error` port in Step 5 instead. Full syntax and rules: [impl.md — Conditional branches](impl.md#conditional-branches).

## Step 5 — Wire edges

The HTTP node's target port is `input`. Source ports: `default` (success), `error` (network/non-2xx), `branch-{id}` (one per Step 4 entry). Wire `default` to the next node. Wire `error` to a handler **only when the requirements say what a failed call should do** — with no `error` edge the call faults the flow, which is the correct default, and setting `inputs.errorHandlingEnabled: true` without the edge swallows the failure into a run that reports success. See [file-format.md — Default: off](../../../shared/file-format.md#default-off--enable-only-for-a-failure-the-flow-actually-handles).

Edge JSON shapes and all four examples (upstream→node, default→downstream, error→handler, branch→downstream): [impl.md — Wire edges](impl.md#wire-edges).

## Debug

See [impl.md — Debug](impl.md#debug). For connector mode, the most common errors are `not_authed` / 401/403 (expired connection — ping it) and `Connection not found` (wrong connector key or connection ID — re-list).