---
title: "Create Prompt"
method: POST
path: "/prompts"
tags: ["Prompts"]
---

# Create Prompt

`POST /prompts`

Create a new prompt that you can use across your AI applications. Build prompts from one or more components, and use handlebars-style variables like `{{userName}}` for personalization.

**Safe by Default:**
Creating a prompt creates a new version but doesn't activate it. Your production prompts stay unchanged until you explicitly activate the new version (via the UI or when you reference it in the Messages API). This lets you test and prepare new prompts without risk.

**Versioning:**
Every prompt is immutable and versioned with fingerprinting, so you can safely iterate and track changes over time.

## Request body

- CreatePromptRequest
  - `externalPromptId` string — Your external identifier for the prompt.
  - `name` string, required — Prompt name.
  - `description` string — Prompt description.
  - `productId` string, uuid, required — Product this prompt will map to.
  - `role` string, required — Role key in the product mapping (e.g. "agent tool").
  - `source` 'customer' | 'participant' | 'greenflash' | 'agent' — Prompt source.
  - `components` ComponentInput[], required — Array of component objects.
    - `content` string, required — The content of the component.
    - `componentId` string, uuid — The Greenflash component ID.
    - `externalComponentId` string — Your external identifier for the component.
    - `type` 'system' | 'user' | 'tool' | 'guardrail' | 'rag' | 'agent' | 'other' — Component type: system, user, tool, guardrail, rag, agent, or a custom type (other).
    - `source` 'customer' | 'participant' | 'greenflash' | 'agent' — Component source: customer, participant, greenflash, or agent.
    - `name` string — Component name.
    - `isDynamic` boolean — Whether the component content changes dynamically.

## Response `201`

Prompt created successfully

- CreatePromptResponse
  - `externalPromptId` string — The external prompt ID.
  - `promptId` string, uuid, required — The created prompt ID.
  - `versionId` string, uuid, required — The created version ID. Version is created but not activated (activation happens via UI or Messages API).
  - `componentIds` string[], required — The IDs of the created prompt components.

## Other responses

- `400` — Invalid request body
- `500` — Server error

## Changes

- **2026-02-18** `d5edd18f9685` — 2 breaking, 4 info
  - removed the enum value `endUser` of the request property `components/items/type`
  - removed the enum value `userModified` of the request property `components/items/type`
  - added the new `guardrail` enum value to the request property `components/items/type`
  - added the new `other` enum value to the request property `components/items/type`
  - …2 more
- **2025-11-24** `c1998d918478` — 1 info
  - api tag `Prompts` added
- **2025-10-29** `f1cd8a0e3bee` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/changes/prompts/post.md)

---

[API](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference.md) · [All operations](https://skmtc.dev/greenflash-ai/apis/greenflash-api-reference/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/greenflash-ai/greenflash-api-reference/revisions/c566e560677d/schema)