> ## 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. # Create an AI variable > Create a new AI variable (AI research): a research/enrichment value computed per contact or company, e.g. classifications, extracted facts, findings. Do NOT use this for outreach content — personalized outbound messages belong in `POST /v1/ai-variables/ai-messages`, reusable phrase fragments in `POST /v1/ai-variables/ai-snippets`, and literal (non-AI-generated) sequences in `POST /v1/ai-variables/message-templates`. Prompt placeholders must come from the relevant fields endpoint output for this workspace; generic conversation placeholders such as `previousMessage` are not supported here. Enginy automatically converts `prompt` into the internal editor format used by the platform. Use the contact/company fields endpoints as the source of truth for prompt placeholders. Do not assume campaign-only aliases like `previousMessage` are valid in manual/public AI-variable creation. > **Required scope:** `AI_VARIABLES_WRITE` > > **Rate limit:** 30 requests per minute ## OpenAPI ````yaml https://openapi.enginy.ai/definitions.json post /v1/ai-variables openapi: 3.1.0 info: title: Enginy API version: 1.0.0 description: Public API for Enginy platform servers: - url: https://openapi.enginy.ai description: Configured server security: [] tags: - name: AI Variables description: >- Manage AI variables and discover the entity fields you can reference in prompts and entity requests. - name: Inbox description: >- Inbox endpoints for listing contact threads, reading thread messages, managing tags, and sending manual replies. - name: Workflows description: >- Build, validate, publish, run, and inspect advanced (graph) workflows, plus the block/condition catalog needed to author a workflow plan. paths: /v1/ai-variables: post: tags: - AI Variables summary: Create an AI variable description: >- Create a new AI variable (AI research): a research/enrichment value computed per contact or company, e.g. classifications, extracted facts, findings. Do NOT use this for outreach content — personalized outbound messages belong in `POST /v1/ai-variables/ai-messages`, reusable phrase fragments in `POST /v1/ai-variables/ai-snippets`, and literal (non-AI-generated) sequences in `POST /v1/ai-variables/message-templates`. Prompt placeholders must come from the relevant fields endpoint output for this workspace; generic conversation placeholders such as `previousMessage` are not supported here. Enginy automatically converts `prompt` into the internal editor format used by the platform. Use the contact/company fields endpoints as the source of truth for prompt placeholders. Do not assume campaign-only aliases like `previousMessage` are valid in manual/public AI-variable creation. > **Required scope:** `AI_VARIABLES_WRITE` > > **Rate limit:** 30 requests per minute requestBody: content: application/json: schema: type: object properties: name: type: string minLength: 1 description: Unique AI variable name. prompt: type: string minLength: 1 description: >- Prompt template. Reference entity fields with `{fieldName}` placeholders. Use `GET /v1/contacts/fields` or `GET /v1/companies/fields` to discover the valid placeholder names for this workspace. Unsupported generic placeholders such as `{previousMessage}` are rejected in manual/public AI-variable creation. model: type: - string - 'null' description: Optional model ID. Defaults to Enginy’s default AI model. outputSchema: type: object properties: type: type: string enum: - text - number - date - oneOf - url - email description: >- Controls the output format Enginy expects from the AI variable. values: type: array items: type: string description: >- Required when `type` is `oneOf`. Lists the allowed values the model should return. provideExplanation: type: boolean description: >- When true, Enginy also stores an explanation alongside the generated value. jsonSchema: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' description: >- Advanced JSON schema override used by some structured-output AI variables. default: type: text provideExplanation: false required: - type additionalProperties: false description: >- Optional output contract. Defaults to `{ "type": "text", "provideExplanation": false }`. search: type: boolean default: false description: >- Enable Deep Search for this AI variable. Defaults to `false`. entity: type: string enum: - CONTACT - COMPANY description: Entity that will store the generated value. folderId: type: - integer - 'null' exclusiveMinimum: 0 description: Optional folder ID. customWebsiteField: type: - string - 'null' description: Optional custom website field source. required: - name - prompt - entity additionalProperties: false examples: contactVariable: summary: Create a contact AI variable value: name: iceBreaker entity: CONTACT prompt: >- Write a short ice breaker using {firstName}, {jobTitle}, {company}, and {lastLinkedInPost}. outputSchema: type: text provideExplanation: true search: true companyVariable: summary: Create a company AI variable with categorical output value: name: accountPriority entity: COMPANY prompt: >- Classify {name} as High, Medium, or Low priority based on {industry}, {numberOfEmployees}, and {openJobPositions}. outputSchema: type: oneOf values: - High - Medium - Low search: true responses: '201': description: AI variable created successfully content: application/json: schema: type: object properties: status: type: string enum: - success message: type: string data: type: object properties: id: type: number description: Unique identifier for the AI variable. name: type: string description: >- Unique AI variable name. Use this exact name in prompts and entity field requests. prompt: type: string description: >- Plain-text prompt template. Field references use the `{fieldName}` syntax. model: type: - string - 'null' description: >- Model ID used to run the variable. If omitted on create, Enginy uses the default AI model. outputSchema: type: object properties: type: type: string enum: - text - number - date - oneOf - url - email description: >- Controls the output format Enginy expects from the AI variable. values: type: array items: type: string description: >- Required when `type` is `oneOf`. Lists the allowed values the model should return. provideExplanation: type: boolean description: >- When true, Enginy also stores an explanation alongside the generated value. jsonSchema: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: array items: anyOf: - type: string - type: number - type: boolean - type: 'null' - type: object additionalProperties: anyOf: - type: string - type: number - type: boolean - type: 'null' description: >- Advanced JSON schema override used by some structured-output AI variables. required: - type additionalProperties: false description: Output contract for the AI variable. search: type: boolean description: >- Enable or disable Deep Search for this AI variable. This is the only public search option. entity: type: string enum: - CONTACT - COMPANY description: Which entity stores the resulting value. folderId: type: - number - 'null' description: Folder ID used to organize the AI variable. customWebsiteField: type: - string - 'null' description: >- Optional custom website source field used by variables that crawl a specific website field. description: type: - string - 'null' description: Auto-generated variable description, when available. isPublic: type: boolean description: >- Whether the AI variable is globally public inside Enginy. archivedAt: type: - string - 'null' format: date-time description: >- Archive timestamp. Archived variables are excluded from list results unless requested. createdAt: type: string format: date-time description: Creation timestamp. updatedAt: type: string format: date-time description: Last update timestamp. required: - id - name - prompt - model - outputSchema - search - entity - folderId - customWebsiteField - description - isPublic - archivedAt - createdAt - updatedAt required: - status - message - data '400': description: >- Bad request - invalid input, folder/entity mismatch, or unsupported placeholders such as previousMessage '409': description: Conflict - AI variable name already exists for this entity security: - apiKey: [] components: securitySchemes: apiKey: type: apiKey in: header name: x-api-key ````