---
title: "Template Function Reference"
slug: template-functions
type: reference
plugin: huxx-connect
summary: "Signatures, runtime argument keys, return values, and error shapes for huxx_api(), huxx_api_is_error(), huxx_api_get_error(), and their long-form equivalents."
keywords: [template functions, huxx_api, reference, PHP, error handling]
version_added: 1.2.5
version_updated: 1.2.5
level: advanced
related: [use-template-functions, shortcodes, keys-syntax]
---

Task-oriented walkthrough: [Use Template Functions in Your Theme](/docs/connect/how-to/use-template-functions/).

All functions are global, loaded on every request. Source: `src/Frontend/TemplateFunctions.php` (all signatures verified against source). The short `huxx_api*` names are the recommended forms; the long `huxx_connect_*` originals are permanent equivalents.

## huxx_api()

```php
huxx_api( string $api_id, string $endpoint_id, array $args = array() )
```

The return type is `mixed` (documented; the source declares no return type).

Executes a configured endpoint and returns the response.

### Parameters

| Name | Type | Default | Since | Description |
|---|---|---|---|---|
| `$api_id` | `string` | — | 0.1.0 | The API slug id. |
| `$endpoint_id` | `string` | — | 0.1.0 | The endpoint slug id. |
| `$args` | `array` | `array()` | 0.1.0 | Runtime arguments; see below. |

### `$args` keys

All optional. Runtime values merge over the saved endpoint configuration; runtime wins.

| Key | Type | Default | Since | Description |
|---|---|---|---|---|
| `debug` | `bool` | `false` | 0.1.0 | When `true`, a failure of the actual HTTP request returns the error as an array (see error shape below) instead of an `ErrorResponse` object. Lookup/configuration failures (unknown API or endpoint id, deactivated API, execution blocked by filter) return `ErrorResponse` objects regardless of `debug`. `huxx_api_is_error()` covers both. |
| `endpoint_variables` | `array` | — | 0.1.0 | Values for path variables. Indexed array maps by position to `{0}`, `{1}` (or positionally onto named variables); associative array maps by name to `{post_id}` etc. Values are URL-encoded on substitution. |
| `query_variables` | `array` | — | 0.1.0 | Query parameters merged over API- and endpoint-level parameters. |
| `header_variables` | `array` | — | 0.1.0 | Headers merged over the configured headers. |
| `body_variables` | `array` | — | 0.1.0 | Body parameters merged over the configured body. For multipart endpoints, a value may be a structured array with `value`, `filename`, `type`, `is_file` to override file metadata; unset fields fall back to the endpoint configuration. |
| `cache` | `int|false` | endpoint cache duration | 0.1.0 | `false` or `0` skips the cache for this call; a positive integer is the TTL in seconds. Only GET requests are cached. |
| `keys` | `string|array` | — | 0.9.0 | Extraction path(s), applied when the result is an array. A string is parsed like the shortcode attribute (brace or bare notation); an array is used as-is. See [keys Syntax Reference](/docs/connect/reference/keys-syntax/). |
| `trigger_type` | `string` | `'php_function'` | 0.9.0 | Label stored in the request log for this call (sanitized with `sanitize_key()`). |

The response format (decoded array vs. JSON string vs. raw body) is controlled by the endpoint's Results Format setting, not by a runtime argument. (The source docblock for `huxx_connect_api()` advertises a `results_format` runtime argument, but the executor never reads it — the endpoint setting is the only control.)

### Return value

`mixed`:

- Decoded array (Results Format `PHP Array`), string (`JSON String` / `Raw`), extracted value(s) when `keys` is set.
- `HuxxConnectCoreErrorResponse` on failure. With `debug => true`, failures of the actual HTTP request are returned as the error array instead; lookup/configuration failures always return the `ErrorResponse` object.
- `false` when `$api_id` or `$endpoint_id` is an empty string (no lookup is attempted).

### Example

```php
<?php
$titles = huxx_api( 'demo_api', 'get_products', array(
    'query_variables' => array( 'limit' => 2 ),
    'keys'            => 'products.[].title',
) );
print_r( $titles );
```

Output:

```
Array
(
    [0] => Essence Mascara Lash Princess
    [1] => Eyeshadow Palette with Mirror
)
```

## huxx_api_is_error()

```php
huxx_api_is_error( $response ): bool
```

The `$response` parameter accepts any value (`mixed`, documented; the source declares no parameter type).

Returns `true` when `$response` is a failure — either an `ErrorResponse` object or an array whose `_huxx_connect_error` key is `true`. Returns `false` for everything else, including `false` itself.

| Name | Type | Description |
|---|---|---|
| `$response` | `mixed` | Any value returned by `huxx_api()`. |

### Example

```php
<?php
$data = huxx_api( 'demo_api', 'get_products' );
var_dump( huxx_api_is_error( $data ) );
```

Output on success:

```
bool(false)
```

## huxx_api_get_error()

```php
huxx_api_get_error( $response ): ?array
```

The `$response` parameter accepts any value (`mixed`, documented; the source declares no parameter type).

Returns the error details as an array, or `null` when `$response` is not an error.

| Name | Type | Description |
|---|---|---|
| `$response` | `mixed` | Any value returned by `huxx_api()`. |

### Error array shape

Matches `HuxxConnectCoreErrorResponse::to_array()`:

| Key | Type | Description |
|---|---|---|
| `_huxx_connect_error` | `bool` | Always `true`. Marker key. |
| `code` | `int` | HTTP status code, or `0` for transport/configuration errors (`408` timeout and `503` connection-refused are mapped from cURL errors). |
| `message` | `string` | Human-readable message, extracted from common API error fields when available. |
| `original_response` | `mixed` | The raw underlying response or `WP_Error`, when available. |
| `context` | `array` | Additional context such as `api_id`, `endpoint_id`, `url`. |

### Example

```php
<?php
$data = huxx_api( 'demo_api', 'no_such_endpoint' );
$error = huxx_api_get_error( $data );
echo esc_html( $error['message'] );
```

Output:

```
Endpoint "no_such_endpoint" not found for API "demo_api".
```

## Long-form equivalents

Identical behavior, kept permanently for backward compatibility:

| Short form | Long form |
|---|---|
| `huxx_api()` | `huxx_connect_api()` |
| `huxx_api_is_error()` | `huxx_connect_is_error()` |
| `huxx_api_get_error()` | `huxx_connect_get_error()` |

```php
huxx_connect_api( string $api_id, string $endpoint_id, array $args = array() )
huxx_connect_is_error( $response ): bool
huxx_connect_get_error( $response ): ?array
```

## Notes

- Calls made through these functions are tagged `php_function` in the request log unless `trigger_type` overrides it.
- Deactivated APIs return an `ErrorResponse` (`API "…" is currently deactivated.`) without making a request.
- To observe or modify the outgoing request, use the request-lifecycle hooks: [`huxx_connect/request/before`](/docs/connect/reference/action-hooks/#huxx-connect-request-before), [`huxx_connect/request/args`](/docs/connect/reference/filter-hooks/#huxx-connect-request-args), [`huxx_connect/request/after`](/docs/connect/reference/action-hooks/#huxx-connect-request-after).