Feedback

Structured feedback lets agents label prior Lithtrix results as helpful, unhelpful, or wrong. Events are append-only; ref_id is not validated against your data (fast path). Avoid secrets and PII in note (≤500 characters). Discovery version 2.2.0 includes a feedback block and lithtrix_response_envelope (shape of _lithtrix, including browse_url) in GET /v1/capabilities with tier limits and vocabulary.

POST /v1/feedback

curl -X POST https://lithtrix.ai/v1/feedback \
  -H "Authorization: Bearer ltx_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "ref_type": "search_id",
    "ref_id": "550e8400-e29b-41d4-a716-446655440000",
    "signal": "helpful",
    "note": "optional"
  }'

Body

Field	Type	Required	Description
`ref_type`	string	Yes	`search_id`, `memory_key`, `blob_id`, `parse_id`, or `browse_id`
`ref_id`	string	Yes	Opaque id (e.g. `_lithtrix.search_id` from search, or `browse_id` from `POST /v1/browse`)
`signal`	string	Yes	`helpful`, `unhelpful`, or `wrong`
`note`	string	No	≤500 characters

Success (201)

{
  "status": "success",
  "feedback_id": "uuid",
  "_lithtrix": {
    "served_by": "api.lithtrix.ai",
    "register_url": "https://api.lithtrix.ai/v1/register",
    "discover_url": "https://api.lithtrix.ai/.well-known/ai-agent.json",
    "guide_url": "https://api.lithtrix.ai/v1/guide",
    "feedback_url": "https://api.lithtrix.ai/v1/feedback",
    "browse_url": "https://api.lithtrix.ai/v1/browse",
    "terms_url": "https://lithtrix.ai/terms",
    "terms_version": "2026-04-25"
  }
}

Errors

HTTP	`error_code`	When
422	`INVALID_REF_TYPE`	`ref_type` not in allowed set
422	`INVALID_SIGNAL`	`signal` not in allowed set
422	`NOTE_TOO_LONG`	`note` over 500 characters
422	`INVALID_REF_ID`	Empty `ref_id`
429	`FEEDBACK_LIMIT`	Monthly tier cap (UTC month); includes `upgrade_url`

See Errors for the common envelope shape.

GET /v1/feedback/stats

curl https://lithtrix.ai/v1/feedback/stats \
  -H "Authorization: Bearer ltx_your_key"

Returns rolling UTC aggregates for the authenticated agent: last_7d, last_30d, by_ref_type (counts per ref_type × signal), plus limit and remaining for the current UTC calendar month (same caps as POST).

MCP

Tool: lithtrix_feedback (npx -y lithtrix-mcp)
Static schema: GET /mcp/lithtrix-feedback.json

Getting Started

API Reference

Concepts

Integrations

POST /v1/feedback

Body

Success (201)

Errors

GET /v1/feedback/stats

MCP

​POST /v1/feedback

​Body

​Success (201)

​Errors

​GET /v1/feedback/stats

​MCP

POST /v1/feedback

Body

Success (201)

Errors

GET /v1/feedback/stats

MCP