{
  "openapi": "3.0.3",
  "info": {
    "title": "TruScore Confidence Auditor API",
    "description": "Reviews and audits AI assistant responses, delivering an objective 1-10 confidence level score, breakdown metrics, and hallucination risk warnings. Also provides Prompt Doctor diagnostics to eliminate hallucination triggers.",
    "version": "1.3.15"
  },
  "servers": [
    {
      "url": "https://gettruscore.com",
      "description": "Production TruScore API"
    }
  ],
  "paths": {
    "/api/audit": {
      "post": {
        "operationId": "auditResponseConfidence",
        "summary": "Calculate 1-10 confidence score for an AI response",
        "description": "Analyzes an AI response against user prompt for hedging language, factual grounding, citations, logical consistency, and hallucination markers.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Audit result containing score out of 10 and detailed breakdown",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/prompt-doctor": {
      "post": {
        "operationId": "diagnoseAndOptimizePrompt",
        "summary": "Diagnose prompt flaws and construct an optimized high-confidence prompt",
        "description": "Identifies causes of hallucination or hedging in a user prompt, and generates an optimized prompt structure to maximize factual grounding.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PromptDoctorRequest"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Prompt Doctor diagnostic results and improved prompt",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PromptDoctorResponse"
                }
              }
            }
          }
        }
      }
    },
    "/api/health": {
      "get": {
        "operationId": "getHealthStatus",
        "summary": "Check auditor service health",
        "responses": {
          "200": {
            "description": "Service is healthy and operational"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "AuditRequest": {
        "type": "object",
        "required": ["response"],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The original user query or prompt asked to the LLM",
            "example": "What is the capital of Australia and when was it founded?"
          },
          "response": {
            "type": "string",
            "description": "The LLM assistant's text response to be evaluated",
            "example": "Canberra is the capital of Australia, officially founded in 1913."
          },
          "options": {
            "type": "object",
            "properties": {
              "persona": {
                "type": "string",
                "enum": ["general", "academic", "legal", "technical", "custom_medical", "custom_financial"],
                "default": "general",
                "description": "Domain rigor persona or built-in custom persona template (e.g., custom_medical, custom_financial) to calibrate weightings"
              },
              "activePersona": {
                "type": "string",
                "description": "Alias for persona ID to activate (supports general, academic, legal, technical, custom_medical, custom_financial, or a custom persona ID)"
              },
              "customPersona": {
                "type": "object",
                "description": "Inline custom persona configuration with custom weights and constraints",
                "properties": {
                  "id": { "type": "string" },
                  "name": { "type": "string" },
                  "weights": {
                    "type": "object",
                    "properties": {
                      "grounding": { "type": "number" },
                      "uncertainty": { "type": "number" },
                      "coherence": { "type": "number" },
                      "specificity": { "type": "number" }
                    }
                  },
                  "constraints": { "type": "object" }
                }
              },
              "customPersonas": {
                "type": "array",
                "description": "Array of user-defined custom persona configurations available for selection via persona or activePersona",
                "items": { "type": "object" }
              }
            }
          }
        }
      },
      "AuditResponse": {
        "type": "object",
        "properties": {
          "score": {
            "type": "number",
            "format": "float",
            "description": "Overall confidence score marked strictly out of 10",
            "example": 8.7
          },
          "grade": {
            "type": "string",
            "example": "High Confidence"
          },
          "confidenceClass": {
            "type": "string",
            "enum": ["high", "medium", "low"],
            "example": "high"
          },
          "persona": {
            "type": "string",
            "example": "general"
          },
          "personaName": {
            "type": "string",
            "example": "General"
          },
          "isCustomPersona": {
            "type": "boolean",
            "example": false
          },
          "isFabrication": {
            "type": "boolean",
            "example": false
          },
          "language": {
            "type": "string",
            "example": "en"
          },
          "detectedLanguage": {
            "type": "string",
            "example": "English"
          },
          "breakdown": {
            "type": "object",
            "properties": {
              "grounding": { "type": "number", "example": 8.5 },
              "uncertainty": { "type": "number", "example": 9.0 },
              "coherence": { "type": "number", "example": 9.5 },
              "specificity": { "type": "number", "example": 8.0 }
            }
          },
          "warnings": {
            "type": "array",
            "items": { "type": "string" },
            "example": []
          },
          "strengths": {
            "type": "array",
            "items": { "type": "string" },
            "example": ["Strong factual grounding with verified dates or citations."]
          },
          "summary": {
            "type": "string",
            "example": "High confidence (8.7/10). The response is clear, structured, and displays strong factual certainty."
          },
          "stats": {
            "type": "object"
          }
        }
      },
      "PromptDoctorRequest": {
        "type": "object",
        "required": ["prompt"],
        "properties": {
          "prompt": {
            "type": "string",
            "description": "The user prompt to analyze and optimize",
            "example": "Tell me about quantum computing"
          },
          "auditResult": {
            "type": "object",
            "description": "Optional prior audit results to inform diagnosis"
          },
          "history": {
            "type": "array",
            "description": "Optional prior conversation turns (up to 5 recent turns) for multi-turn context-aware follow-up resolution",
            "items": {
              "type": "object",
              "properties": {
                "prompt": { "type": "string" },
                "response": { "type": "string" }
              }
            }
          }
        }
      },
      "PromptDoctorResponse": {
        "type": "object",
        "properties": {
          "originalPrompt": { "type": "string" },
          "originalScore": { "type": "number" },
          "projectedScore": { "type": "number", "example": 9.2 },
          "diagnosis": {
            "type": "array",
            "items": { "type": "string" }
          },
          "actionableTips": {
            "type": "array",
            "items": { "type": "string" }
          },
          "improvedPrompt": {
            "type": "string",
            "description": "Optimized prompt revision designed for maximum factual grounding"
          },
          "contextAware": {
            "type": "boolean",
            "description": "Indicates whether multi-turn conversation history was used to resolve follow-up context",
            "example": false
          },
          "contextTopic": {
            "type": "string",
            "nullable": true,
            "description": "Extracted topic or entity from prior conversation turns when contextAware is true"
          },
          "contextSource": {
            "type": "string",
            "nullable": true,
            "description": "Source turn indicator for the resolved conversation context"
          }
        }
      }
    }
  }
}