---
title: "✨ Refine a prompt version"
method: POST
path: "/api/prompts/{prompt_id}/versions/{version_id}/refine"
tags: ["Prompts"]
---

# ✨ Refine a prompt version

`POST /api/prompts/{prompt_id}/versions/{version_id}/refine`

<Card href="https://humansignal.com/goenterprise">
        <img style="pointer-events: none; margin-left: 0px; margin-right: 0px;" src="https://docs.humansignal.com/images/badge.svg" alt="Label Studio Enterprise badge"/>
        <p style="margin-top: 10px; font-size: 14px;">
            This endpoint is not available in Label Studio Community Edition. [Learn more about Label Studio Enterprise](https://humansignal.com/goenterprise)
        </p>
    </Card>
Refine a prompt version using a teacher model and save the refined prompt as a new version.

## Path parameters

- `prompt_id` integer, required
- `version_id` integer, required

## Query parameters

- `async` boolean

## Request body

- RefinePromptRequestRequest
  - `project_id` integer, required — Project ID to target the refined prompt for
  - `teacher_model_name` string, required — Name of the model to use to refine the prompt
  - `teacher_model_provider_connection_id` integer, required — Model Provider Connection ID to use to refine the prompt

## Response `201`

Refined prompt response

- RefinedPromptResponse
  - `previous_version` ThirdPartyModelVersion, required
    - `created_at` string, date-time, required
    - `created_by` UserSimple, required — A ModelSerializer that takes additional arguments for "fields", "omit" and "expand" in order to control which fields are displayed, and whether to replace simple values with complex, nested serializations
      - `avatar` string, nullable, required
      - `email` string, email
      - `first_name` string
      - `id` integer, required
      - `last_name` string
      - `username` string, required
    - `id` integer, required
    - `max_few_shot_examples` integer, nullable — Max number of few-shot examples to include in prompts. 0 = disabled.
    - `model_display_name` string, required — Human-readable model name derived from provider_model_id.
    - `model_provider_connection` integer, nullable
    - `organization` integer, nullable
    - `parent_model` integer — Parent model interface ID
    - `prompt` string, required — Prompt to execute
    - `provider` 'OpenAI' | 'AzureOpenAI' | 'AzureAIFoundry' | 'VertexAI' | 'Gemini' | 'Anthropic' | 'Custom' — * `OpenAI` - OpenAI * `AzureOpenAI` - AzureOpenAI * `AzureAIFoundry` - AzureAIFoundry * `VertexAI` - VertexAI * `Gemini` - Gemini * `Anthropic` - Anthropic * `Custom` - Custom
    - `provider_model_id` string, required — The model ID to use within the given provider, e.g. gpt-3.5
    - `score` number, double, nullable, required
    - `title` string, required — Model name
    - `updated_at` string, date-time, required
  - `prompt` string, required — The refined prompt text
  - `reasoning` string, nullable, required — Reasoning behind the refinement
  - `refinement_job_id` string, nullable, required — Unique identifier for the refinement job
  - `refinement_status` string, nullable, required — Status of the refinement job
  - `title` string, nullable, required — Title of the refined prompt
  - `total_cost` string, nullable, required — Total cost of the refinement job (in USD)

---

[API](https://skmtc.net/humansignal/apis/label-studio-api.md) · [All operations](https://skmtc.net/humansignal/apis/label-studio-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/humansignal/label-studio-api/versions/1b113b8df950/schema)