API Call (API_CALL)

Calls a web service (REST API) and passes its answer on. Use it as a step, or connect it to an Agent’s Tools port so the agent can call the service itself.

Category: Data Sources · Deployed: yes · Tool-capable: yes

Ports

Port Kind Purpose

Input (in_input)

Input

Optional. A JSON object from the previous module that can replace the address, method, body or headers for this run (see below)

Response (out_response)

Output

The answer of the service (see Result)

Tool (tool_mcp)

Tool

Connect it to an Agent’s Tools port to let the agent call the service itself

Properties

Field Required Meaning

URL (url)

Yes

The address to call. The previous module can replace it with a JSON field url

Method (method)

Yes

GET reads data, POST sends new data, PUT and PATCH change data, DELETE removes it. You type it as text. Upper and lower case do not matter

Description (description)

No, but needed as a tool

Meant to tell the agent what the service does. See the note under As a tool

Headers (headers)

No

Extra request headers as a JSON object, for example {"Content-Type": "application/json"}. If the text is not valid JSON, the headers are left out without an error message

Body (body)

No

The data to send, usually for POST, PUT or PATCH

Auth Type (authType)

No

NONE (default), BEARER (a token) or BASIC (user name and password). For an API key in its own header, put it into Headers instead

Auth Value (authValue)

Needed with BEARER and BASIC

For BEARER: the token. For BASIC: username:password as plain text. The module encodes it for you, so do not encode it yourself. The field is hidden like a password. A header named Authorization in Headers wins over Auth Type

Response JSONPath (responseJsonPath)

No

Passes on only one field of the answer, for example $.choices[0].message.content. Empty → the whole answer is passed on. If the answer is not JSON or the field is not found, the whole answer is passed on too, without an error message

Timeout (s) (timeoutSeconds)

No

How long to wait for the service, in seconds. Default: 30. It applies to making the connection and to waiting for the answer. Higher → slow services can answer. Lower → a stuck call fails sooner

Both URL and Method must be filled in. If one is empty, the pipeline cannot be assigned to an agent, and the designer lists the missing field. If a saved pipeline is deployed anyway, the module is left out. If it was connected to an Agent’s Tools port, it is removed from that agent’s tools too.

What the previous module can send (step)

When the previous module sends a JSON object, these fields are read:

Input field Effect

url

Replaces the configured address

method

Replaces the method

body

Replaces the body. It must be text

headers

Adds headers to the configured ones. A header with the same name replaces the configured one

Anything else — plain text, or a JSON object without these fields — runs the call as configured.

As a tool

Connected to an Agent’s Tools port, the agent can call the module without any input. Then the configured call runs. The agent may also send its own url, method, body and headers. Each of them replaces the configured value for that call.

  • Credentials stay with the configured service. If the agent changes the address to a different server (another host, port or http instead of https), the module does not send the configured Auth Type and Auth Value. It also drops configured Authorization, Proxy-Authorization and Cookie headers for that call. Headers with these names that the agent sends itself are always ignored.

  • The agent learns only the method and the address. The text the agent sees names the configured method and address and says that the call can be made without arguments. The Description field is sent along with the pipeline, but the agent server does not use it at present. Put what the service does into the agent’s own instructions.

Result

  • As a step, the output is the text HTTP <status>, a line break, and then the body of the answer. For example HTTP 200 followed by the JSON. The next module sees this whole text, not only the JSON. With Response JSONPath set, the body part is only the picked field.

  • As a tool, the agent gets the status number and the body as separate values.

  • An error status does not stop the run. A 404 or 500 answer is passed on like any other answer, with its status.

  • If the service cannot be reached or does not answer in time, the step fails with an error.

Use cases

  • Fetch data mid-pipeline: Scheduler → API Call → Agent summarises the answer.

  • As a tool, so the agent looks things up on demand.

  • Push a result outward: Agent → API Call posting to a webhook or ticket system.

  • Chained calls: the first answer builds the next request through the input fields. Put a Template between them to build the JSON.

Notes

  • Use Response JSONPath to hand the next module or the agent one clean value instead of a whole JSON document. Answers get easier to use and cheaper, because the model reads less.

  • The service must be reachable from inside the agent server’s container. localhost there means the agent server itself, not your computer.

  • Auth Value is not part of an export. It is left out when you export a pipeline, so enter it again after an import. Headers are exported as they are. Do not put secrets into Headers if you share exports. Use Auth Type and Auth Value instead.

  • A call that changes data (POST, PUT, PATCH, DELETE) is only as safe as the service’s own rights. As a tool, the agent can pick another method and address, so give the service a user that may only do what you want.