Prompts API

Manage prompts and render them against live entities. All endpoints require authentication.

Prompt object

Field	Type	Description
prompt_id	Int	Unique prompt identifier (read-only)
title	String	Human-readable prompt name shown in admin
code	String	Machine identifier used to reference the prompt
placeholder	String	Hint shown in the input field when this prompt is used
prompt	String	The Liquid template body sent to the AI provider
scopes	String[]	Field paths this prompt is offered for (e.g. product.meta_title)
field_selector	String	CSS selector for the admin field this prompt targets
is_active	Boolean	Whether the prompt is available in the admin AI popup
is_modal	Boolean	Show the prompt in a modal instead of inline
is_cleanup	Boolean	Strip HTML tags from the context input before sending to the AI
is_convert2html	Boolean	Convert the AI response from Markdown to HTML before applying
is_web_search	Boolean	Allow the AI to use web search when generating the response
position	Int	Sort order in the admin prompts dropdown
frequency_penalty	Float	OpenAI-style frequency penalty (higher = less repetition)
stop_sequences	String	Comma-separated stop sequences for the model
ai_model	String	Override model for this prompt; empty falls back to the global setting
ai_provider	String	Override provider (openai, claude, gemini, grok); empty falls back to global
data_store_id	String	Knowledge-base data store the prompt should query; current to use the current entity
message_id	Int	ID of the system message attached to this prompt

Get prompt

GET /rest/V1/assistant/prompt/:promptId

Response: the prompt object.

Errors: 404 prompt not found.

List prompts

GET /rest/V1/assistant/prompts

Supports filtering and pagination.

Response:

{
  "items": [ { ... }, { ... } ],
  "search_criteria": { "filter_groups": [], "page_size": 20, "current_page": 1 },
  "total_count": 12
}

Create prompt

POST /rest/V1/assistant/prompt

Request body:

{
  "prompt": {
    "title": "Meta title",
    "code": "meta_title",
    "prompt": "Write a meta title for {{ product.name }}.",
    "is_active": true
  }
}

title, code, and prompt are required. All other fields are optional and default to empty/false/zero.

Response: the created prompt object with prompt_id assigned.

Update prompt

PUT /rest/V1/assistant/prompt/:promptId

Request body: same structure as Create prompt. Include only the fields you want to change — see partial updates.

Response: the updated prompt object.

Errors: 404 prompt not found.

Delete prompt

DELETE /rest/V1/assistant/prompt/:promptId

Response:

true

Errors: 404 prompt not found.

Render prompt

Run a prompt's Liquid template against a specified entity and get back the resolved text — without invoking the AI provider. Useful for previewing what would be sent to the model or for using the rendered prompt in a custom workflow (e.g. feeding it to your own AI agent).

POST /rest/V1/assistant/prompt/:promptId/render

Request body:

{
  "request": {
    "entity_type": "product",
    "entity_id": 42,
    "global_input": "translate to French",
    "store_id": 1,
    "target_store_id": 2,
    "is_cleanup": true
  }
}

All request fields are optional. When omitted:

• entity_type / entity_id — no entity context is resolved; only global and store variables are available.
• global_input — {{ global.input }} resolves to an empty string.
• store_id — context is built for the default store view.
• target_store_id — same as store_id.
• is_cleanup — defaults to true (HTML stripped from context values).

Supported entity_type values: product, category, page, block, order, email, kb_category, kb_article, mst_ticket, mst_blog_post, mst_blog_category, magefan_blog_post, brand.

Response:

{
  "rendered": "Write a meta title for Allegra Pullover."
}

Errors:

• 404 prompt not found
• 500 Liquid template error (returned with a LocalizedException message describing the failure)