Logo
Search
Docs

Endpoints — v2 builder

The layered template engine: base configs + industry templates + presets, with a validation preview before creating.

What the v2 builder is

The v2 endpoints assemble an assistant from layered parts — a base configuration, an optional industry template, a layer-2 preset, and a personality — and validate the merged result before anything is created. Assistants created here are the same assistants as everywhere else; rows additionally carry build_context (base config + preset) so they can be re-edited through v2.

GET/v2/assistants

List assistants with their v2 build context

Parameters

NameInTypeRequiredNullableRulesDB columnDescription
type query string no yes in: demo, production assistants.type
per_page query integer no no integer

Errors

StatusMeaningBody
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account

GET/v2/assistants/form-options

Everything the builder form needs (base configs, templates, presets, personalities)

Response example 200

{"success": true, "data": {"base_configs": [{"id","name"}], "industry_templates": [{"id","name","base_config_id","custom_fields"}], "layer2_presets": [{"id","key","name"}], "personalities": [{"id","name"}]}}

Errors

StatusMeaningBody
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account

POST/v2/assistants/preview

Validate the merged configuration without creating anything

Parameters

NameInTypeRequiredNullableRulesDB columnDescription
base_config_id body integer no yes required_without_all:prompt_template_id,industry_template_id|nullable|integer|exists:assistant_base_configs,id assistants.base_config_id The layered base configuration; may be derived from a template instead.
name body string yes no required|string|max:40 assistants.name
type body string no yes nullable|string|in:demo,production assistants.type
layer2_key body string no yes nullable|string|max:64 Layer-2 preset key.
prompt_template_id body integer no yes nullable|integer|exists:prompt_templates,id assistants.template_id
industry_template_id body integer no yes nullable|integer|exists:industry_templates,id
system_prompt body string no yes nullable|string assistants.model Free-form system prompt override.
first_message body string no yes nullable|string (firstMessage also accepted) assistants.first_message
end_call_message body string no yes nullable|string (endCallMessage also accepted) assistants.end_call_message
server_url body string no yes nullable|string|url assistants.webhook_url Webhook for call events.
personality_id body integer no yes nullable|integer|exists:personalities,id assistants.personality_id
metadata body object no yes nullable|array assistants.metadata
variable_values body object no yes nullable|array assistants.metadata Template variable values.

Response example 200

{"success": true, "message": "Config is valid. You can create the assistant.", "data": {"config": { … }}}

Errors

StatusMeaningBody
422 No buildable base {"success":false,"message":"base_config_id is required, or provide prompt_template_id or industry_template_id whose template has a base config."}
422 Merged config invalid {"success":false,"message":"Configuration validation failed","errors":{…}}
422 Validation failed
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account

POST/v2/assistants

Create an assistant from the layered configuration

Parameters

NameInTypeRequiredNullableRulesDB columnDescription
base_config_id body integer no yes required_without_all:prompt_template_id,industry_template_id|nullable|integer|exists:assistant_base_configs,id assistants.base_config_id The layered base configuration; may be derived from a template instead.
name body string yes no required|string|max:40 assistants.name
type body string no yes nullable|string|in:demo,production assistants.type
layer2_key body string no yes nullable|string|max:64 Layer-2 preset key.
prompt_template_id body integer no yes nullable|integer|exists:prompt_templates,id assistants.template_id
industry_template_id body integer no yes nullable|integer|exists:industry_templates,id
system_prompt body string no yes nullable|string assistants.model Free-form system prompt override.
first_message body string no yes nullable|string (firstMessage also accepted) assistants.first_message
end_call_message body string no yes nullable|string (endCallMessage also accepted) assistants.end_call_message
server_url body string no yes nullable|string|url assistants.webhook_url Webhook for call events.
personality_id body integer no yes nullable|integer|exists:personalities,id assistants.personality_id
metadata body object no yes nullable|array assistants.metadata
variable_values body object no yes nullable|array assistants.metadata Template variable values.

Errors

StatusMeaningBody
403 Creation quota reached
500 Live platform write failed {"success":false,"message":"Failed to create assistant in Cloud. Please try again."}
422 Validation failed
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account

GET/v2/assistants/{assistantId}

Retrieve one assistant with live configuration

Parameters

NameInTypeRequiredNullableRulesDB columnDescription
assistantId path string yes no uuid — the public assistant_id The assistant's public id (UUID).

Errors

StatusMeaningBody
404 Assistant not found {"success":false,"message":"Assistant not found"}
502 Live platform read failed {"success":false,"message":"Failed to load assistant from Cloud"}
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account

PUT/v2/assistants/{assistantId}

Update through the layered engine

Parameters

NameInTypeRequiredNullableRulesDB columnDescription
assistantId path string yes no uuid — the public assistant_id The assistant's public id (UUID).
base_config_id body integer no yes required_without_all:prompt_template_id,industry_template_id|nullable|integer|exists:assistant_base_configs,id assistants.base_config_id The layered base configuration; may be derived from a template instead.
name body string yes no required|string|max:40 assistants.name
type body string no yes nullable|string|in:demo,production assistants.type
layer2_key body string no yes nullable|string|max:64 Layer-2 preset key.
prompt_template_id body integer no yes nullable|integer|exists:prompt_templates,id assistants.template_id
industry_template_id body integer no yes nullable|integer|exists:industry_templates,id
system_prompt body string no yes nullable|string assistants.model Free-form system prompt override.
first_message body string no yes nullable|string (firstMessage also accepted) assistants.first_message
end_call_message body string no yes nullable|string (endCallMessage also accepted) assistants.end_call_message
server_url body string no yes nullable|string|url assistants.webhook_url Webhook for call events.
personality_id body integer no yes nullable|integer|exists:personalities,id assistants.personality_id
metadata body object no yes nullable|array assistants.metadata
variable_values body object no yes nullable|array assistants.metadata Template variable values.

Errors

StatusMeaningBody
404 Assistant not found {"success":false,"message":"Assistant not found"}
422 Not a v2 assistant {"success":false,"message":"Cannot update: no base_config_id (assistant was not created via v2)."}
500 Live platform write failed
422 Validation failed
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account

Notes

  • name is sometimes|string|max:40 on update (optional; never empty when present).

DELETE/v2/assistants/{assistantId}

Delete an assistant

Parameters

NameInTypeRequiredNullableRulesDB columnDescription
assistantId path string yes no uuid — the public assistant_id The assistant's public id (UUID).

Response example 200

{"success": true, "message": "Assistant deleted"}

Errors

StatusMeaningBody
404 Assistant not found {"success":false,"message":"Assistant not found"}
401 Missing or invalid bearer token
403 Feature assistants not enabled for the account