# Parameter Configuration

Configure headers, query, body, and path parameters for your Custom Actions.

---

> **Note:** Custom Actions require a Builder plan or higher.
> [Upgrade to Builder](https://app.avcodex.com/plans)

## Parameter types

### Headers

HTTP headers sent with the request.

```json
{
  "Authorization": "Bearer {{var.API_KEY}}",
  "Content-Type": "application/json",
  "X-User-ID": "{{system.user_id}}"
}
```

### Query parameters

URL parameters appended to your endpoint.

```bash
GET https://api.example.com/rooms?site={{site}}&limit=10&page={{page}}
```

### Body parameters

JSON data sent on POST, PUT, and PATCH requests.

```json
{
  "site": "{{siteCode}}",
  "room": "{{roomName}}",
  "metadata": {
    "source": "avcodex",
    "timestamp": "{{system.timestamp}}"
  }
}
```

### Path parameters

Dynamic URL segments replaced at runtime.

```bash
https://api.example.com/sites/{{siteId}}/rooms/{{roomId}}

https://api.example.com/sites/123/rooms/456
```

## Parameter sources

### Fixed value

Static values that never change.

| Setting    | Value         |
| ---------- | ------------- |
| **Source** | Fixed value   |
| **Key**    | `api_version` |
| **Type**   | String        |
| **Value**  | `v2`          |

**Use for:** API versions, static identifiers, constant headers.

### Let AI generate

Dynamic values the agent fills in from the conversation.

| Setting             | Value                                                     |
| ------------------- | --------------------------------------------------------- |
| **Source**          | Let AI generate                                           |
| **Key**             | `search_query`                                            |
| **Type**            | String                                                    |
| **Example**         | `1200-market boardroom-4`                                 |
| **AI instructions** | `Extract the room or site identifier from the request`    |
| **Required**        | yes                                                       |

**Use for:** search queries, dynamic filters, contextual values like a site code or device hostname.

### System variables

Platform-provided runtime values.

| Variable                     | Type   | Description                |
| ---------------------------- | ------ | -------------------------- |
| `{{system.message_history}}` | Array  | Full conversation history. |
| `{{system.user_id}}`         | String | Current user's ID.         |
| `{{system.timestamp}}`       | String | Unix timestamp.            |

**Use for:** user context, audit trails, conversation analysis.

### Application variables

Reusable values defined at the agent level.

| Setting         | Value             |
| --------------- | ----------------- |
| **Source**      | Variable          |
| **Variable**    | `API_KEY`         |
| **Resolves to** | `{{var.API_KEY}}` |

**Use for:** API keys, base URLs, workspace IDs.

### Output from another Action

Use a previous action's response as input to the next one. This is how multi-step workflows work, with data flowing between API calls.

**Configuration fields**

| Setting      | Description                                  | Example                          |
| ------------ | -------------------------------------------- | -------------------------------- |
| **Source**   | Select "Output from another Action"          | -                                |
| **Action**   | Which action's output to use                 | `Get user profile`               |
| **JSONPath** | Path to extract a specific value (optional)  | `$.data.organization.id`         |
| **Context**  | Instructions for the agent on how to use it  | `Use the tech's primary org ID`  |

**How it works**

1. The prerequisite action runs first and returns data.
2. The JSONPath selector extracts the needed value (or the agent uses the full response if blank).
3. The extracted value replaces the parameter in the current action.
4. If the prerequisite has not run yet, the agent runs it first automatically.

**JSONPath examples**

```javascript
$.id                    // Top-level field: {"id": "123"} → "123"
$.data.user.email       // Nested field: {"data": {"user": {"email": "a@b.com"}}} → "a@b.com"
$.items[0].name         // First array item: {"items": [{"name": "First"}]} → "First"
$.items[*].id           // All IDs: {"items": [{"id": 1}, {"id": 2}]} → [1, 2]
$.data.users[?(@.active)] // Filtered: active users only
```

**Real-world example**

**Scenario:** open a support ticket against a tech's home org.

**Action 1: Get tech profile**
- Returns: `{"user": {"id": "u123", "org_id": "org456", "name": "John"}}`.

**Action 2: Open ticket**
- Parameter: `organization_id`.
- Source: Output from another Action.
- Action: Get tech profile.
- JSONPath: `$.user.org_id`.
- Result: parameter receives `"org456"`.

**Important: JSONPath is optional**

You have two options for extracting data:

1. **With JSONPath (precise):** specify an exact path like `$.data.id` to pull a specific value.
2. **Without JSONPath (agent-driven):** leave it blank and use the Context field to describe what you need. The agent finds the right value in the response.

**Example without JSONPath**

- Action returns: `{"user": {"id": "123", "email": "tech@integrator.com"}, "org": {"id": "456"}}`.
- Context: "Use the organization ID from the response."
- Result: the agent extracts `"456"`.

**Tips**

- JSONPath is optional. Context alone often works.
- Test JSONPath at [jsonpath.com](https://jsonpath.com) with sample data when you need precision.
- Actions with dependencies show a link icon in your action list.
- The agent picks the right value based on the context you describe.

**Use for:** multi-step workflows, data enrichment, sequential API operations.

## Data types

### String

Text values, URLs, identifiers.

```json
{
  "site": "1200-market",
  "url": "https://example.com"
}
```

### Number

Integers and decimals.

```json
{
  "rack_count": 12,
  "labor_rate": 185.00
}
```

### Boolean

True or false.

```json
{
  "active": true,
  "commissioned": false
}
```

### Object

Nested JSON.

```json
{
  "metadata": {
    "tags": ["boardroom", "priority"],
    "properties": {
      "manufacturer": "Crestron"
    }
  }
}
```

### Array

Lists of values.

```json
{
  "tags": ["q-sys", "biamp", "extron"],
  "ids": [1, 2, 3]
}
```

## AI generation guidelines

### Writing effective instructions

**Good example**

```
Generate a one-line ticket subject (max 100 chars) describing the device, the room, and the symptom. Include the site code if mentioned.
```

**Bad example**

```
Make a subject
```

### Providing sample values

Sample values teach the agent about format expectations:

| Parameter | Sample value     | What the agent learns                |
| --------- | ---------------- | ------------------------------------ |
| `phone`   | `+1-555-0123`    | Include country code with dashes.    |
| `date`    | `2024-03-15`     | Use ISO 8601 format.                 |
| `slug`    | `boardroom-4`    | Lowercase, hyphenated room slug.     |

### Required vs optional

- **Required:** the agent must provide a value or the action fails.
- **Optional:** the agent includes the value only when relevant.

## Advanced patterns

### Nested parameters

Configure complex JSON structures:

```bash
response_format.type = "json_schema"
response_format.json_schema.strict = true
response_format.json_schema.name = "analyze"

{
  "response_format": {
    "type": "json_schema",
    "json_schema": {
      "strict": true,
      "name": "analyze"
    }
  }
}
```

### Mixed sources

Combine sources in one action:

```json
{
  "api_key": "{{var.API_KEY}}",       // Variable
  "user_id": "{{system.user_id}}",    // System
  "query": "{{searchTerm}}",          // AI generated
  "limit": 10,                        // Fixed
  "org_id": "{{previousAction.org_id}}" // Dependency
}
```

### Conditional parameters

The agent decides whether to include optional parameters:

```json
{
  "filter": {
    "source": "Let AI generate",
    "required": false,
    "instructions": "Include only if the tech specified a manufacturer or room type"
  }
}
```

## Testing parameters

### 1. Use the built-in tester

Preview how parameters resolve:

```bash
URL: https://api.example.com/{{endpoint}}
Query: search={{query}}

endpoint: "rooms"
query: "boardroom-4"

GET https://api.example.com/rooms?search=boardroom-4
```

### 2. Verify variable resolution

Check that all variables resolve correctly:

- Application variables show actual values.
- System variables show placeholders.
- AI parameters show example values.

### 3. Test edge cases

- Empty optional parameters.
- Special characters in values.
- Large nested objects.
- Array parameters.

## Next steps

- [Manage variables](/docs/custom-actions/variables-and-secrets)
- [Test your actions](/docs/custom-actions/testing-and-debugging)
- [View examples](/docs/custom-actions/examples)

*AVCodex · Your AV expertise. Amplified by AI.*