Automate Prompt Management

Overview

Instead of manually creating and updating prompts on the platform, you can automate prompt management via the Confident API. This allows you to:

• Push new prompt commits from your codebase or CI/CD pipeline
• Promote commits to versions programmatically
• Optionally configure model settings, output type, and tools to track alongside prompts
• Integrate prompt management into your development workflow

Push Prompt Commits

Push a new commit of a prompt to Confident AI. If the prompt alias doesn't exist, it will be created automatically. Every push creates a new commit that tracks your changes.

For text prompts:

from confident_ai import ConfidentAI
from confident_ai.prompts import TextPromptInput

client = ConfidentAI()

result = client.prompts.push(
    prompt=TextPromptInput(
        text="Hello, {{name}}! How can I help you today?",
        alias="greeting"
    ),
)

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.prompts.push(
  {
    text: "Hello, {{name}}! How can I help you today?",
    alias: "greeting"
  },
);

curl -X POST "https://api.confident-ai.com/v2/prompts" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "text": "Hello, {{name}}! How can I help you today?",
  "alias": "greeting"
}'

For messages prompts:

from confident_ai import ConfidentAI
from confident_ai.prompts import MessagesPromptInput, PromptMessage

client = ConfidentAI()

result = client.prompts.push(
    prompt=MessagesPromptInput(
        messages=[
            PromptMessage(
                role="system",
                content="You are a helpful assistant."
            ),
            PromptMessage(
                role="user",
                content="Hello, {{name}}! How can I help you today?"
            )
        ],
        alias="greeting"
    ),
)

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.prompts.push(
  {
    messages: [
        {
          role: "system",
          content: "You are a helpful assistant."
        },
        {
          role: "user",
          content: "Hello, {{name}}! How can I help you today?"
        }
      ],
    alias: "greeting"
  },
);

curl -X POST "https://api.confident-ai.com/v2/prompts" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{
  "messages": [
    {
      "role": "system",
      "content": "You are a helpful assistant."
    },
    {
      "role": "user",
      "content": "Hello, {{name}}! How can I help you today?"
    }
  ],
  "alias": "greeting"
}'

• One kind per prompt: a push must be the same kind, text or messages, as the prompt's existing type.
• Branches: commits go to main unless you set branch. A branch that doesn't exist yet is created from main.
• Interpolation type: interpolation_type sets how variables are written, and defaults to FSTRING. See Interpolation types.
• Model settings, output type and tools: all optional. See Adding Model Configs and What about Tools?.

Each push creates a new commit automatically. When you're ready to mark a commit as a stable release, you can promote it to a version. Version numbers are controlled by Confident AI in the format 00.00.0X.

Create a Version

When you're ready to mark a commit as a stable release, you can promote it to a version. Version numbers are automatically assigned by Confident AI in the format 00.00.0X (e.g., 00.00.01, 00.00.02).

from confident_ai import ConfidentAI

client = ConfidentAI()

result = client.prompts.create_version(prompt_id="<PROMPT-ID>")

import { ConfidentAI } from "confident-ai";

const client = new ConfidentAI();

const result = await client.prompts.createVersion("<PROMPT-ID>");

curl -X POST "https://api.confident-ai.com/v2/prompts/{promptId}/versions" \
  -H "CONFIDENT_API_KEY: <PROJECT-API-KEY>" \
  -H "Content-Type: application/json" \
  -d '{}'

Leave out hash to version the head commit of main. The prompt's id comes back from every push.

Once a commit is promoted to a version, you can assign labels (like staging or production) to it. Labels can only exist on versions, not commits.

Adding Model Configs

If you want to manage your model configuration alongside your prompts — tracking the prompt + model together in each commit — you can include model_settings and output_type when pushing.

This is useful when:

• You want to ensure a specific prompt always runs with a specific model and parameters
• You're A/B testing different prompt + model combinations together
• You want to centralize both prompt and model configuration in one place

To track them, pass model_settings (provider, model and parameters), output_type and output_schema when you push. Every field is described in the reference below.

Reference

Model settings

Model settings include the provider, model name, and model parameters:

Parameters

Here are all the available parameters you could set. A parameter you leave out stays unset:

Providers

Here are the list of available model providers:

Output types

You can optionally set output_type when pushing a prompt. This controls what format the LLM response should follow:

Output schema

When output_type is set to SCHEMA, you can define a structured schema that the LLM response should conform to. This is useful when you need typed, validated responses from your LLM.

An output_schema has a name and a list of fields. Each field has a name, a type (STRING, INTEGER, FLOAT, BOOLEAN, OBJECT, ARRAY or NULL) and whether it is required. To nest a field, give its parent an id and set the child's parent_id to it. Every field is listed under OutputSchema in the SDK reference.

Interpolation types

Specify how variables are interpolated in your prompts:

What about Tools?

You can create and update tools using prompts by passing them as tools when you push. Each commit pins every tool it lists at a version, so the commit tracks the exact tool configuration it was pushed with.

• Reference an existing tool by its id, and optionally the version to pin. Without a version, the latest one is pinned.
• Or use a name: the tool with that name is used, or created if there is none.
• Change a tool by sending a different mode or schema (the JSON Schema for the tool's input). That creates a new version of the tool, which this commit pins. Fields you leave out keep the values of the version being pinned.

Prompts in CI/CD

Automate prompt tracking as part of your CI/CD pipeline. A common pattern is to push prompt commits whenever your prompt files change:

name: Push Prompt Commits

on:
  push:
    paths:
      - "prompts/**"

jobs:
  push-prompts:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3

      - name: Set up Python
        uses: actions/setup-python@v4
        with:
          python-version: "3.11"

      - name: Install dependencies
        run: pip install confident-ai

      - name: Push prompts
        env:
          CONFIDENT_PROJ_API_KEY: ${{ secrets.CONFIDENT_PROJ_API_KEY }}
        run: python scripts/push_prompts.py

Your push_prompts.py script can read prompt files and push them:

from confident_ai import ConfidentAI
from confident_ai.prompts import TextPromptInput

client = ConfidentAI()

# Read your prompt content from file or config
with open("prompts/assistant.txt") as f:
    prompt_text = f.read()

client.prompts.push(prompt=TextPromptInput(alias="assistant-prompt", text=prompt_text))

print("Prompt commit pushed successfully!")

Next Steps

Now that you can push prompts programmatically, learn how to pull them into your app for usage.

Last updated on October 17, 2026