---
title: "Ai Helper"
method: POST
path: "/v3/ai-helper/"
tags: ["v3", "ai-helper"]
---

# Ai Helper

`POST /v3/ai-helper/`

## Request

- Base URL: `https://api.mentium.io` (the document declares no server; this is the origin it was published from)
- URL: `https://api.mentium.io/v3/ai-helper/`
- Auth: HTTP bearer

AI-assisted content generation for the frontend.

Send a JSON body with a `type` field to select the helper:

- **prompt_generator** — generates a system prompt for an AI agent.
- **prompt_rewriter** — rewrites an existing prompt based on user instructions.
- **transcript_feedback_generator** — analyzes a conversation transcript and suggests feedback.

## Headers

- `mentium-workspace-id` string, nullable

## Request body

- union
  - PromptGeneratorRequest: Request payload for the system-prompt generator helper.
    - `type` 'prompt_generator', required
    - `role` string: The role and purpose of the AI agent to generate a prompt for.
    - `context` string: Context and information the agent will have access to.
    - `tools` string[]: Tools or capabilities available to the agent.
    - `constraints` string[]: Hard rules and constraints the agent must follow.
    - `tone` string: Desired tone (e.g. professional, friendly, concise).
    - `additional_instructions` string: Any additional nuances or instructions to incorporate.
    - `available_variables` string[]: Available {{variable}} placeholders for this agent type.
    - `feedback_ids` string[]: IDs of PromptFeedback records to include as context.
  - PromptRewriterRequest: Request payload for the prompt rewriter helper.
    - `type` 'prompt_rewriter', required
    - `current_prompt` string, required: The existing prompt to rewrite.
    - `instructions` string, required: User instructions describing what to change (tone, structure, etc.).
    - `prompt_type` 'system' | 'user': Whether editing a system prompt or user prompt template.
    - `agent_name` string: Name of the agent being edited.
    - `agent_description` string: Description of the agent being edited.
    - `agent_tools` string[]: Tools available to the agent.
    - `available_variables` string[]: Available {{variable}} placeholders for this agent type.
    - `conversation_history` ConversationTurnRequest[]: Previous rewrite conversation turns for multi-turn context.
      - `role` 'user' | 'assistant', required
      - `content` string, required
    - `feedback_ids` string[]: IDs of PromptFeedback records to include as context.
  - TranscriptFeedbackGeneratorRequest: Request payload for the transcript feedback generator helper.
    - `type` 'transcript_feedback_generator', required
    - `transcript` PromptFeedbackTranscriptTurn[]: The conversation transcript to analyze.
      - `role` 'agent' | 'user', required
      - `message` string, required
    - `agent_name` string: Name of the agent.
    - `agent_description` string: Description of the agent.
    - `system_prompt` string: The agent's system prompt, so the AI can compare actual behavior against intended behavior.
  - CodeRewriterRequest: Request payload for the code rewriter helper.
    - `type` 'code_rewriter', required
    - `current_code` string: The existing Python code to rewrite. Empty for generation from scratch.
    - `instructions` string, required: User instructions describing what to change or generate.
    - `params_hint` object: Current config.params keys and values (for context).
    - `param_fields` CodeFieldHintRequest[]: Current Params class fields parsed from the code.
      - `name` string, required
      - `type` string, required: Python type annotation, e.g. 'str', 'list[int]'.
    - `output_fields` CodeFieldHintRequest[]: Current Result class fields parsed from the code.
      - `name` string, required
      - `type` string, required: Python type annotation, e.g. 'str', 'list[int]'.
    - `available_variables` UpstreamVariableHintRequest[]: Variables produced by upstream workflow nodes.
      - `path` string, required: Variable reference path, e.g. '$.node-abc.output.field'.
      - `label` string
      - `type` string: Python type annotation.
      - `source_node` string
      - `description` string
      - `nested_schema` object, nullable: Optional JSON-Schema-shaped nested type info — `properties` for objects, `items` for arrays — so the agent can index into complex types like list[dict].
    - `downstream_consumers` DownstreamConsumerHintRequest[]: Downstream workflow nodes that reference this node's Result fields.
      - `node_label` string, required
      - `node_type` string
      - `referenced_fields` string[]: Names of Result fields this downstream node currently references.
    - `conversation_history` CodeRewriterConversationTurnRequest[]: Previous conversation turns for multi-turn context.
      - `role` 'user' | 'assistant', required
      - `content` string, required

## Response `200`

Successful Response

- AIHelperResponse: Generic response returned by all AI helper variants.
  - `type` 'prompt_generator' | 'prompt_rewriter' | 'transcript_feedback_generator' | 'code_rewriter', required: Echoes the request type.
  - `result` string, required: The generated text content.
  - `chat_response` string: Conversational reply from the agent (code_rewriter only).
  - `code_changed` boolean: True iff the agent emitted a new ```python``` block (code_rewriter only).

## Other responses

- `404`: Not found
- `422`: Validation Error

---

[API](https://skmtc.dev/mentium/apis/mentium-api.md) - [All operations](https://skmtc.dev/mentium/apis/mentium-api/llms.txt) - [OpenAPI document](https://skmtc.dev/mentium/apis/mentium-api/revisions/b4ed8e59432e?raw)