API

The API node makes an outbound HTTP call to one of your own systems or a third-party service. It’s the workhorse for read-style lookups (member record, eligibility, order status) and write-style submissions (create ticket, post a transaction) when the recipe needs a structured response back.

Configuring the node

1. Drop the API node from the Integration category onto the canvas.
2. Open the configuration drawer:
   • Method — GET, POST, PUT, PATCH, or DELETE.
   • URL — the endpoint. Supports {{scope.variable}} interpolation (e.g. https://api.example.com/members/{{conversation.member_id}}).
   • Headers — repeater of key/value rows. Authorization headers should come from the Credential vault, not be typed inline.
   • Body (JSON) — request payload. Also supports variable interpolation. The Content-Type header defaults to application/json when a body is set and no explicit Content-Type header is provided.
   • Credential name — looks up an entry in the Credential vault by name. The matched credential’s auth type (Bearer / API key header / Basic / custom headers / API key query) is applied automatically to the outgoing request.
   • Timeout — 5 s, 10 s, or 30 s.
   • Retry once on 5xx / timeout (+2s) — when enabled (default on), the runtime retries one time after a 2-second backoff on a 5xx response or a timeout.

Output ports

• success — the receiver returned a 2xx response.
• fail — non-2xx response, network error, timeout, or a malformed credential lookup. The variables $api.lastStatus, $api.lastBody, and $api.lastLatencyMs are written so downstream nodes (e.g. a Message before a Transfer) can include error context.

Response mapping (configured outside the drawer today)

The runtime supports mapping fields from the JSON response onto recipe variables (per-row: dot-path on the response, target scope, variable name, type). Today the drawer does NOT expose an editor for these rows — the mapping has to be edited directly in the recipe JSON. Tracking fix in POSTPONED_FIXES.md PF-9 .

If you need response-driven branching today and don’t want to hand-edit JSON, route the call through an Agent node, which has a working response-mapping editor — but only do that when the call is genuinely ambiguous LLM-shaped work. For deterministic lookups, API is the right node; just accept the temporary friction.

When to use it

• Look up a customer record by ID or phone number before branching.
• Post a ticket, refill request, or order to your downstream system.
• Fetch real-time data (account balance, shipment status, eligibility) to shape the rest of the recipe.

When not to use it

• You don’t need to act on the response — use Webhook instead. Webhook adds HMAC signing and named outcome ports keyed off a discriminator field.
• The agent needs LLM-style reasoning over the response — use the Agent node, which talks to your external agent platform.

Notes

• Variable interpolation runs against the conversation, user, and recipe scopes plus the contact’s PHI fields. Real PHI values are passed through; tokenization applies to logging, not to the live request.
• An api_key_query credential is appended to the URL automatically; the audit log records the URL without the secret parameter.
• The runtime serializes the request body as-is — if you write JSON in the Body field, send the Content-Type: application/json header (or omit it and let the runtime add the default).