---
title: "Create a prompt"
method: POST
path: "/v1/ai-prompt"
tags: ["ai-prompt"]
---

# Create a prompt

`POST /v1/ai-prompt`

## Request body

- CreateAiPrompt
  - `orgId` string — org id, or null if this is a global prompt
  - `name` string, required — unique name
  - `type` 'AUTO_CHAT' | 'CHAT' | 'CHAT_SHOULD_RESPOND' | 'CHAT_SUMMARY' | 'FORM_RESPONSE_SUMMARY' | 'REPORT_RESULT_SUMMARY' | 'SCENARIO_PLANNING' | 'CQL' | 'CQL_TRANSLATE' | 'PROMPT_SUGGEST' | 'JOB_CODE_MATCH', required — usecase for this prompt
  - `parentAiPromptId` string — cascading parent prompt
  - `modelId` string — comma-separated list of preferred models in priority order. When a ModelTier is provided, the list is interpreted as: 3 entries -> [HIGH, MEDIUM, LOW]; 2 entries -> [HIGH/MEDIUM, LOW]; 1 entry -> always that model. With no tier, the first entry is used.
  - `systemPrompt` string — the value of the system prompt that will provide model context. System prompts can use CQL, and will automatically be chained together with parent prompts' system prompts
  - `userPrompt` string — the value of the user prompt. User prompts can use CQL, and by convention will use {{content}} to refer to the inner content or data provided by the end user.
  - `maxTokens` integer — Maximum number of tokens that the model can generate in response to the user prompt. This is a soft limit, and the model may generate fewer tokens.
  - `maxStringLength` integer — Maximum length of a string that the model can generate in response to the user prompt. This is a soft limit, and the model may generate shorter strings.
  - `temperature` number, double — Parameter that controls the randomness of the model's output. A value of 0.0 means the model will always choose the most likely next token, while a value of 1.0 means the model will choose tokens more randomly.
  - `topP` number, double — An alternative to temperature, called nucleus sampling. This parameter controls the number of tokens that the model considers when generating a response. A value of 1.0 means the model will consider all tokens, while a value of 0.0 means the model will only consider the most likely token.
  - `stopSequences` string[] — An optional list of stop sequences that will cause the model to stop generating tokens when encountered. This can be useful for preventing the model from generating unwanted content or going off-topic.

## Response `201`

successful operation

- AiPrompt
  - `id` string, required — globally unique id
  - `orgId` string — org id, or null if this is a global prompt
  - `name` string, required — unique name
  - `type` 'AUTO_CHAT' | 'CHAT' | 'CHAT_SHOULD_RESPOND' | 'CHAT_SUMMARY' | 'FORM_RESPONSE_SUMMARY' | 'REPORT_RESULT_SUMMARY' | 'SCENARIO_PLANNING' | 'CQL' | 'CQL_TRANSLATE' | 'PROMPT_SUGGEST' | 'JOB_CODE_MATCH', required — usecase for this prompt
  - `parentAiPromptId` string — cascading parent prompt
  - `modelId` string — comma-separated list of preferred models in priority order. When a ModelTier is provided, the list is interpreted as: 3 entries -> [HIGH, MEDIUM, LOW]; 2 entries -> [HIGH/MEDIUM, LOW]; 1 entry -> always that model. With no tier, the first entry is used.
  - `systemPrompt` string — the value of the system prompt that will provide model context. System prompts can use CQL, and will automatically be chained together with parent prompts' system prompts
  - `userPrompt` string — the value of the user prompt. User prompts can use CQL, and by convention will use {{content}} to refer to the inner content or data provided by the end user.
  - `maxTokens` integer — Maximum number of tokens that the model can generate in response to the user prompt. This is a soft limit, and the model may generate fewer tokens.
  - `maxStringLength` integer — Maximum length of a string that the model can generate in response to the user prompt. This is a soft limit, and the model may generate shorter strings.
  - `temperature` number, double — Parameter that controls the randomness of the model's output. A value of 0.0 means the model will always choose the most likely next token, while a value of 1.0 means the model will choose tokens more randomly.
  - `topP` number, double — An alternative to temperature, called nucleus sampling. This parameter controls the number of tokens that the model considers when generating a response. A value of 1.0 means the model will consider all tokens, while a value of 0.0 means the model will only consider the most likely token.
  - `stopSequences` string[] — An optional list of stop sequences that will cause the model to stop generating tokens when encountered. This can be useful for preventing the model from generating unwanted content or going off-topic.
  - `usageCount` integer — The number of times this prompt has been used
  - `createId` string — created by user id
  - `createBehalfId` string — created on behalf of user id
  - `createAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `createAt` string — created timestamp
  - `updateId` string — last updated by user id
  - `updateBehalfId` string — last updated on behalf of user id
  - `updateAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `updateAt` string — last updated timestamp
  - `deleteId` string — deleted by user id
  - `deleteBehalfId` string — deleted on behalf of user id
  - `deleteAttribution` Attribution
    - `principalUserId` string
    - `agentUserIds` string[]
    - `eventId` string
    - `aiChatId` string
    - `aiToolUseId` string
    - `channel` 'WEB' | 'MOBILE' | 'SLACK' | 'TEAMS' | 'MCP'
  - `deleteAt` string — deleted timestamp

## Other responses

- `400` — invalid data
- `401` — not authorized
- `403` — permission denied

---

[API](https://skmtc.net/charthop/apis/charthop-api.md) · [All operations](https://skmtc.net/charthop/apis/charthop-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/charthop/charthop-api/versions/50a1edd6b27e/schema)