Output Connector Nodes
      Back to home
      1. Home
      2. 5: Automation & Workflows
      3. Output Connector Nodes

      API Node Configuration Guide

      The API Node enables Rayven workflows to send outbound HTTP requests to external systems. It is used to integrate with RESTful APIs for data exchange, command execution, or system interoperability.

      What It Does

      This node acts as an HTTP client, sending data to a target API and optionally parsing the response into the workflow. It supports GET, POST, PATCH, and other standard HTTP methods, with configurable headers, authentication, and JSON field extraction.

       Step-by-Step: How to Configure the API Node

      1. Add the node

        • Drag the API Node from the Outputs section to your workflow canvas.

      2. Connect upstream data

        • Link a node that provides data to be sent via API (e.g., formatted JSON, sensor reading, command).

      3. Open configuration

        • Double-click the API Node to open its settings window.

       Configuration Fields

       Request Basics

      Field Requirement Description
      Node Name* Required Internal identifier for the node.
      API Endpoint* Required Full URL of the API endpoint (e.g., https://api.example.com/data).
      HTTP Method* Required Select HTTP method:
      – GET, POST, PATCH, PUT, DELETE, etc.
      Payload Format* Required Format of the request payload (currently: JSON).
       

       Advanced Request Features

      Field Description
      API Bearer Token Optional bearer token for authorization. Sent as Authorization: Bearer <token>.
      Output JSON Key If provided, stores the API response body into this key in the output payload.
      Body (for POST or PATCH) JSON body to include in the request. May reference incoming fields using double brackets (e.g., [[temperature]]).
      Use Incoming Payload as Body When enabled, the full upstream JSON object is used as the POST body.
      Use URL Encoded Form If enabled, sends the payload as application/x-www-form-urlencoded instead of JSON.
       

       Headers and Cookies

       Headers

      Configure one or more headers for the request:

      Field Description
      Key Header name (e.g., Content-Type).
      Value Header value (e.g., application/json).
       

       Cookies

      Send cookies with the request:

      Field Description
      Name Cookie name.
      Value Cookie value.
       

       Payload Date Settings (Optional)

      Field Description
      Timestamp JSON Key Field name from the upstream data that contains the timestamp.
      Timestamp Format Format string to parse the timestamp (e.g., yyyy-MM-dd HH:mm:ss).
      Time Zone Interprets the timestamp using the specified time zone (e.g., UTC, UID time zone).
       

       Authentication

      Field Description
      Username Basic or digest authentication username.
      Password Password for the specified user.
      Digest Authentication Enables HTTP digest authentication instead of basic auth.
      Ignore Invalid SSL Certs If enabled, skips certificate validation for HTTPS endpoints.
       

       Output Behavior

      • The node sends a request as configured and optionally captures the response.

      • If Output JSON Key is configured, the response body is stored under that key in the output.

      • Errors (timeouts, 4xx/5xx responses) may be passed downstream depending on node error settings.

      Example Output:

       
      {
      "api_response": {
      "status": "ok",
      "value": 100
      }
      }

       Best Practices

      • Always validate the external API accepts your data structure and method.

      • Use the "Use incoming payload as body" option for dynamic payloads, especially when integrating directly from sensors or rule results.

      • Define explicit field mappings in the body when calling structured APIs (e.g., {"id": "[[uid]]", "value": [[temp]]}).

      • Use the Output JSON Key to safely isolate response data and avoid overwriting upstream payload content.

       Use Cases

      • Send telemetry to an external analytics platform

      • Notify third-party systems of device state changes

      • Push alarms to a webhook, email service, or messaging queue

      • Submit control signals or updates to external equipment APIs

       FAQ

      Q: What happens if the API endpoint is unreachable?

      A: The request will fail. If not handled, this may break the workflow. Use downstream logic to handle errors (e.g., check for statusCode, error, or null values).

      Q: Can the body reference workflow values?

      A: Yes. Use [[field_name]] syntax to substitute values from the upstream payload.

      Q: Is rate limiting handled by the node?

      A: No. If needed, apply a Queue or Throttle node upstream to control request frequency.