> ## Documentation Index
> Fetch the complete documentation index at: https://docs.enginy.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# AI Variables

> How to create, update, delete, and reference AI Variables through the Enginy OpenAPI

## Overview

AI Variables let you define reusable AI-powered fields for contacts and companies.

The new OpenAPI section covers the full lifecycle:

* List AI Variables: `GET /v1/ai-variables`
* Get one AI Variable: `GET /v1/ai-variables/{aiVariableId}`
* Create an AI Variable: `POST /v1/ai-variables`
* Update an AI Variable: `PATCH /v1/ai-variables/{aiVariableId}`
* Delete an AI Variable: `DELETE /v1/ai-variables/{aiVariableId}`
* List contact AI Variable folders: `GET /v1/ai-variables/folders/contacts`
* List company AI Variable folders: `GET /v1/ai-variables/folders/companies`
* Create, update, get, and delete folder endpoints under those same folder paths

It also adds field-discovery endpoints so you can see exactly which placeholders are valid:

* Contact fields: `GET /v1/contacts/fields`
* Company fields: `GET /v1/companies/fields`

## Mental Model

An AI Variable is defined by the prompt you write, the entity it belongs to, and the output format you expect back.

Send `prompt` as plain text and Enginy handles the internal prompt representation automatically.

## Prompt Format

Reference fields with curly braces:

```text theme={null}
Write a short intro for {firstName} at {companyName} using {jobTitle} and {lastLinkedInPost}.
```

Use the exact `id` returned by the field-discovery endpoints.

If you send an unknown placeholder, the API returns a validation error starting with `Invalid placeholders detected`.

## Request Format

### Minimal create payload

```json theme={null}
{
  "name": "iceBreaker",
  "entity": "CONTACT",
  "prompt": "Write a short intro for {firstName} at {companyName}."
}
```

### Structured create payload

```json theme={null}
{
  "name": "accountPriority",
  "entity": "COMPANY",
  "prompt": "Classify {name} as High, Medium, or Low priority based on {industry} and {numberOfEmployees}.",
  "outputSchema": {
    "type": "oneOf",
    "values": ["High", "Medium", "Low"]
  },
  "search": true
}
```

## AI Variable Fields

| Field                | Type                   | Required      | Notes                                                                                               |
| -------------------- | ---------------------- | ------------- | --------------------------------------------------------------------------------------------------- |
| `name`               | string                 | yes on create | Must be unique per entity                                                                           |
| `entity`             | `CONTACT` \| `COMPANY` | yes on create | Determines where the generated value is stored                                                      |
| `prompt`             | string                 | yes on create | Plain-text prompt template                                                                          |
| `model`              | string \| null         | no            | Optional model ID                                                                                   |
| `outputSchema`       | object                 | no            | Defaults to `{ "type": "text", "provideExplanation": false }`                                       |
| `search`             | boolean                | no            | Deep Search toggle. `true` enables Deep Search, `false` disables it                                 |
| `folderId`           | number \| null         | no            | Folder used for organization. Use the AI Variable folder endpoints to discover or manage folder IDs |
| `customWebsiteField` | string \| null         | no            | Optional custom website field source                                                                |

## `outputSchema` Format

`outputSchema` describes the expected AI output.

| Field                | Type                                                        | Notes                                                                                       |
| -------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `type`               | `text` \| `number` \| `date` \| `oneOf` \| `url` \| `email` | Required                                                                                    |
| `values`             | string\[]                                                   | Required when `type` is `oneOf`. Requests fail validation if this array is missing or empty |
| `provideExplanation` | boolean                                                     | Optional                                                                                    |
| `jsonSchema`         | JSON value                                                  | Optional advanced override                                                                  |

## `search` Toggle

`search` is a boolean:

* `true`: enable Deep Search
* `false`: disable Deep Search

## Folder Endpoints

AI Variables support folder CRUD for both entities:

* Contact folders: `GET|POST /v1/ai-variables/folders/contacts`
* Contact folder detail/update/delete: `GET|PATCH|DELETE /v1/ai-variables/folders/contacts/{folderId}`
* Company folders: `GET|POST /v1/ai-variables/folders/companies`
* Company folder detail/update/delete: `GET|PATCH|DELETE /v1/ai-variables/folders/companies/{folderId}`

Deleting an AI Variable folder does not delete the AI Variables inside it. Enginy moves those variables, and any child folders, up to the deleted folder's parent.

## Discovering Valid Field Names

Before writing prompts, fetch the available fields for the relevant entity:

### Contact fields

`GET /v1/contacts/fields`

### Company fields

`GET /v1/companies/fields`

Each field object includes:

| Field             | Meaning                                                                   |
| ----------------- | ------------------------------------------------------------------------- |
| `id`              | Exact field name to use in prompts and `fields` query params              |
| `label`           | Human-readable label                                                      |
| `fieldType`       | `STANDARD`, `AI_VARIABLE`, `CRM_FIELD`, `FORMULA_FIELD`, or `EMPTY_FIELD` |
| `dataType`        | Underlying data type                                                      |
| `editable`        | Whether the entity update endpoint accepts this field                     |
| `promptReference` | Copy-paste-ready placeholder, for example `{firstName}`                   |

For contact variables, `GET /v1/contacts/fields` includes both contact-backed placeholders and company-backed placeholders that are valid in contact prompts, such as `{companyName}`.

## Typical Flow

1. Call `GET /v1/contacts/fields` or `GET /v1/companies/fields`
2. Build your prompt with the returned field `id` values
3. Create the AI Variable with `POST /v1/ai-variables`
4. Retrieve contacts or companies with the generated field through the normal entity endpoints

## Notes

* Archived AI Variables are excluded from `GET /v1/ai-variables` unless you pass `includeArchived=true`
* Updating `prompt` causes Enginy to regenerate its internal prompt representation automatically
* Deleting an AI Variable also removes its generated smart-field values from entity records