---
title: "Shortcode Reference"
slug: shortcodes
type: reference
plugin: huxx-connect
summary: "Complete attribute reference for [huxx_api] and its aliases [huxx_connect_api] and [huxx_connect], including output rules, error strings, filters, and Pro formatter attributes."
keywords: [shortcode, reference, attributes, huxx_api, format]
version_added: 1.2.5
version_updated: 1.2.5
level: advanced
related: [display-data-with-shortcodes, keys-syntax, template-functions]
---

Task-oriented recipes: [Display Data with Shortcodes](/docs/connect/how-to/display-data-with-shortcodes/).

## Syntax

```
[huxx_api api_id="demo_api" endpoint_id="get_products"]
```

Three names register the same handler with identical attributes:

| Shortcode | Status |
|---|---|
| `[huxx_api]` | Preferred short form (mirrors `huxx_api()`) |
| `[huxx_connect_api]` | Long form (mirrors `huxx_connect_api()`) |
| `[huxx_connect]` | Legacy alias |

Source: `src/Frontend/Shortcodes.php` (all attributes verified against `shortcode_atts()` in `render()`).

## Attributes

| Name | Type | Default | Since | Description |
|---|---|---|---|---|
| `api_id` | string | `""` | 1.1.0 | **Required.** The API slug id. |
| `endpoint_id` | string | `""` | 1.1.0 | **Required.** The endpoint slug id. |
| `api` | string | `""` | 0.1.0 | Fallback alias for `api_id`; used only when `api_id` is empty. |
| `endpoint` | string | `""` | 0.1.0 | Fallback alias for `endpoint_id`; used only when `endpoint_id` is empty. |
| `debug` | string | `"false"` | 0.1.0 | `"true"` renders error details on failure — only for users with the `manage_huxx_connect` capability (see Output rules). Any other value is treated as false. |
| `endpoint_variables` | string | `""` | 0.1.0 | Path variable values. Indexed: `"123,456"` maps by position. Named: `"post_id=123,cid=5"` maps by name. Auto-detected: any `=` in any segment switches to named mode. |
| `query_variables` | string | `""` | 0.1.0 | `key=value` pairs, comma-separated. Merged over saved query parameters; runtime wins. |
| `body_variables` | string | `""` | 0.1.0 | `key=value` pairs, comma-separated. Colon namespacing sets multipart file metadata: `"avatar:filename=a.jpg,avatar:is_file=true"`. A flat entry for the same field becomes its `value` property. |
| `body_json` | string | `""` | 0.5.0 | A complete JSON object for the request body. Takes precedence over `body_variables`. Ignored if it does not decode to an array/object. |
| `keys` | string | `""` | 0.1.0 | Extraction path(s) applied to array responses. The `[]` wildcard cannot be used here — WordPress ends the shortcode at the first `]`; use `huxx_api()` in PHP for wildcard paths. See [keys Syntax Reference](/docs/connect/reference/keys-syntax/). |
| `format` | string | `""` | 0.1.0 | `"no_display"`: execute the request, render nothing. With Pro: `"html"` and `"number_format(N)"` (see below). Any other value falls through to default rendering. |

Parsing notes:

- `endpoint_variables`, `query_variables`, and `body_variables` split pairs on `,` — values cannot contain commas. Keys cannot contain `=`; values may (the split on `=` keeps the remainder intact).
- Pairs without an `=` in `query_variables`/`body_variables` are dropped.
- `endpoint_variables`, `query_variables`, `body_variables`, `body_json`, and `keys` pass through `sanitize_text_field()` before parsing; the other attributes are not sanitized by the handler.

### One example per attribute

| Attribute | Example |
|---|---|
| `api_id` / `endpoint_id` | `[huxx_api api_id="demo_api" endpoint_id="get_products"]` |
| `api` / `endpoint` | `[huxx_api api="demo_api" endpoint="get_products"]` |
| `debug` | `[huxx_api api_id="demo_api" endpoint_id="get_products" debug="true"]` |
| `endpoint_variables` | `[huxx_api api_id="demo_api" endpoint_id="product_detail" endpoint_variables="1"]` |
| `query_variables` | `[huxx_api api_id="demo_api" endpoint_id="get_products" query_variables="limit=2,skip=10"]` |
| `body_variables` | `[huxx_api api_id="demo_api" endpoint_id="add_product" body_variables="title=Coffee Mug"]` |
| `body_json` | `[huxx_api api_id="demo_api" endpoint_id="add_product" body_json='{"title": "Coffee Mug"}']` |
| `keys` | `[huxx_api api_id="demo_api" endpoint_id="get_products" keys="products.0.title"]` |
| `format` | `[huxx_api api_id="demo_api" endpoint_id="get_products" format="no_display"]` |

## Pro formatter attributes

Pro passthrough attributes — declared by the free shortcode, acted on by HuxxConnect Pro's `huxx_connect/shortcode/format_output` filter (Pro source: `src/Features/HtmlFormatter/`). Without Pro active they have no effect. `html_*`/`img_*` apply when `format="html"` and the result is an array.

| Name | Type | Default | Since | Description |
|---|---|---|---|---|
| `html_tag` | string | `""` | 1.0.0 | Wrapper element per value: `div`, `li`, or `span` (whitelist; empty or anything else renders as `div`). `li` values get an outer `<ul>`; others an outer `<div>`. Both outers carry `class="huxx-connect-html huxx-connect-outer-wrap"`. |
| `html_labels` | string | `""` | 1.0.0 | `"true"`, `"1"`, or `"yes"` renders each string key as a `<span class="huxx-connect-label">` label, title-cased (`user_name` → `User Name`). Off by default; numeric keys never get labels. |
| `html_url` | string | `""` | 1.0.0 | Dot path to the URL value used for link rendering (commas are converted to dots for WPGetAPI-style paths). |
| `html_to_link` | string | `""` | 1.0.0 | Key whose value is wrapped in `<a>` using the `html_url` value. |
| `img_key` | string | `""` | 1.0.0 | Key whose value is rendered as an `<img>`. |
| `img_prepend` | string | `""` | 1.0.0 | URL prefix prepended to `img_key` values (for APIs returning relative image paths). |
| `img_link` | string | `""` | 1.0.0 | Dot path to the URL for wrapping the `<img>` in `<a>` (commas converted to dots). |

`format` values handled by Pro:

| Value | Effect |
|---|---|
| `html` | Array result rendered as nested HTML per the attributes above. |
| `number_format(N)` | Numeric result rendered with `N` decimal places (e.g. `number_format(2)`). |

Example — `product_detail` is a GET endpoint with the path `/products/{0}`:

```
[huxx_api api_id="demo_api" endpoint_id="product_detail" endpoint_variables="1" keys="{title},{price}" format="html" html_tag="li" html_labels="true"]
```

Output (whitespace added for readability):

```html
<ul class="huxx-connect-html huxx-connect-outer-wrap">
    <li class="huxx-connect-title"><span class="huxx-connect-label">Title</span> Essence Mascara Lash Princess</li>
    <li class="huxx-connect-price"><span class="huxx-connect-label">Price</span> 9.99</li>
</ul>
```

## Output rules

Applied in order after the request completes:

1. **Missing ids** — the shortcode returns the literal text `HuxxConnect: "api_id" attribute is required.` or `HuxxConnect: "endpoint_id" attribute is required.`
2. **`format="no_display"`** — request executes; output is an empty string.
3. **Error, `debug="false"`** — empty string.
4. **Error, `debug="true"`** — an `ErrorResponse` renders as pretty-printed JSON in `<pre class="huxx-connect-error">` only for users with the `manage_huxx_connect` capability; every other visitor gets an empty string. Exception: when the HTTP request itself fails, the executor's debug mode converts the `ErrorResponse` to an array before the shortcode sees it, so it renders through rule 6 instead — publicly. Do not leave `debug="true"` on published pages.
5. **`keys` extraction** — applied only when the response is an array.
6. **Array result** — pretty-printed JSON in `<pre class="huxx-connect-response">`.
7. **String result** — HTML-escaped in `<pre class="huxx-connect-response">`. The `huxx_connect/shortcode/allow_raw_html` filter (default `false`) switches to `wp_kses_post()` sanitized output instead.
8. **Scalar/null result from `keys`** — JSON-encoded in the same `<pre>` block (so a `null` miss is visible).
9. **Anything else** — empty string.

## Filters

All receive the parsed attribute array `$a`. Defined in `src/Frontend/Shortcodes.php`:

| Filter | Signature | Purpose |
|---|---|---|
| `huxx_connect/shortcode/attributes` | `( array $a, array|string $atts ) : array` | Modify merged attributes before execution. |
| `huxx_connect/shortcode/can_execute` | `( bool $can_execute, array $a ) : bool` | Return `false` to suppress execution (e.g. logged-in visitors only). Default `true`. |
| `huxx_connect/shortcode/format_output` | `( ?string $output, mixed $result, array $a ) : ?string` | Return a non-null string to replace default rendering (used by Pro's formatter). |
| `huxx_connect/shortcode/allow_raw_html` | `( bool $allow_raw, array $a ) : bool` | Allow sanitized HTML for string results. Default `false`. |

Request-lifecycle hooks fired during execution are documented separately: [`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).

## Notes

- Requests triggered by any of the three shortcode names are tagged `shortcode` in the request log.
- The `shortcode_atts()` filter hook name is `shortcode_atts_huxx_connect` for all three registered names.