✨ Refine a prompt version | API Reference

curl -X POST http://localhost:8000/api/prompts/1/versions/1/refine \
     -H "Authorization: Token  <api_key>" \
     -H "Content-Type: application/json" \
     -d '{
  "project_id": 1,
  "teacher_model_name": "string",
  "teacher_model_provider_connection_id": 1
}'

{
  "previous_version": {
    "created_at": "2024-01-15T09:30:00Z",
    "created_by": {
      "avatar": "string",
      "id": 1,
      "username": "string",
      "email": "string",
      "first_name": "string",
      "last_name": "string"
    },
    "id": 1,
    "model_display_name": "string",
    "prompt": "string",
    "provider_model_id": "string",
    "score": 1.1,
    "title": "string",
    "updated_at": "2024-01-15T09:30:00Z",
    "max_few_shot_examples": 1,
    "model_provider_connection": 1,
    "organization": 1,
    "parent_model": 1,
    "provider": "OpenAI"
  },
  "prompt": "string",
  "reasoning": "string",
  "refinement_job_id": "string",
  "refinement_status": "string",
  "title": "string",
  "total_cost": "string"
}

This endpoint is not available in Label Studio Community Edition. Learn more about Label Studio Enterprise

Refine a prompt version using a teacher model and save the refined prompt as a new version.

Authentication

AuthorizationToken

The token (or API key) must be passed as a request header. You can find your user token on the User Account page in Label Studio. Example:

curl https://label-studio-host/api/projects -H "Authorization: Token [your-token]"

Path parameters

prompt_idintegerRequired

version_idintegerRequired

Query parameters

asyncbooleanOptional

Whether to run the refinement asynchronously

Request

This endpoint expects an object.

project_idintegerRequired

Project ID to target the refined prompt for

teacher_model_namestringRequired>=1 character

Name of the model to use to refine the prompt

teacher_model_provider_connection_idintegerRequired

Model Provider Connection ID to use to refine the prompt

Response

Refined prompt response

previous_versionobject or null

Previous version of the prompt

promptstring

The refined prompt text

reasoningstring or null

Reasoning behind the refinement

refinement_job_idstring or null

Unique identifier for the refinement job

refinement_statusstring or null

Status of the refinement job

titlestring or null

Title of the refined prompt

total_coststring or null

Total cost of the refinement job (in USD)