Optimizations API

Run and manage prompt optimizations.

Trigger Optimization

POST /api/v1/optimizations

Request Body

{
  "promptId": "prompt_123",
  "mode": "exploratory",
  "variantCount": 3,
  "intent": {
    "targetImprovements": ["clarity", "task completion"],
    "hypothesis": "Adding examples will improve understanding"
  }
}

Required Fields

Field	Type	Description
promptId	string	Prompt to optimize

Optional Fields

Field	Type	Description
mode	string	exploratory (fast) or validation (thorough)
variantCount	number	Number of variants (1-5, default: 3)
intent	object	Optimization guidance
personaIds	string[]	Specific personas to test

Response

{
  "id": "opt_789",
  "promptId": "prompt_123",
  "status": "running",
  "mode": "exploratory",
  "variantCount": 3,
  "createdAt": "2025-01-20T14:30:00Z"
}

Status: 201 Created

List Optimizations

GET /api/v1/optimizations

Query Parameters

Parameter	Type	Description
promptId	string	Filter by prompt
status	string	Filter by status
limit	number	Max results (default: 10)

Response

{
  "data": [
    {
      "id": "opt_789",
      "promptId": "prompt_123",
      "status": "completed",
      "mode": "exploratory",
      "createdAt": "2025-01-20T14:30:00Z",
      "completedAt": "2025-01-20T14:45:00Z"
    }
  ]
}

Get Optimization

GET /api/v1/optimizations/:id

Response

{
  "id": "opt_789",
  "promptId": "prompt_123",
  "status": "completed",
  "mode": "exploratory",
  "variantCount": 3,
  "results": {
    "winnerSelected": true,
    "winningVariantId": "var_456",
    "lift": 23.5,
    "confidence": 0.97
  },
  "createdAt": "2025-01-20T14:30:00Z",
  "completedAt": "2025-01-20T14:45:00Z"
}

Status Values

Status	Description
queued	Waiting to start
running	In progress
completed	Finished with results
failed	Error occurred
stopped	Manually stopped

Get Variant Details

GET /api/v1/optimizations/:id/variants

Response

{
  "data": [
    {
      "id": "var_control",
      "name": "Control (Original)",
      "isOriginal": true,
      "content": "Original prompt content...",
      "metrics": {
        "taskCompletion": 72,
        "sentiment": 68,
        "quality": 75
      }
    },
    {
      "id": "var_456",
      "name": "Variant B",
      "isOriginal": false,
      "content": "Improved prompt content...",
      "metrics": {
        "taskCompletion": 89,
        "sentiment": 85,
        "quality": 91
      },
      "lift": 23.5,
      "isWinner": true
    }
  ]
}

Apply Variant

POST /api/v1/optimizations/:id/apply

Apply the winning variant (or a specific variant) to the prompt.

Request Body (Optional)

{
  "variantId": "var_456"
}

If variantId is not provided, applies the winning variant.

Response

{
  "success": true,
  "promptId": "prompt_123",
  "appliedVariantId": "var_456",
  "message": "Variant applied successfully"
}

Stop Optimization

POST /api/v1/optimizations/:id/stop

Request Body (Optional)

{
  "reason": "Need to modify base prompt"
}

Response

{
  "success": true,
  "status": "stopped"
}

Error Responses

Optimization Not Found

{
  "error": {
    "code": "NOT_FOUND",
    "message": "Optimization not found"
  }
}

Cannot Apply

{
  "error": {
    "code": "INVALID_STATE",
    "message": "Cannot apply variant: optimization not complete"
  }
}