api_request()

Make an authenticated HTTP request through a saved API integration connection. The integration supplies the auth (OAuth2, HTTP Basic, or token) so you don't hardcode credentials in your script.

Syntax

api_request(connection, url, method, spec?)

Parameters

Name	Type	Required	Description
`connection`	string	yes	Name of the API integration connection to use (HTTP Basic, Token, or OAuth2).
`url`	string	yes	The request URL. Absolute (`https://…`) is used as-is. A relative path is resolved against the integration's base URL — the configured base URL for HTTP Basic / Token connections, or (for OAuth2, which has no base URL field) the API host derived from the connection's resource-owner endpoint. If a relative path can't resolve, pass the full URL.
`method`	string	yes	`GET`, `POST`, `PUT`, `PATCH`, or `DELETE`.
`spec`	array	no	Request shape (same across all auth types): `headers`, `query`, `mode`, `data`.

spec keys

Key	Type	Description
`headers`	array \| string	Extra request headers — an assoc map `["Name" => "value"]`, a list of `"Name: Value"` strings, or a comma/newline string.
`query`	array	Query-string parameters, appended to the URL for any method.
`mode`	string	How `data` is encoded: `json` (default), `form`, or `raw`.
`data`	array \| string	Request body (ignored for `GET`). `json`/`form` accept an array; `raw` sends a string verbatim.

Returns

A structured response (the same shape as curl_request()):

[
  "ok"      => true,            // true on a 2xx with no transport error
  "status"  => 200,            // HTTP status code
  "headers" => [ ... ],        // lower-cased response header map
  "body"    => "{ ... }",      // raw response body
  "json"    => [ ... ],        // body decoded to an array (JSON or XML responses)
  "error"   => null            // transport error / "HTTP <code>" on >= 400
]

json holds the parsed body as a normal array for both JSON and XML responses (e.g. an XML API like Xero is converted automatically). The raw text is always in body. For other content types json is null.

A non-2xx response is returned in this array (with ok => false), not thrown. Only a configuration/auth failure (missing credentials, OAuth refresh failure) throws.

Example

$resp = api_request("Stripe", "https://api.stripe.com/v1/customers", "POST", [
    "mode" => "form",
    "data" => ["email" => $record["email"], "name" => $record["name"]]
]);
if ($resp["ok"]) {
    sys_log("Created customer " . $resp["json"]["id"]);
} else {
    sys_log("Stripe error " . $resp["status"] . ": " . $resp["body"], "E");
}

A relative URL against the integration's base, with a bearer/OAuth2 connection:

$resp = api_request("MyApi", "/users/" . $record["ext_id"], "GET");

Notes

Set up the connection first under your account's integrations (OAuth2 / HTTP Basic / Token).
OAuth2 access tokens are refreshed automatically when expired.
Use this instead of curl_request() whenever the endpoint is behind one of your configured integrations — it handles auth and token refresh for you.