---
title: "Create a prompt"
method: POST
path: "/v2/prompts"
tags: ["Prompts"]
---

# Create a prompt

`POST /v2/prompts`

Create a new prompt with an initial version.

**Payload Requirements**
- The prompt name must be unique within the given space.
- At least one message is required.

<Note>This endpoint is in beta, read more [here](https://arize.com/docs/ax/rest-reference#api-version-stages).</Note>

## Request body

- CreatePromptRequest — Prompt creation parameters with an initial version.
  - `space_id` string, required — ID of the space to create the prompt in
  - `name` string, required — Name of the prompt (must be unique within the space)
  - `description` string — Description of the prompt. Optional. If omitted, the prompt has no description.
  - `version` PromptVersionCreateRequest, required — Initial version configuration for a new prompt
    - `commit_message` string, required — Commit message describing this version
    - `input_variable_format` 'F_STRING' | 'MUSTACHE' | 'NONE' — The format for input variables in the prompt messages. Defaults to `F_STRING` if not provided. - `F_STRING`: Single curly braces ({variable_name}) - `MUSTACHE`: Double curly braces ({{variable_name}}) - `NONE`: **Deprecated.** Treated as `F_STRING`. Will be removed in a future version.
    - `provider` 'OPEN_AI' | 'AZURE_OPEN_AI' | 'AWS_BEDROCK' | 'VERTEX_AI' | 'ANTHROPIC' | 'CUSTOM', required — The LLM provider to use
    - `model` string — The model to use for the call. Optional. If omitted, no default model is set on the prompt version.
    - `messages` LLMMessageRequest[], required — The messages that make up the prompt template
      - `role` 'USER' | 'ASSISTANT' | 'SYSTEM' | 'TOOL', required — The role of the message author
      - `content` string, nullable — The content of the message
      - `tool_call_id` string — The ID of the tool call this message is responding to
      - `tool_calls` ToolCallRequest[] — Tool calls generated by the model
        - `id` string — The ID of the tool call
        - `type` 'FUNCTION', required — The type of tool call
        - `function` ToolCallFunctionRequest, required — The function to call (strict request form of ToolCallFunction)
          - `name` string, required — The name of the function
          - `arguments` string, required — The arguments to the function as a JSON string
    - `invocation_params` InvocationParamsRequest — Parameters for the LLM invocation in a write request (strict form of InvocationParams; leaf schemas use *Request variants)
      - `temperature` number — Sampling temperature (higher = more random)
      - `max_tokens` integer — Maximum number of tokens to generate
      - `max_completion_tokens` integer — Maximum number of completion tokens to generate
      - `top_p` number — Nucleus sampling parameter
      - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
      - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
      - `stop` string[] — Stop sequences
      - `response_format` ResponseFormatRequest — Response format configuration in a write request (strict form of ResponseFormat)
        - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
        - `json_schema` JsonSchemaConfigRequest — JSON schema configuration in a write request (strict form of JsonSchemaConfig)
          - `name` string — The name of the JSON schema
          - `description` string — A description of the JSON schema
          - `schema` object — The JSON schema object
          - `strict` boolean — Whether to enforce strict schema validation. Defaults to `false`.
      - `tool_config` ToolConfig — Tool configuration for the LLM invocation
        - `tools` ToolDefinition[] — List of tool definitions available to the model
        - `tool_choice` unknown
      - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
      - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
      - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
      - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
      - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
    - `provider_params` ProviderParamsRequest — Provider-specific parameters in a write request (strict form of ProviderParams; leaf schemas use *Request variants)
      - `azure_params` AzureParamsRequest — Azure OpenAI specific parameters in a write request (strict form of AzureParams)
        - `azure_deployment_name` string — The Azure deployment name
        - `azure_openai_endpoint` string — The Azure OpenAI endpoint URL
        - `azure_openai_version` string — The Azure OpenAI API version
      - `anthropic_headers` AnthropicHeadersRequest — Anthropic-specific headers in a write request (strict form of AnthropicHeaders)
        - `anthropic_beta` string[], nullable — Anthropic beta feature flags
      - `anthropic_version` string — Anthropic API version
      - `bedrock_options` BedrockOptionsRequest — AWS Bedrock options in a write request (strict form of BedrockOptions)
        - `use_converse_endpoint` boolean — Whether to use the AWS Bedrock Converse endpoint. Defaults to `false`.
      - `region` string — Region for the model deployment

## Response `201`

A prompt object with a resolved version

- PromptWithVersion — A prompt with a resolved version. Returned by Create Prompt and Get Prompt. The version is the initial version on create, or the resolved version (latest, by ID, or by label) on get.
  - `id` string, required — The prompt ID
  - `name` string, required — The prompt name
  - `description` string, nullable — The prompt description
  - `space_id` string, required — The space ID the prompt belongs to
  - `created_at` string, date-time, required — When the prompt was created
  - `updated_at` string, date-time, required — When the prompt was last updated
  - `created_by_user_id` string, required — The user ID of the user who created the prompt
  - `version` PromptVersion, required — A prompt version represents a specific snapshot of a prompt's configuration. Each version captures the messages, model settings, and parameters at a point in time. Versions are immutable once created and are identified by a commit hash.
    - `id` string, required — The prompt version ID
    - `prompt_id` string, required — The prompt ID this version belongs to
    - `commit_hash` string, required — The commit hash of this version
    - `commit_message` string, required — The commit message describing the changes in this version
    - `messages` LLMMessage[], required — The messages that make up the prompt template
      - `role` 'USER' | 'ASSISTANT' | 'SYSTEM' | 'TOOL', required — The role of the message author
      - `content` string, nullable — The content of the message
      - `tool_call_id` string — The ID of the tool call this message is responding to
      - `tool_calls` ToolCall[] — Tool calls generated by the model
        - `id` string — The ID of the tool call
        - `type` 'FUNCTION', required — The type of tool call
        - `function` ToolCallFunction, required — The function to call
          - `name` string, required — The name of the function
          - `arguments` string, required — The arguments to the function as a JSON string
    - `input_variable_format` 'F_STRING' | 'MUSTACHE' | 'NONE', required — The format for input variables in the prompt messages. Defaults to `F_STRING` if not provided. - `F_STRING`: Single curly braces ({variable_name}) - `MUSTACHE`: Double curly braces ({{variable_name}}) - `NONE`: **Deprecated.** Treated as `F_STRING`. Will be removed in a future version.
    - `provider` 'OPEN_AI' | 'AZURE_OPEN_AI' | 'AWS_BEDROCK' | 'VERTEX_AI' | 'ANTHROPIC' | 'CUSTOM', required — The LLM provider to use
    - `model` string, required — The model to use for the call
    - `invocation_params` InvocationParams — Parameters for the LLM invocation
      - `temperature` number — Sampling temperature (higher = more random)
      - `max_tokens` integer — Maximum number of tokens to generate
      - `max_completion_tokens` integer — Maximum number of completion tokens to generate
      - `top_p` number — Nucleus sampling parameter
      - `frequency_penalty` number — Frequency penalty (-2.0 to 2.0)
      - `presence_penalty` number — Presence penalty (-2.0 to 2.0)
      - `stop` string[] — Stop sequences
      - `response_format` ResponseFormat — Response format configuration
        - `type` 'TEXT' | 'JSON_OBJECT' | 'JSON_SCHEMA' — The response format type
        - `json_schema` JsonSchemaConfig — JSON schema configuration (when type is JSON_SCHEMA)
          - `name` string — The name of the JSON schema
          - `description` string — A description of the JSON schema
          - `schema` object — The JSON schema object
          - `strict` boolean — Whether to enforce strict schema validation. Defaults to `false`.
      - `tool_config` ToolConfig — Tool configuration for the LLM invocation
        - `tools` ToolDefinition[] — List of tool definitions available to the model
        - `tool_choice` unknown
      - `top_k` integer — Top-K sampling parameter. A top-K of 1 means the next selected token is the most probable (greedy decoding).
      - `thinking_level` string — Controls how much reasoning the model performs before responding. Supported by Gemini 3.x models. Accepted values: 'low', 'high'.
      - `thinking_budget` integer — Maximum tokens the model may use for internal reasoning. Supported by Gemini 2.5 models. Range: 0-24576 (Flash/Flash-Lite) or 128-32768 (Pro). Set 0 to disable thinking on Flash models.
      - `reasoning_effort` string — Controls how much reasoning the model performs before responding. Supported by OpenAI o-series and GPT-5 models. o-series: 'low' | 'medium' | 'high'. GPT-5: 'none' | 'low' | 'medium' | 'high' | 'xhigh'.
      - `verbosity` string — Controls the verbosity of model output. Supported by OpenAI GPT-5 series. Accepted values: 'low' | 'medium' | 'high'.
    - `provider_params` ProviderParams — Provider-specific parameters
      - `azure_params` AzureParams — Azure OpenAI specific parameters
        - `azure_deployment_name` string — The Azure deployment name
        - `azure_openai_endpoint` string — The Azure OpenAI endpoint URL
        - `azure_openai_version` string — The Azure OpenAI API version
      - `anthropic_headers` AnthropicHeaders — Anthropic-specific headers
        - `anthropic_beta` string[], nullable — Anthropic beta feature flags
      - `anthropic_version` string — Anthropic API version
      - `bedrock_options` BedrockOptions — AWS Bedrock options
        - `use_converse_endpoint` boolean — Whether to use the AWS Bedrock Converse endpoint. Defaults to `false`.
      - `region` string — Region for the model deployment
    - `created_at` string, date-time, required — When the version was created
    - `created_by_user_id` string, required — The user ID of the user who created this version
    - `labels` string[] — Label names currently pointing to this version (e.g., "production", "staging"). Labels are case-sensitive.

## Other responses

- `400` — Invalid request
- `401` — Authentication is required
- `403` — Insufficient permissions to access this resource
- `409` — Resource conflict
- `422` — Unprocessable entity
- `429` — Rate limit exceeded

---

[API](https://skmtc.net/arize-ai/apis/arize-rest-api.md) · [All operations](https://skmtc.net/arize-ai/apis/arize-rest-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/arize-ai/arize-rest-api/versions/2ce448f1de13/schema)