Feedback - Crewship

Endpoints under /api/v1/feedback capture structured per-message signal — thumb-up/down, edit, regenerate — for the continuous-learning loop. Rows are keyed to an OTel trace_id so the eval pipeline can join signals back onto the run that produced them. See the Feedback guide for the design contract and UI flow.

All endpoints require authentication. Rows are private to the authoring user — no cross-user reads, even within the same workspace.

Endpoints

Method	Endpoint	Purpose
POST	`/api/v1/feedback`	Create or upsert a feedback signal
GET	`/api/v1/feedback`	List the caller’s feedback by message or trace
DELETE	`/api/v1/feedback`	Clear a feedback signal

Signals

Create, read, and clear per-message feedback rows scoped to the authoring user.

Create / upsert feedback

POST /api/v1/feedback

Idempotent at the (workspace_id, message_id, user_id, signal) tuple. A re-submit in the same workspace replaces reason, trace_id, and chat_id on the existing row rather than producing a duplicate. A forked workspace can retain its own feedback row for the same source message id. Request body:

Field	Type	Required	Notes
`message_id`	string	yes	Turn id from the chat UI. Must already exist in the `conversation_messages` search mirror — see below. Max 256 chars.
`signal`	enum	yes	One of: `helpful`, `not_helpful`, `inaccurate`, `unsafe`, `edit`, `regenerate`.
`chat_id`	string	no	Accepted for older clients but not trusted for authorization. Workspace and chat are always resolved from `message_id`’s own `session_id`. Max 256 chars.
`trace_id`	string	no	OTel trace id linking the row back to the conversation trace. Max 256 chars.
`reason`	string	no	Free-form text. For `edit` signals, holds the replacement text. Max 4096 chars.

message_id must resolve to a real, visible message — not merely be well-formed. The handler looks it up in conversation_messages (the search mirror, migration v111) and derives workspace_id/chat_id from that row’s own session_id, then confirms the caller is a member of that workspace. A message_id that was never persisted there (nothing has been sent in that chat yet, or it predates the mirror) gets the same 404 as a message in a chat the caller can’t see — the two aren’t distinguishable from outside, closing a cross-tenant message-existence oracle (#1208). chat_id in the body is accepted but no longer authoritative.

Response: 201 Created

{ "id": "fb_abc123" }

Errors:

Status	Cause
`400`	Missing `message_id`, unknown `signal`, `reason` > 4096 chars, any id field > 256 chars, malformed JSON.
`401`	No authenticated user. Returned BEFORE any DB lookup so anonymous probes can’t enumerate ids via response codes.
`404`	`message_id` doesn’t resolve to a row in `conversation_messages`, or it does but the caller isn’t a member of that message’s workspace.
`413`	Request body exceeds the size cap (`http.MaxBytesReader`).
`500`	DB write failure. The error body is `{"error":"internal"}` — details land in server logs.

Example:

curl -X POST https://api.crewship.local/api/v1/feedback \
  -b session.txt \
  -H 'Content-Type: application/json' \
  -d '{
    "message_id": "turn_4f3a2c",
    "chat_id":    "chat_8d1e9b",
    "trace_id":   "4f3a2c1b8d1e9b00000000000000abcd",
    "signal":     "not_helpful",
    "reason":     "Mixed up which calendar to query."
  }'

List feedback

GET /api/v1/feedback?message_id=<id>
GET /api/v1/feedback?trace_id=<id>

Exactly one of message_id or trace_id must be provided. Returns only rows authored by the caller — no cross-user visibility. Query parameters:

Param	Type	Required	Description
`message_id`	string	one of `message_id` / `trace_id`	Return feedback for one chat message.
`trace_id`	string	one of `message_id` / `trace_id`	Return feedback joined to one OTel trace.

The request has no body. Supplying both filters is rejected with 400. Response: 200 OK

{
  "feedback": [
    {
      "id":          "fb_abc123",
      "workspace_id": "ws_example",
      "message_id":  "turn_4f3a2c",
      "chat_id":     "chat_8d1e9b",
      "trace_id":    "4f3a2c1b8d1e9b00000000000000abcd",
      "signal":      "not_helpful",
      "reason":      "Mixed up which calendar to query.",
      "user_id":     "usr_caller",
      "created_at":  "2026-05-19T14:23:00Z"
    }
  ]
}

Ordered by created_at DESC. Empty array when no matching rows visible to the caller. Errors:

Status	Cause
`400`	Neither `message_id` nor `trace_id` provided.
`401`	No authenticated user.
`500`	DB read failure.

Delete feedback

DELETE /api/v1/feedback?message_id=<id>&signal=<signal>

Removes the caller’s row for the given (message_id, signal) tuple in one workspace. Other users’ rows and copies in other workspaces are untouched. Existing clients can omit workspace_id when exactly one visible row matches. If a fork leaves matching rows in two workspaces, the server returns 409; use the workspace_id from GET to choose which one to clear. Query parameters:

Param	Type	Required	Notes
`message_id`	string	yes	The message the feedback was attached to.
`signal`	enum	yes	Which signal to clear. Same enum as POST.
`workspace_id`	string	no	Required when matching feedback exists in multiple workspaces. The caller must still be a member of this workspace.

Response: 204 No Content Idempotent: returns 204 even when no row matched, so a client can fire DELETE on every toggle-off click without first checking existence. Errors:

Status	Cause
`400`	Missing `message_id` or `signal`; unknown `signal`.
`401`	No authenticated user.
`409`	Matching feedback exists in multiple visible workspaces; supply `workspace_id`.
`500`	DB write failure.

Schema

message_feedback table (added in migration v96; unique key scoped to a workspace by #2274):

CREATE TABLE message_feedback (
    id           TEXT PRIMARY KEY,
    workspace_id TEXT NOT NULL REFERENCES workspaces(id) ON DELETE CASCADE,
    chat_id      TEXT REFERENCES chats(id) ON DELETE CASCADE,
    message_id   TEXT NOT NULL,
    trace_id     TEXT,
    signal       TEXT NOT NULL CHECK (signal IN (
        'helpful','not_helpful','inaccurate','unsafe','edit','regenerate'
    )),
    reason       TEXT,
    user_id      TEXT REFERENCES users(id) ON DELETE SET NULL,
    created_at   TEXT NOT NULL DEFAULT (datetime('now')),
    UNIQUE(workspace_id, message_id, user_id, signal)
);

CREATE INDEX idx_feedback_trace
    ON message_feedback(trace_id) WHERE trace_id IS NOT NULL;
CREATE INDEX idx_feedback_ws_created
    ON message_feedback(workspace_id, created_at DESC);
CREATE INDEX idx_feedback_message
    ON message_feedback(message_id);

The eval pipeline reads from this table by trace_id to join feedback signals onto the routine run that produced them; see Online eval sampler.

​Endpoints

​Signals

​Create / upsert feedback

​List feedback

​Delete feedback

​Schema

Endpoints

Signals

Create / upsert feedback

List feedback

Delete feedback

Schema