v1

latestOpenAPI 3.1.02026-08-06121424.1 KB

generator

Create Generator Interaction

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.

post/api/v1/generator

Headers

x-api-keystring

Request body

namestring 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.

rolestring required

The role the Digital Person will play (e.g., 'Customer Service Agent', 'Product Advisor').

tonestring nullable

The desired conversational tone for the Digital Person (e.g., 'Friendly'). Friendly is the default tone.

objectivesstring[] 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_sessionboolean 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.

resultsobject 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'}).

parametersobject nullable

Optional parameters to be passed through to the webhook triggered at the end of the interaction.

eventstring nullable

An optional event name. If provided, a trigger with this name will be created/updated with sample data based on the 'results'.

purposestring required

A detailed description of the overall purpose of this Digital Person interaction. This will be used to generate the system prompt.

contextobject 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_snippetstring 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_mappingobject nullable

Optional input mapping for context field.

results_mappingobject nullable

Optional output mapping for results field.

base_web_urlstring nullable

The base URL for constructing the interaction URL. Defaults to environment setting.

user_idstring nullable

An identifier for the user initiating the generation request.

avatarstring 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_idstring nullable

template_idstring nullable

template to use as a base for the interaction

voice_idstring nullable

response_length'concise' | 'moderate' | 'detailed'

timezonestring nullable

The timezone for the interaction, if specific timing is relevant (e.g., 'America/New_York').

modelstring nullable

timeout_secsinteger 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_secondsinteger 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.

welcome_messagestring nullable

An optional welcome message for the interaction. If not provided, the AI-generated welcome message will be used.

topics_to_avoidstring nullable

An optional list of topics to avoid in the interaction. If provided, the agent will avoid these topics in the interaction.

allowed_domainsstring[] 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

Successful Response

interaction_urlstring required

web_apikeystring required

Web API key for widget deployment, extracted separately from interaction URL for convenience

state'preparing' | 'ready' | 'failed'

failure_reasonstring nullable

welcome_messagestring nullable

waiting_messagestring nullable

warning_messagesstring[] nullable

topics_to_avoidstring nullable

promptstring nullable

organization_idstring nullable

interaction_idstring required

created_atstring required

namestring required

avatarstring required

style_idstring nullable

voice_idstring nullable

expires_atstring nullable required

created_by_key_idstring nullable

response_length'concise' | 'moderate' | 'detailed'

group_namestring nullable

template_idstring nullable

deleted_atstring nullable

is_deletedboolean

rolestring nullable

tonestring nullable

timezonestring nullable

imagestring nullable

metadataobject nullable