Skip to content
Nappai Documentation

API Request

The API Request component allows you to call any web service or API endpoint directly from your Nappai dashboard. You can choose the HTTP method, set headers, add query parameters, and craft a request body. After the call, the component returns the response data so you can use it in the rest of your workflow or expose it as a tool for an AI agent.

How it Works

When you configure the component, Nappai builds an HTTP request based on the fields you fill in.

  • Method – Pick GET, POST, PATCH, or PUT.
  • URLs – Enter one or more endpoint URLs, separated by commas.
  • Headers – Add any HTTP headers needed (e.g., Content-Type, Authorization).
  • Query Parameters – Append key‑value pairs to the URL.
  • Body – For POST/PUT/PATCH, supply a JSON object, a form, or build it field‑by‑field.
  • Timeout – Set how long Nappai should wait for a response before giving up.

If you paste a curl command into the Curl field, Nappai automatically parses that command and fills in the headers, body, and query parameters for you.
When Mapping Mode is turned on, you can feed the component a list of data records and it will send a separate request for each record, returning a list of responses.

The component then parses the HTTP response and outputs two items:

  • Data – The raw response body (usually JSON).
  • Tool – A formatted tool object that can be used by an AI agent if you expose the component as a tool.

Inputs

Mapping Mode

This component has a special mode called “Mapping Mode”. When you enable this mode using the toggle switch, an additional input called “Mapping Data” is activated, and each input field offers you three different ways to provide data:

  • Fixed: You type the value directly into the field.
  • Mapped: You connect the output of another component to use its result as the value.
  • Javascript: You write Javascript code to dynamically calculate the value.

This flexibility allows you to create more dynamic and connected workflows.

Input Fields

  • Body: The body to send with the request as a dictionary (for POST, PATCH, PUT). This is populated when using the CURL field.
  • Body Mode: Choose how to configure body: JSON format, create manually with individual fields, or FORM (x-www-form-urlencoded).
  • Curl: Paste a curl command to populate the fields. This will automatically configure headers and body fields.
  • Headers: The headers to send with the request as a dictionary. This is populated when using the CURL field.
  • Headers Mode: Choose how to configure headers: JSON format or create manually with individual fields.
  • Mapping Mode: Enable mapping mode to process multiple data records in batch.
  • Method: The HTTP method to use (GET, POST, PATCH, PUT).
  • Number of Body Fields: Number of body fields to be added to the request (for POST, PATCH, PUT).
  • Number of Headers: Number of headers to be added to the request.
  • Number of Query Parameters: Number of query parameters to be added to the request.
  • Query Parameters: The query parameters to append to the URL as a dictionary.
  • Query Parameters Mode: Choose how to configure query parameters: JSON format or create manually with individual fields.
  • Timeout: The timeout to use for the request.
  • URLs: Enter one or more URLs, separated by commas.
  • Tool Name: The name of the tool that will be used when this component is connected as a tool.
  • Tool Description: A detailed description of what this tool does.
  • Tools arguments metadata: Defines the arguments metadata for the tools.

Outputs

  • Data: The response body returned by the API call. This can be JSON, XML, plain text, or any format the endpoint provides.
  • Tool: A structured tool object that can be passed to an AI agent, allowing the agent to call the API directly from its conversation.

Usage Example

  1. Goal: Create a new user in an external CRM system.
  2. Configure the component:
    • Method: POST
    • URLs: https://api.example-crm.com/v1/users
    • Headers Mode → JSON 
      {
        "Content-Type": "application/json",
        "Authorization": "Bearer YOUR_ACCESS_TOKEN"
      }
    • Body Mode → JSON 
      {
        "name": "John Doe",
        "email": "john@example.com",
        "age": 30,
        "active": true
      }
    • Timeout: 30
  3. Run the workflow. The component will send the POST request and return the created user data in the Data output, which you can then feed into a “Send Email” component or store in a database.
  • Data Transformation – Manipulate the JSON response before passing it to other components.
  • Data Mapping – Connect the output of this component to other parts of your workflow.
  • HTTP Request – A simpler component that only supports GET requests; use API Request for full flexibility.

Tips and Best Practices

  • Use the Curl field to quickly import complex requests from your terminal or Postman.
  • When working with sensitive data (e.g., API keys), store them in Nappai’s secure variable store and reference them in the Headers field.
  • Enable Mapping Mode if you need to process a list of records (e.g., batch‑creating users).
  • Keep the Timeout reasonable; a very long timeout can stall your workflow.
  • Test your request with a single URL first before enabling batch processing.

Security Considerations

  • Never expose raw API keys or secrets in the component’s UI. Use Nappai’s encrypted variable storage.
  • If the API returns sensitive data, ensure downstream components handle it securely (e.g., encrypt at rest).
  • Validate the response format before using it in downstream logic to avoid injection or parsing errors.