--- title: "Create Generator Interaction" method: POST path: "/api/v1/generator" tags: ["generator"] --- # Create Generator Interaction `POST /api/v1/generator` Generates a new Soul Machines interaction. This endpoint is designed to receive specifications for an AI assistant (Digital Person), including its purpose, context, objectives, and expected results. It then uses an LLM (e.g., GPT-4) to generate the necessary system prompts, welcome messages, and structured objectives for the interaction. For MCP server integration, this endpoint can be used to programmatically create and configure new Digital Person interactions/experiences based on predefined templates or dynamic inputs. The generated `interaction_url` is the expected output to the user asking to generate an interaction. ## Headers - `x-api-key` string ## Request body - GeneratorRequest — Request body for the generator endpoint, detailing the desired interaction to be created. - `name` string, nullable — The display name for the Digital Person in the conversation (e.g., 'Sarah'). If not provided, a default based on the avatar is used. - `role` string, required — The role the Digital Person will play (e.g., 'Customer Service Agent', 'Product Advisor'). - `tone` string, nullable — The desired conversational tone for the Digital Person (e.g., 'Friendly'). Friendly is the default tone. - `objectives` string[], nullable — A list of high-level objectives for the conversation to be executed in order (e.g., 'Collect user feedback', 'Troubleshoot an issue'). - `auto_end_session` boolean, nullable — Automatically end the session after the last objective is completed. If not provided, defaults to True if objectives are present otherwise, defaults to False. - `results` object, required — A dictionary defining the key pieces of information the Digital Person should aim to collect or provide. Keys are identifiers, values are descriptions (e.g., {'user_email': 'The user's email address'}). - `parameters` object, nullable — Optional parameters to be passed through to the webhook triggered at the end of the interaction. - `event` string, nullable — An optional event name. If provided, a trigger with this name will be created/updated with sample data based on the 'results'. - `purpose` string, required — A detailed description of the overall purpose of this Digital Person interaction. This will be used to generate the system prompt. - `context` object, nullable — Key-value pairs providing additional context for the AI to understand its environment or constraints or additional information. This will be added with no changes as context to the system prompt.(e.g., {'Onboarding Information': 'information goes here'}). - `knowledge_snippet` string, nullable — An optional knowledge snippet that will be added directly to the Digital Person's interaction system prompt. This should be short and brief - `context_mapping` object, nullable — Optional input mapping for context field. - `results_mapping` object, nullable — Optional output mapping for results field. - `base_web_url` string, nullable — The base URL for constructing the interaction URL. Defaults to environment setting. - `user_id` string, nullable — An identifier for the user initiating the generation request. - `avatar` string, nullable — The avatar look for the Digital Person. This will be used to choose the avatars look from a well known set of avatars. (default to '{DEFAULT_AVATAR}') - `style_id` string, nullable - `template_id` string, nullable — template to use as a base for the interaction - `voice_id` string, nullable - `response_length` 'concise' | 'moderate' | 'detailed' - `timezone` string, nullable — The timezone for the interaction, if specific timing is relevant (e.g., 'America/New_York'). - `webhook` Webhook - `url` string, required - `method` string, nullable - `headers` object, nullable - `body` object, nullable - `model` string, nullable - `timeout_secs` integer, nullable — The timeout to wait for the interaction to be fully created in seconds, default is 20 seconds. Even if 0 seconds is given a valid URL is still returned that will wait for the interaction to be created as needed. - `ttl_seconds` integer, nullable — Optional TTL in seconds for the interaction record. If 0 or negative, the record will not expire. If None, a default TTL will be applied. - `auth_settings` AuthSettings - `require_wf_org_authentication` boolean - `welcome_message` string, nullable — An optional welcome message for the interaction. If not provided, the AI-generated welcome message will be used. - `topics_to_avoid` string, nullable — An optional list of topics to avoid in the interaction. If provided, the agent will avoid these topics in the interaction. - `allowed_domains` string[], nullable — List of allowed origin URLs that can use this interaction (e.g., ['https://example.com', 'http://localhost:3000']). If None, no origin restrictions apply. ## Response `200` Successful Response - InteractionSummary — Response body for the summary and generator endpoints. - `interaction_url` string, required - `web_apikey` string, required — Web API key for widget deployment, extracted separately from interaction URL for convenience - `state` 'preparing' | 'ready' | 'failed' - `failure_reason` string, nullable - `welcome_message` string, nullable - `waiting_message` string, nullable - `warning_messages` string[], nullable - `topics_to_avoid` string, nullable - `prompt` string, nullable - `organization_id` string, nullable - `interaction_id` string, required - `created_at` string, required - `name` string, required - `avatar` string, required - `style_id` string, nullable - `voice_id` string, nullable - `expires_at` string, nullable, required - `created_by_key_id` string, nullable - `response_length` 'concise' | 'moderate' | 'detailed' - `group_name` string, nullable - `template_id` string, nullable - `deleted_at` string, nullable - `is_deleted` boolean - `role` string, nullable - `tone` string, nullable - `timezone` string, nullable - `auth_settings` AuthSettings - `require_wf_org_authentication` boolean - `image` string, nullable - `metadata` object, nullable ## Other responses - `422` — Validation Error --- [API](https://skmtc.net/soulmachines/apis/soul-machines-interactions-api.md) · [All operations](https://skmtc.net/soulmachines/apis/soul-machines-interactions-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/soulmachines/soul-machines-interactions-api/versions/4ac38edbb38a/schema)