Feedback

GET /v1/feedback#

List answer feedback. One page of the raw feedback rows your visitors and reviewers left on individual answers, in key order (call, then turn, then author). This is also the export: follow the cursor to the end and you hold every row. **Paging.** Pass the next_cursor from the previous response back as ?cursor=. **An empty next_cursor is the only signal that you have seen everything**, a short page, including an empty one, is normal and means "ask again": the agent filter is applied after each read, so a page can match nothing and still have more behind it.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/feedback" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a FeedbackListResponse.

Example response

{
  "items": [
    {
      "agent_name": "front-desk",
      "author_id": "widget-user-1a2b",
      "author_kind": "visitor",
      "call_id": "widget-8c2f1a7e-4b3d-4e21-9c0a-5f6d7e8a9b0c",
      "category": "inaccurate",
      "rating": "down",
      "rating_kind": "thumbs",
      "score": 1,
      "tenant_slug": "acme",
      "turn_id": "t3",
      "turn_role": "agent"
    }
  ],
  "next_cursor": ""
}

POST /v1/feedback#

Rate an answer. Records your review of one transcript turn. Send **either** rating (up/down) **or** score (1 to 5), a thumb is stored as 5/1 on the same scale, so both controls land in one shape. turn_id is t<index>, the zero-based position of the turn in GET /calls/{id}/transcript, or o<offset_ms>, the turn's offset_ms. The turn must exist on the persisted call. **One row per (turn, author): re-submitting replaces your previous rating, it is never counted twice.** Pass author to keep two reviewers' ratings distinct. A rating on a human reply (a representative's turn) is stored with its role and deliberately excluded from the agent satisfaction numbers, it is not an AI quality signal.

Request body

application/json Schema: FeedbackSubmitRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/feedback" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "call_id": "widget-8c2f1a7e-4b3d-4e21-9c0a-5f6d7e8a9b0c",
  "category": "outdated",
  "comment": "Quotes the 2024 price list.",
  "score": 2,
  "turn_id": "t3"
}'

Example response

{
  "agent_name": "front-desk",
  "author_id": "operator",
  "author_kind": "operator",
  "call_id": "widget-8c2f1a7e-4b3d-4e21-9c0a-5f6d7e8a9b0c",
  "category": "outdated",
  "rating": "down",
  "rating_kind": "scale",
  "score": 2,
  "tenant_slug": "acme",
  "turn_id": "t3",
  "turn_role": "agent"
}

GET /v1/feedback/analytics#

Answer satisfaction analytics. Per-agent satisfaction over the stored feedback rows: rated count, up/down split, average score and the satisfaction rate (share of ratings with score ≥ 4), plus the worst-rated turns as a review feed. Only ratings on AI turns count; ratings on human replies are excluded and reported in human_turns_excluded. The fold reads a bounded number of rows and says so: when truncated is true the numbers cover scanned rows, not the whole history.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/feedback/analytics" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a FeedbackAnalyticsResponse.

Example response

{
  "human_turns_excluded": 2,
  "items": [
    {
      "agent": "front-desk",
      "average_score": 4.1,
      "down": 8,
      "rated": 41,
      "satisfaction_rate": 0.8,
      "up": 33
    }
  ],
  "scanned": 43,
  "truncated": false,
  "worst": [
    {
      "agent": "front-desk",
      "call_id": "widget-8c2f…",
      "category": "inaccurate",
      "rating": "down",
      "score": 1,
      "turn_id": "t3"
    }
  ]
}

GET /v1/feedback/regressions#

Export confirmed-wrong answers (regression cases). Every report resolved confirmed_wrong, as stable rows an evaluation harness can consume: the snapshotted answer, its sources, the linked knowledge document and the resolution trail. Rows whose call was erased under a data-subject request keep only the hashed call linkage (erased: true). **Paging.** Pass the next_cursor back as ?cursor=; **an empty next_cursor is the only signal that the export is complete**, the status filter runs after each read, so short pages with a cursor are normal. The row shape is additive-only: fields may be added, never renamed or removed.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/feedback/regressions" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a FeedbackRegressionsResponse.

Example response

{
  "items": [
    {
      "agent": "front-desk",
      "answer_text": "Our premium plan costs …",
      "call_id_hash": "b1946ac9…",
      "category": "inaccurate",
      "id": "fbr_9d8c7b6a",
      "kb_document_id": "doc_4b1e77a0",
      "resolved_by": "maria@acme.example",
      "turn_id": "t3"
    }
  ],
  "next_cursor": ""
}

GET /v1/feedback/reports#

List inaccuracy reports (review queue). One page of the reported answers, in report-id order. ?status=open is the review queue; the three resolved states are the history. Each report carries its own **snapshot** of the answer text and the sources that grounded it, taken when the report was filed, so the review works even after the call itself was erased. snapshot_source says whether the copy came from the stored transcript or was claimed by the reporter mid-session. **Paging.** Pass the next_cursor back as ?cursor=. **An empty next_cursor is the only signal that you have seen everything**, the status filter runs after each read, so short and empty pages with a cursor are normal.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/feedback/reports" \
  -H "Authorization: Bearer VL_API_KEY"

A successful response returns a FeedbackReportsResponse.

Example response

{
  "items": [
    {
      "answer_text": "Our premium plan costs …",
      "call_id": "widget-8c2f…",
      "category": "inaccurate",
      "id": "fbr_9d8c7b6a",
      "snapshot_source": "transcript",
      "sources": [
        {
          "chunk_id": "doc_4b1e77a0:0003",
          "document_id": "doc_4b1e77a0",
          "index": 1,
          "title": "Τιμολόγηση 2026"
        }
      ],
      "status": "open",
      "turn_id": "t3"
    }
  ],
  "next_cursor": ""
}

POST /v1/feedback/reports#

Report an inaccurate answer. Files one answer into the review queue. The answer text and the sources that grounded it are **copied from the stored transcript turn at this moment**, never recomputed later, so the report stays reviewable even if the call is erased afterwards. turn_id is t<index> (transcript item index) or o<offset_ms>, and must name a turn of the persisted call.

Request body

application/json Schema: FeedbackReportCreateRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/feedback/reports" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "call_id": "widget-8c2f1a7e-4b3d-4e21-9c0a-5f6d7e8a9b0c",
  "category": "inaccurate",
  "comment": "The quoted price is last year'\''s.",
  "turn_id": "t3"
}'

Example response

{
  "answer_text": "Our premium plan costs …",
  "call_id": "widget-8c2f…",
  "category": "inaccurate",
  "id": "fbr_9d8c7b6a",
  "snapshot_source": "transcript",
  "status": "open",
  "turn_id": "t3"
}

GET /v1/feedback/reports/{id}#

Get an inaccuracy report. One report, snapshot included.

Parameters

Responses

Example request

curl "https://api.voiceland.ai/v1/feedback/reports/{id}" \
  -H "Authorization: Bearer VL_API_KEY"

Example response

{
  "category": "inaccurate",
  "id": "fbr_9d8c7b6a",
  "status": "open",
  "turn_id": "t3"
}

POST /v1/feedback/reports/{id}/resolve#

Resolve an inaccuracy report. Records the review decision: confirmed_wrong (the answer is wrong and becomes a regression case, see GET /feedback/regressions), correct (the answer was fine), or fixed (you corrected the knowledge content, so the expected answer changed). Optionally link the knowledge document that caused it with kb_document_id. **confirmed_wrong with a kb_document_id flags that document for review**: it appears in GET /kb/review-flags with a pointer back to this report, and its cited_wrong_count goes up. kb_document_flagged in the response says whether that happened. It is false when no document was named or the document no longer exists, and the decision itself is recorded either way. **A decision is one-shot**: resolving an already-resolved report answers 409.

Parameters

Request body

application/json Schema: FeedbackResolveRequest

Responses

Example request

curl -X POST "https://api.voiceland.ai/v1/feedback/reports/{id}/resolve" \
  -H "Authorization: Bearer VL_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "kb_document_id": "doc_4b1e77a0",
  "note": "Doc quotes the 2024 price list.",
  "resolution": "confirmed_wrong",
  "resolved_by": "maria@acme.example"
}'

A successful response returns a FeedbackResolveResponse.

Example response

{
  "id": "fbr_9d8c7b6a",
  "kb_document_flagged": true,
  "kb_document_id": "doc_4b1e77a0",
  "status": "confirmed_wrong"
}

Schemas#

AnswerFeedback#

AnswerFeedbackReport#

Error#

Error envelope returned for non-2xx responses.

FeedbackAgentAnalytics#

FeedbackAnalyticsResponse#

FeedbackListResponse#

FeedbackRegressionCase#

FeedbackRegressionsResponse#

FeedbackReportCreateRequest#

FeedbackReportsResponse#

FeedbackResolveRequest#

FeedbackResolveResponse#

FeedbackSubmitRequest#

FeedbackWorstItem#

TranscriptSource#