Sign in

v51

latestOpenAPI 3.0.0raw.githubusercontent.com2026-08-014102371.0 MB
AI

Propose an improved AI prompt based on selected audits.

Generates a prompt improvement proposal asynchronously using Gemini, based on the selected completed audits. Returns 202 Accepted immediately with status progressing; poll GET /aipromptproposals/{id} for completion. All selected audits must belong to the same AI and reference the AI's current prompt version.

post/aipromptproposals

Request body

ai_idstring uuid required

The AI participant whose prompt should be improved.

audit_idsstring[] required

The completed AI audits to use as evidence for the proposal.

languagestring

BCP47 language code for proposal output (e.g. "en-US", "ko-KR"). Defaults to "en-US".

Response

Proposal accepted and running in background.

idstring uuid

The unique identifier of the prompt proposal.

customer_idstring uuid

The customer who owns this proposal.

ai_idstring uuid

The AI participant whose prompt is being improved. Returned from the GET /ais response.

audit_idsstring[]

Ordered list of AI audit IDs the proposal was derived from. Returned from the GET /aiaudits response.

basis_prompt_history_idstring uuid

The prompt history snapshot the proposal was generated against.

original_promptstring

The basis prompt text captured at proposal time.

proposed_promptstring

The Gemini-generated improved prompt. Empty until status is completed.

rationalestring

Gemini's explanation for the proposed prompt change. Empty until status is completed.

status'progressing' | 'completed' | 'failed' | 'accepted' | 'rejected' | 'expired'

Status of the AI prompt proposal.

errorstring

Canonicalized failure reason if status is failed or expired.

applied_prompt_history_idstring uuid

The prompt history ID created when this proposal was accepted. Empty until accepted.

tm_createstring date-time

Timestamp when the proposal was created.

tm_updatestring date-time nullable

Timestamp when the proposal was last updated.

tm_deletestring date-time nullable

Timestamp when the proposal was deleted.

Example response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "customer_id": "7c4d2f3a-1b8e-4f5c-9a6d-3e2f1a0b4c5d",
  "ai_id": "550e8400-e29b-41d4-a716-446655440000",
  "audit_ids": [
    "550e8400-e29b-41d4-a716-446655440001",
    "550e8400-e29b-41d4-a716-446655440002"
  ],
  "basis_prompt_history_id": "550e8400-e29b-41d4-a716-446655440000",
  "original_prompt": "You are a helpful support assistant.",
  "proposed_prompt": "You are a helpful and empathetic support assistant. Always confirm the customer's issue before proposing a fix.",
  "rationale": "The audits showed the assistant moved to solutions before fully acknowledging the customer's concern.",
  "status": "progressing",
  "error": "evaluator_unavailable",
  "applied_prompt_history_id": "550e8400-e29b-41d4-a716-446655440000",
  "tm_create": "2026-01-15T09:30:00.000000Z",
  "tm_update": "2026-01-15T09:30:00.000000Z",
  "tm_delete": "2026-01-15T09:30:00.000000Z"
}