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

# Push Prompts

`POST /v1/prompts`

## Request

- Base URL: `https://api.confident-ai.com`
- URL: `https://api.confident-ai.com/v1/prompts`
- Auth: none declared
- TypeScript: <https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/docs/v1/prompts/post.ts> (a function with typed inputs; its response is checked against the schema)

Creates a new commit for an existing prompt, or creates a new prompt with the given `alias` otherwise.

## Request body

- CreatePromptRequest
  - `alias` string, required: The unique alias of the prompt.
  - `text` string: The text content of the prompt. Supply this only if you are creating a text-based prompt.
  - `messages` PromptMessage[]: The list of messages that make up the prompt. Supply this only if you are creating a list-based prompt.
    - `role` string, required: This is the role of the message, which can be user, assistant, system, or developer.
    - `content` string, required: This is the text content of the message.
  - `interpolationType` 'MUSTACHE' | 'MUSTACHE_WITH_SPACE' | 'FSTRING' | 'DOLLAR_BRACKETS': The type of interpolation format used in the prompt to insert dynamic variables.
  - `modelSettings` ModelSettings
    - `provider` 'OPEN_AI' | 'ANTHROPIC': This is the provider of the evaluation model.
    - `name` string: This is the name of the model.
    - `temperature` number, float: This controls randomness in the model's output. Higher values make output more random.
    - `maxTokens` integer: This is the maximum number of tokens to generate.
    - `topP` number, float: This controls diversity via nucleus sampling. Lower values focus on more likely tokens.
    - `frequencyPenalty` number, float: This is the penalty for tokens based on their frequency in the text so far.
    - `presencePenalty` number, float: This is the penalty for tokens based on whether they appear in the text so far.
    - `stopSequence` string[]: This is the sequences where the model will stop generating further tokens.
    - `reasoningEffort` 'MINIMAL' | 'LOW' | 'MEDIUM' | 'HIGH': This is the level of reasoning effort for the model.
    - `verbosity` 'LOW' | 'MEDIUM' | 'HIGH': This is the verbosity level for model output.
  - `outputType` 'TEXT' | 'JSON' | 'SCHEMA': The type of output expected from the prompt.
  - `outputSchema` OutputSchema
    - `name` string, required: This is the name of the output schema.
    - `fields` OutputSchemaField[], required: This is the array of fields that define the output schema structure.
      - `id` string, required: This is the unique identifier for the schema field.
      - `name` string, required: This is the name of the schema field.
      - `type` string, required: This is the data type for schema fields.
      - `required` boolean: This indicates whether the field is required in the output.
      - `parentId` string: This is the ID of the parent field for nested structures.
  - `tools` Tool[]
    - `id` string: This is the unique identifier for the schema field.
    - `name` string, required: This is the name of the tool
    - `description` string, required: This is the description of the tool
    - `mode` 'STRICT' | 'ADDITIONAL' | 'NO_ADDITIONAL', required: This is the mode for your tool input fields
    - `structuredSchema` OutputSchema
      - `name` string, required: This is the name of the output schema.
      - `fields` OutputSchemaField[], required: This is the array of fields that define the output schema structure.
        - `id` string, required: This is the unique identifier for the schema field.
        - `name` string, required: This is the name of the schema field.
        - `type` string, required: This is the data type for schema fields.
        - `required` boolean: This indicates whether the field is required in the output.
        - `parentId` string: This is the ID of the parent field for nested structures.
  - `branch` string: The name of the branch you want to push the new commit to. Defaults to "main" if not specified.

## Response `200`

- CreatePromptResponse
  - `success` boolean, required: This is true if the prompt was successfully created.
  - `data` object, required: This maps to the prompt version id.
    - `promptId` string, required: This is the id of the prompt generated by Confident AI, not to be confused with the alias you supplied or version number.
    - `hash` string, required: This is the hash of the commit created by Confident AI for pushing this prompt, not to be confused with version number.
  - `link` string, required: This is the URL to redirect to after the prompt is created.
  - `deprecated` boolean, required: This is true if this endpoint is deprecated.

## Changes

> 54 revisions in range; 3 not diffed.

- **2026-04-07** `7375d8421ed2`: 2 info
  - added the new `ARRAY` enum value to the request property `outputSchema/fields/items/type`
  - added the new `ARRAY` enum value to the request property `tools/items/structuredSchema/fields/items/type`
- **2026-03-30** `9ef3ae42bba2`: 1 info
  - added the new optional request property `branch`

[Operation history](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/changes/v1/prompts/post.md)

---

[API](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api.md) - [All operations](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/llms.txt) - [OpenAPI document](https://skmtc.dev/confident-ai/apis/confident-ai-metrics-api/revisions/95cdde71b65e?raw)