Utterance Feedback Response

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/simple-ai/json-schema/simple-ai-utterance-feedback-response-schema.json",
  "title": "Utterance Feedback Response",
  "x-generated": "2026-10-29",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/simple-ai-openapi.json#/components/schemas/UtteranceFeedbackResponse",
  "type": "object",
  "required": [
    "uuid",
    "transcript_entry_id",
    "feedback_text",
    "resolved",
    "created_at",
    "notes",
    "anchors"
  ],
  "properties": {
    "uuid": {
      "type": "string",
      "format": "uuid",
      "title": "UUID",
      "description": "Unique identifier for the feedback entry"
    },
    "call_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Call ID",
      "description": "UUID of the call the feedback belongs to"
    },
    "transcript_entry_id": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Transcript Entry ID",
      "description": "Identifier of the first transcript entry (utterance) the feedback was left on; null for feedback on the call as a whole"
    },
    "category": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "wrong_action",
            "skipped_verification",
            "incorrect_information",
            "transfer_handling",
            "conversation_quality",
            "data_integration",
            "transcription_error",
            "interruption_handling",
            "tag_error",
            "other"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Category",
      "description": "Feedback category, auto-assigned when the feedback is created unless the reviewer picked one. Null when not yet categorized."
    },
    "priority": {
      "anyOf": [
        {
          "type": "string",
          "enum": [
            "critical",
            "high",
            "medium",
            "low"
          ]
        },
        {
          "type": "null"
        }
      ],
      "title": "Priority",
      "description": "Reviewer-assigned priority. Null when the reviewer did not set one."
    },
    "utterance_text": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Utterance Text",
      "description": "Text of the utterance the feedback was left on"
    },
    "utterance_role": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Utterance Role",
      "description": "Speaker role of the utterance (e.g. 'assistant' or 'user')"
    },
    "feedback_text": {
      "type": "string",
      "title": "Feedback Text",
      "description": "The feedback left by the reviewer"
    },
    "corrected_response": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Corrected Response",
      "description": "Suggested corrected response, if one was provided"
    },
    "agent_id": {
      "anyOf": [
        {
          "type": "string",
          "format": "uuid"
        },
        {
          "type": "null"
        }
      ],
      "title": "Agent ID",
      "description": "UUID of the agent the feedback was recorded against"
    },
    "agent_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Agent Name",
      "description": "Name of the agent at the time the feedback was created"
    },
    "node_name": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "null"
        }
      ],
      "title": "Node Name",
      "description": "Name of the agent node the utterance came from, if known"
    },
    "resolved": {
      "type": "boolean",
      "title": "Resolved",
      "description": "Whether the feedback has been marked as fixed"
    },
    "resolved_at": {
      "anyOf": [
        {
          "type": "string",
          "format": "date-time"
        },
        {
          "type": "null"
        }
      ],
      "title": "Resolved At",
      "description": "When the feedback was marked as fixed (null if unresolved)"
    },
    "created_at": {
      "type": "string",
      "format": "date-time",
      "title": "Created At",
      "description": "When the feedback was created"
    },
    "submitted_by": {
      "anyOf": [
        {
          "type": "object",
          "properties": {
            "email": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Email",
              "description": "Submitter's email address"
            },
            "first_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "First Name",
              "description": "Submitter's first name"
            },
            "last_name": {
              "anyOf": [
                {
                  "type": "string"
                },
                {
                  "type": "null"
                }
              ],
              "title": "Last Name",
              "description": "Submitter's last name"
            }
          }
        },
        {
          "type": "null"
        }
      ],
      "title": "Submitted By",
      "description": "The user who submitted the feedback (null if unavailable)"
    },
    "notes": {
      "type": "array",
      "items": {
        "$ref": "#/$defs/UtteranceFeedbackNoteResponse"
      },
      "title": "Notes",
      "description": "Discussion notes attached to the feedback entry"
    },
    "anchors": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "transcript_entry_id",
          "text"
        ],
        "properties": {
          "transcript_entry_id": {
            "type": "string",
            "title": "Transcript Entry ID"
          },
          "text": {
            "type": "string",
            "title": "Text",
            "description": "Text of the utterance"
          },
          "role": {
            "anyOf": [
              {
                "type": "string"
              },
              {
                "type": "null"
              }
            ],
            "title": "Role",
            "description": "Who spoke the utterance, e.g. assistant or user"
          }
        },
        "title": "Feedback Anchor"
      },
      "title": "Anchors",
      "description": "Every transcript entry the feedback points at, in conversation order. Empty for feedback on the call as a whole, and for older feedback stored without utterance text (transcript_entry_id is still set for those). Otherwise transcript_entry_id, utterance_text and utterance_role mirror the first anchor."
    }
  },
  "$defs": {
    "UtteranceFeedbackNoteResponse": {
      "type": "object",
      "required": [
        "note_text",
        "created_at"
      ],
      "properties": {
        "author_name": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "null"
            }
          ],
          "title": "Author Name",
          "description": "Display name of the note author"
        },
        "note_text": {
          "type": "string",
          "title": "Note Text",
          "description": "The text content of the note"
        },
        "created_at": {
          "type": "string",
          "format": "date-time",
          "title": "Created At",
          "description": "When the note was created"
        }
      },
      "title": "Utterance Feedback Note Response"
    }
  }
}