{"openapi":"3.1.0","info":{"title":"ThinkOwl Quality Assurance for ThinkOwl","description":"<CENTER><img src=\"/static/ai-quality-assurance-service.png\"></CENTER><BR>\n        This is the realtime backend for quality assurance (e.g. for phone calls).\n    ","contact":{"url":"http://www.thinkowl.com/"},"license":{"name":"ThinkOwl Usage License","url":"http://www.thinkowl.com/"},"version":"v1"},"paths":{"/metrics":{"get":{"summary":"Combined Metrics","description":"Expose combined metrics from the local instrumentator and the external server.","operationId":"combined_metrics_metrics_get","responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}}}}},"/v1/setup":{"post":{"summary":"Setup","description":"Args:\n    body (QaSetup, optional): _description_. Defaults to Body().\n    tenant (str, optional): _description_. Defaults to Query().\n    desk_uuid (str, optional): _description_. Defaults to Query(None).\n    reference (str, optional): _description_. Defaults to Query().\n\nReturns:\n    AssistantResponse: _description_","operationId":"setup_v1_setup_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"desk_uuid","in":"query","required":true,"schema":{"type":"string","title":"Desk Uuid"}},{"name":"score_card_type","in":"query","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"enum":["default live email template","default live phone template","default email template","default phone template","user defined email live","user defined email","user defined phone","user defined phone live"],"title":"Score Card Type"}},{"name":"reference","in":"query","required":true,"schema":{"type":"string","title":"Reference"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QASetup"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/qa":{"post":{"summary":"Qa","description":"Processes a quality assurance request.\nArgs:\n    body (IncomingMessage): The incoming message containing the data to be processed.\n    reference (str): A reference string for the QA process.\nReturns:\n    QAResponse: The response from the QA process.","operationId":"qa_v1_qa_post","parameters":[{"name":"reference","in":"query","required":true,"schema":{"type":"string","title":"Reference"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/IncomingMessages"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QAResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/logs":{"get":{"summary":"Get Logs","description":"This endpoint is used to get the logs of a qa session.\n\nArgs:\n    reference (str, optional): the uuid of the qa session\n\nReturns:\n    Response: the logs of the qa session","operationId":"get_logs_v1_logs_get","parameters":[{"name":"reference","in":"query","required":true,"schema":{"type":"string","title":"Reference"}},{"name":"style","in":"query","required":false,"schema":{"type":"string","enum":["full","prompt","plain"],"default":"plain","title":"Style"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/drafting":{"post":{"summary":"Draft","description":"This endpoint is used to draft a message for the user.\nThe general structure is as follows:\n```json\n{\n    \"kind\": \"string\",\n    \"message\": \"string\",\n    \"agent_input\": \"string\"\n}\n```\nwhere kind is one of\n\n    - email_reply\n    - knowledge_article\n    - smart_response\n\n    - rewrite\n    - shorter\n    - longer\n    - correct_text\n\nAll commands have __message__ as input. __email_reply__ uses an additional __agent_input__ field.\n\n__rewrite__, __correct_text__, __shorter__ and __longer__ are special cases. If __rewrite__ is used, that means that __message__ containes a former message that should be corrected.\nIn this case __agent_input__ is mandatory and is used to rewrite the message.\n__shorter__ and __longer__ are used to shorten or lengthen a message. __correct_text__ will do a spelling and grammar correction of the text.\nIn all of the latter cases __agent_input__ is not usable and is ignored.","operationId":"draft_v1_drafting_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"desk","in":"query","required":true,"schema":{"type":"string","title":"Desk"}},{"name":"get_prompt","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Get Prompt"}},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"german","title":"Language"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftingPromptInput"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{},"example":{"email reply":"string","knowledge article":"```json {titles {array of strings}, text (string), language (string), short description (string)}```","smart response":"```json {title (string), text (string)}```"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/conversationQA":{"post":{"summary":"Conversationqa","operationId":"conversationQA_v1_conversationQA_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"desk_uuid","in":"query","required":true,"schema":{"type":"string","title":"Desk Uuid"}},{"name":"score_card_type","in":"query","required":true,"schema":{"anyOf":[{"type":"string"},{"type":"null"}],"enum":["default email template","default phone template","user defined email","user defined phone","default live email template","default live phone template","user defined email live","user defined phone live"],"title":"Score Card Type"}},{"name":"get_prompt","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Get Prompt"}},{"name":"have_comments","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Have Comments"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ConversationQAData"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QAResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/zweiter_drafting":{"post":{"summary":"Zweiter Draft","description":"This endpoint is used to draft a message for the user.\nThe general structure is as follows:\n```json\n{\n    \"kind\": \"string\",\n    \"message\": \"string\",\n    \"agent_input\": \"string\"\n}\n```\nwhere kind is one of\n\n    - email_reply\n    - knowledge_article\n    - smart_response\n\n    - rewrite\n    - shorter\n    - longer\n    - correct_text\n\nAll commands have __message__ as input. __email_reply__ uses an additional __agent_input__ field.\n\n__rewrite__, __correct_text__, __shorter__ and __longer__ are special cases. If __rewrite__ is used, that means that __message__ containes a former message that should be corrected.\nIn this case __agent_input__ is mandatory and is used to rewrite the message.\n__shorter__ and __longer__ are used to shorten or lengthen a message. __correct_text__ will do a spelling and grammar correction of the text.\nIn all of the latter cases __agent_input__ is not usable and is ignored.","operationId":"zweiter_draft_v1_zweiter_drafting_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"desk","in":"query","required":true,"schema":{"type":"string","title":"Desk"}},{"name":"get_prompt","in":"query","required":false,"schema":{"type":"boolean","default":false,"title":"Get Prompt"}},{"name":"language","in":"query","required":false,"schema":{"type":"string","default":"german","title":"Language"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftingPromptInput"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/DraftResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/evaluations":{"post":{"summary":"Post Evaluation","operationId":"post_evaluation_v1_evaluations_post","security":[{"HTTPBearer":[]}],"parameters":[{"name":"desk_uuid","in":"query","required":true,"schema":{"type":"string","description":"Desk UUID used for the existing tenant/desk API-key lookup.","title":"Desk Uuid"},"description":"Desk UUID used for the existing tenant/desk API-key lookup."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationRequest"}}}},"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"anyOf":[{"$ref":"#/components/schemas/EvaluationAcceptedResponse"},{"type":"object","additionalProperties":true}],"title":"Response Post Evaluation V1 Evaluations Post"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/evaluations/{evaluation_id}":{"get":{"summary":"Get Evaluation","operationId":"get_evaluation_v1_evaluations__evaluation_id__get","parameters":[{"name":"evaluation_id","in":"path","required":true,"schema":{"type":"string","title":"Evaluation Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationLookupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}},"/v1/calls/{session_id}/evaluation":{"get":{"summary":"Get Latest Call Evaluation","operationId":"get_latest_call_evaluation_v1_calls__session_id__evaluation_get","parameters":[{"name":"session_id","in":"path","required":true,"schema":{"type":"string","title":"Session Id"}}],"responses":{"200":{"description":"Successful Response","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EvaluationLookupResponse"}}}},"422":{"description":"Validation Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/HTTPValidationError"}}}}}}}},"components":{"schemas":{"ConversationQAData":{"properties":{"agent_language":{"type":"string","title":"Agent Language"},"score_card":{"anyOf":[{"$ref":"#/components/schemas/ScoreCard"},{"type":"null"}]},"messages":{"items":{"$ref":"#/components/schemas/IncomingMessage"},"type":"array","title":"Messages"}},"type":"object","required":["agent_language"],"title":"ConversationQAData","description":"This is used by conversationQA as a body.\n\nknown_user_details: A dictionary with known user details as a flat dictionary."},"DraftResponse":{"properties":{"draft":{"anyOf":[{"$ref":"#/components/schemas/KnowledgeArticle"},{"$ref":"#/components/schemas/SmartResponse"},{"type":"string"},{"type":"null"}],"title":"Draft"},"billing":{"additionalProperties":true,"type":"object","title":"Billing","default":{}},"profiling":{"additionalProperties":true,"type":"object","title":"Profiling","default":{}}},"type":"object","title":"DraftResponse","description":"Returned by the webservice, this is the response from the assistant/llm, evaluating the incoming message.\n\nAttributes:\n    draft: either Knowledge_article, Smart_response, or StringResponse\n    billing (Dict): Billing information for the llm.\n    profiling (Dict): Profiling information (llm response time etc.)."},"DraftingPromptInput":{"properties":{"kind":{"type":"string","title":"Kind"},"message":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Message"},"agent_input":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Agent Input"}},"type":"object","required":["kind"],"title":"DraftingPromptInput","description":"DraftingPromptInput is a data structure used to represent the input for drafting prompts that are used in the drafting endpoint.\nAttributes:\n    kind (str): The type of the drafting prompt (\"email_reply\", \"correction\" etc. see drafting.py).\n    message (Optional[str]): A message associated with the drafting prompt.\n    agent_input (Optional[str]): Optional input provided by the agent.\n\n    message and agent_input are pseudo optional. It depends on the kind if it is optional."},"EvaluationAcceptedResponse":{"properties":{"evaluation_id":{"type":"string","title":"Evaluation Id"},"status":{"type":"string","title":"Status"}},"type":"object","required":["evaluation_id","status"],"title":"EvaluationAcceptedResponse"},"EvaluationEvent":{"properties":{"type":{"type":"string","title":"Type","description":"Event type passed through from the caller, for example validation."},"field":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Field","description":"Optional field name affected by the event."},"valid":{"anyOf":[{"type":"boolean"},{"type":"null"}],"title":"Valid","description":"Optional validation result."},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp","description":"Optional event timestamp."}},"type":"object","required":["type"],"title":"EvaluationEvent"},"EvaluationLookupResponse":{"properties":{"status":{"type":"string","title":"Status"},"pass_status":{"$ref":"#/components/schemas/PassStatus"},"result":{"anyOf":[{"additionalProperties":true,"type":"object"},{"type":"null"}],"title":"Result"}},"type":"object","required":["status","pass_status"],"title":"EvaluationLookupResponse"},"EvaluationMessage":{"properties":{"role":{"type":"string","enum":["agent","user","human_agent"],"title":"Role","description":"Speaker role from the incoming transcript."},"message":{"type":"string","title":"Message","description":"Raw message text. ASR errors and missing punctuation must be preserved."},"timestamp":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Timestamp","description":"Optional timestamp for this transcript message. Prefer this over legacy message_timestamps."}},"type":"object","required":["role","message"],"title":"EvaluationMessage"},"EvaluationMetadata":{"properties":{"started_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Started At","description":"Optional call start timestamp."},"ended_at":{"anyOf":[{"type":"string","format":"date-time"},{"type":"null"}],"title":"Ended At","description":"Optional call end timestamp."},"caller_id_hash":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Caller Id Hash","description":"Optional already-hashed caller identifier."},"ended_by":{"anyOf":[{"type":"string","enum":["caller","bot","transfer","connection_lost"]},{"type":"null"}],"title":"Ended By","description":"Optional deterministic disconnect reason from the source platform."}},"type":"object","title":"EvaluationMetadata"},"EvaluationRequest":{"properties":{"session_id":{"type":"string","title":"Session Id","description":"Stable call identifier from the calling system."},"force":{"type":"boolean","title":"Force","description":"If true, create a new evaluation even when the same session_id and scorecard_config.version already exist.","default":false},"messages":{"items":{"$ref":"#/components/schemas/EvaluationMessage"},"type":"array","minItems":1,"title":"Messages","description":"Transcript messages in the established service format."},"scorecard_config":{"$ref":"#/components/schemas/ScorecardConfig","description":"Required scorecard configuration supplied by the external Scorecard Service for this tenant/desk."},"metadata":{"anyOf":[{"$ref":"#/components/schemas/EvaluationMetadata"},{"type":"null"}],"description":"Optional call metadata."},"message_timestamps":{"anyOf":[{"items":{"type":"string","format":"date-time"},"type":"array"},{"type":"null"}],"title":"Message Timestamps","description":"Legacy optional per-message timestamps. Prefer messages[].timestamp. If present, length must match messages."},"events":{"items":{"$ref":"#/components/schemas/EvaluationEvent"},"type":"array","title":"Events","description":"Optional events passed through for audit and later security signal processing."}},"type":"object","required":["session_id","messages","scorecard_config"],"title":"EvaluationRequest","example":{"force":false,"messages":[{"message":"Hallo, Bob hier.","role":"agent","timestamp":"2026-07-03T10:00:00Z"},{"message":"Hallo Bob, ich habe eine Frage zu meiner Rechnung.","role":"user","timestamp":"2026-07-03T10:00:08Z"}],"metadata":{"caller_id_hash":"sha256:...","ended_by":"caller","started_at":"2026-07-03T10:00:00Z"},"scorecard_config":{"fact_checks":[{"expected":"14 Tage","keywords":["Rechnung","Frist"],"topic":"Rechnungsfrist"}],"intents":["Rechnung","Kuendigung","other"],"scoring_weights":{"conversation_flow":0.15,"customer_experience":0.2,"dialog_quality":0.25,"task_completion":0.4},"version":"tenant-scorecard-v3"},"session_id":"call-123"}},"FactCheckConfig":{"properties":{"topic":{"type":"string","title":"Topic","description":"Fact-check topic name from the external Scorecard Service."},"expected":{"type":"string","title":"Expected","description":"Expected correct information for this topic."},"keywords":{"items":{"type":"string"},"type":"array","title":"Keywords","description":"Keywords that indicate the topic may be present in the transcript."}},"type":"object","required":["topic","expected"],"title":"FactCheckConfig"},"HTTPValidationError":{"properties":{"detail":{"items":{"$ref":"#/components/schemas/ValidationError"},"type":"array","title":"Detail"}},"type":"object","title":"HTTPValidationError"},"IncomingMessage":{"properties":{"role":{"type":"string","title":"Role"},"message":{"type":"string","title":"Message"}},"type":"object","required":["role","message"],"title":"IncomingMessage","description":"The incoming message coming from the outside. This is the message that should be analysed.\n\nAttributes:\n    role (str): The role of the one that spoke the message, can be \"user\" or \"agent\"\n    message (Optional[str]): The text of the user's message."},"IncomingMessages":{"properties":{"messages":{"items":{"$ref":"#/components/schemas/IncomingMessage"},"type":"array","title":"Messages","default":[]}},"type":"object","title":"IncomingMessages","description":"IncomingMessages is a data structure that represents a collection of incoming messages.\nAttributes:\n    messages (List[IncomingMessage]): A list of IncomingMessage objects."},"KnowledgeArticle":{"properties":{"titles":{"items":{"type":"string"},"type":"array","title":"Titles","default":[]},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"},"language":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Language"},"short_description":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Short Description"}},"type":"object","title":"KnowledgeArticle"},"PassStatus":{"properties":{"extraction":{"type":"string","enum":["ok","failed"],"title":"Extraction","default":"failed"},"quality":{"type":"string","enum":["ok","failed"],"title":"Quality","default":"failed"},"security":{"type":"string","enum":["ok","failed"],"title":"Security","default":"failed"}},"type":"object","title":"PassStatus"},"QAResponse":{"properties":{"feedback":{"items":{"type":"string"},"type":"array","title":"Feedback","default":[]},"score":{"anyOf":[{"type":"integer"},{"type":"null"}],"title":"Score"},"ratings":{"additionalProperties":true,"type":"object","title":"Ratings","default":{}},"draft":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Draft"},"reference":{"type":"string","title":"Reference","default":""},"billing":{"additionalProperties":true,"type":"object","title":"Billing","default":{}},"profiling":{"additionalProperties":true,"type":"object","title":"Profiling","default":{}}},"type":"object","title":"QAResponse","description":"Returned by the webservice, this is the response from the assistant/llm, evaluating the incoming message.\n\nAttributes:\n    text (str): The response text from the assistant.\n    reference (str): A reference string associated with the session.\n    billing (Dict): Billing information for the llm.\n    profiling (Dict): Profiling information (llm response time etc.)."},"QASetup":{"properties":{"agent_language":{"type":"string","title":"Agent Language"},"channel":{"type":"string","title":"Channel"},"score_card":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Score Card"}},"type":"object","required":["agent_language","channel"],"title":"QASetup","description":"This is used in the setup call to provide the\nnecessary information for the qa session.\n\nknown_user_details: A dictionary with known user details as a flat dictionary."},"Question":{"properties":{"question_title":{"type":"string","title":"Question Title"},"additional_description":{"type":"string","title":"Additional Description"},"question_type":{"type":"string","title":"Question Type"}},"type":"object","required":["question_title","additional_description","question_type"],"title":"Question"},"ScoreCard":{"properties":{"sections":{"items":{"$ref":"#/components/schemas/Section"},"type":"array","title":"Sections"}},"type":"object","required":["sections"],"title":"ScoreCard"},"ScorecardConfig":{"properties":{"version":{"type":"string","title":"Version","description":"Version identifier from the external Scorecard Service. Used for idempotency together with session_id."},"intents":{"items":{"type":"string"},"type":"array","minItems":1,"title":"Intents","description":"Tenant-/desk-specific issue intents from the external Scorecard Service."},"fact_checks":{"items":{"$ref":"#/components/schemas/FactCheckConfig"},"type":"array","title":"Fact Checks","description":"Tenant-/desk-specific fact-check topics from the external Scorecard Service."},"scoring_weights":{"$ref":"#/components/schemas/ScoringWeights","description":"Optional scoring weights. Defaults are used when omitted."}},"type":"object","required":["version","intents"],"title":"ScorecardConfig","example":{"fact_checks":[{"expected":"14 Tage","keywords":["Rechnung","Frist"],"topic":"Rechnungsfrist"}],"intents":["Rechnung","Kuendigung","other"],"scoring_weights":{"conversation_flow":0.15,"customer_experience":0.2,"dialog_quality":0.25,"task_completion":0.4},"version":"tenant-scorecard-v3"}},"ScoringWeights":{"properties":{"task_completion":{"type":"number","title":"Task Completion","description":"Weight for task completion scoring.","default":0.4},"dialog_quality":{"type":"number","title":"Dialog Quality","description":"Weight for dialog quality scoring.","default":0.25},"conversation_flow":{"type":"number","title":"Conversation Flow","description":"Weight for conversation flow scoring.","default":0.15},"customer_experience":{"type":"number","title":"Customer Experience","description":"Weight for customer experience scoring.","default":0.2}},"type":"object","title":"ScoringWeights"},"Section":{"properties":{"section_title":{"type":"string","title":"Section Title"},"questions":{"items":{"$ref":"#/components/schemas/Question"},"type":"array","title":"Questions"},"subsections":{"items":{"$ref":"#/components/schemas/Subsection"},"type":"array","title":"Subsections"}},"type":"object","required":["section_title"],"title":"Section"},"SmartResponse":{"properties":{"title":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Title"},"text":{"anyOf":[{"type":"string"},{"type":"null"}],"title":"Text"}},"type":"object","title":"SmartResponse"},"Subsection":{"properties":{"subsection_title":{"type":"string","title":"Subsection Title"},"questions":{"items":{"$ref":"#/components/schemas/Question"},"type":"array","title":"Questions"}},"type":"object","required":["subsection_title","questions"],"title":"Subsection"},"ValidationError":{"properties":{"loc":{"items":{"anyOf":[{"type":"string"},{"type":"integer"}]},"type":"array","title":"Location"},"msg":{"type":"string","title":"Message"},"type":{"type":"string","title":"Error Type"},"input":{"title":"Input"},"ctx":{"type":"object","title":"Context"}},"type":"object","required":["loc","msg","type"],"title":"ValidationError"}},"securitySchemes":{"HTTPBearer":{"type":"http","scheme":"bearer"}}}}