API Call

Reach any external HTTP endpoint from a workflow.

API Call invokes any external HTTP/HTTPS endpoint and passes the response — or the failure details — to the next skill. It is the general-purpose way for an agent to reach systems that aren't in the Apps & Services or MCP Tools catalogs.

When a service is in one of those catalogs, start there: the connector handles authentication for you. API Call is the escape hatch for everything else — your CRM, a payment gateway, a proprietary legacy system.

How it works

• Input resolution — $input (the previous skill's output) and $secret (vault secrets) can be referenced in any templatable field: the URL, headers, or body.

  • https://api.example.com/users/$input.userId

  • Authorization: Bearer $secret.token

• Request assembly — endpoint, query parameters, headers, and body are composed from the configuration.

• Execution — a blocking HTTP call. It always waits for completion, and this does not change between synchronous and asynchronous workflow modes.

• Response:

  • Success — emits the data payload.

  • Failure — fills error, statusCode, statusText; data may be null.

Worked example: notifying your CRM of a new client

A workflow processes a loan application. Once it's approved, the CRM needs the new client's details so the sales or service team can pick up the next step.

The problem. Re-keying client data from the application into the CRM is repetitive, slow, and a reliable source of errors.

The approach. After the approval step, an API Call sends the client's details straight to the CRM.

1. Point it at the CRM. In Endpoint, enter the URL your CRM exposes for creating clients — https://api.yourcrm.com/v1/clients.

Defining the API endpoint

2. Choose the method. You're creating a record, so select POST.

Choosing the HTTP method

3. Add headers. Tell the CRM what you're sending: key Content-Type, value application/json.

Adding the Content-Type header

4. Map the data. Select Key-Value (or Raw Data for complex JSON), then pull values from earlier steps:

• firstName → $input.clientDetails.firstName

• lastName → $input.clientDetails.lastName

• email → $input.clientDetails.email

5. Authorize. Select the auth type your CRM uses — API Key or Bearer.

Setting up authorization with a secret variable

Always use a $secret variable for keys and tokens — $secret.CRM_API_KEY, never the literal value. This keeps credentials out of the configuration, and lets you point test and production at different keys without editing the skill.

Trying it before you ship it

The Try Out tab runs the skill in isolation, against your sample input, without touching the rest of the workflow. Supply the values an earlier step would have produced, run it, and read the JSON response.

• 200/201 — it worked. data holds the CRM's response and error is null.

• 400/409/500 — the call reached the CRM and was rejected. error explains why.

• 0 — a network problem. The call never arrived.

Configuration reference

Field	Type	Required	Description
endpoint	string	✅	Absolute URL of the external HTTP/HTTPS endpoint.
method	GET | POST | PUT | …	✅	HTTP method.
headers	object<string, string>	—	Extra request headers.
params	object<string, string | string[]>	—	Query parameters. An array produces repeated keys.
data	string | object | buffer	—	Request body.
dataFormat	key-value | raw	—	How the body is supplied.
rawDataFormat	json | text | binary	—	Encoding, when dataFormat='raw'.
auth	object	—	Authentication helper — see below.

Auth helpers:

// basic
{ "username": "...", "password": "..." }

// bearer
{ "token": "..." }

// apiKey — supports multiple header/value pairs
{ "headers": { "X-Client-ID": "...", "X-Client-Secret": "..." } }

Multi-value query parameters. { "params": { "dataId": ["123", "234", "4343"] } } generates ?dataId=123&dataId=234&dataId=4343.

Output

Field	Type	Always	Description
data	any | null	—	Parsed response body.
statusCode	number	✅	HTTP status — 0 on network error.
statusText	string	✅	Reason phrase, e.g. OK, Conflict.
headers	object<string, string>	✅	Response headers, keys lower-cased.
error	string | null	—	Error indicator; null on success.

Success:

{
  "data": { "id": "inv_456", "amount": 1000, "status": "issued" },
  "statusCode": 201,
  "statusText": "Created",
  "headers": { "content-type": "application/json" },
  "error": null
}

Failure — a duplicate invoice:

{
  "data": { "error": { "type": "duplicate_request", "message": "Invoice already exists" } },
  "statusCode": 409,
  "statusText": "Conflict",
  "headers": { "content-type": "application/json" },
  "error": "HTTP_ERROR"
}

On an HTTP error, data still holds the external service's response body. The reason why the call failed usually lives there, not in error — which only says HTTP_ERROR.

Errors

Kind	statusCode	statusText	error	data
Network / TLS / DNS	0	""	System message, e.g. NETWORK_ERROR	null
HTTP ≥ 400	Echoes the status (400, 401, 404, 500)	Echoes the reason phrase	HTTP_ERROR	The parsed response body, if any

statusCode: 0 is the tell for "the request never got there" — as opposed to "it arrived and was refused."

Security

• Never hard-code API keys or tokens in the configuration. Inject them with $secret from the vault.

• Engine logs redact fields marked sensitive, including API Key and Authorization headers.

Testing in isolation

• Path — /skill-runtime/workflows/nodes/APICall/execute

• Method — POST

• Body:

{
  "nodeType": "API_CALL",
  "config": { },
  "input": { }
}

---

To add this skill to an agent, see Adding a Skill to the Agent.