Skip to main content
Submit a correction event. Feedback is stored as an append-only event — it never mutates the original artifact or span.

​
Request

POST /v1/feedback
​
action
string
required
One of: pin, private, mark_wrong, outdated, resolve_conflict
​
artifact_id
string
required
The artifact to apply feedback to.
​
span_id
string
required
The specific span within the artifact.
​
actor_id
string
required
Who is submitting the feedback.
​
workspace_id
string
required
Workspace scope.
​
conflict_id
string
Required for resolve_conflict action. The conflict ID from a receipt.
​
preferred_span_id
string
The preferred span when resolving a conflict.
​
reason
string
Human-readable reason for the feedback.

​
Response

​
feedback_id
string
UUID of the feedback event.
​
action
string
The action that was applied.
​
applied
boolean
Whether the feedback was successfully applied.
​
created_at
string
ISO 8601 timestamp.

​
Feedback Actions

ActionEffect on Future Packs
pinSpan is promoted to the prefix (authoritative) section of every context pack in the workspace
privateSpan is excluded from packs for other actors
mark_wrongSpan is excluded from all future packs
outdatedSpan is deprioritized (not excluded, but penalized in scoring)
resolve_conflictResolves a detected conflict, selecting the preferred span

​
Example

# Pin a span as authoritative
client.feedback(
    action="pin",
    artifact_id="a1b2c3d4-...",
    span_id="s1e2f3g4-...",
    actor_id="user_alice",
    workspace_id="ws_acme",
    reason="This is the authoritative Q2 pricing policy",
)

# Mark a span as incorrect
client.feedback(
    action="mark_wrong",
    artifact_id="a1b2c3d4-...",
    span_id="s1e2f3g4-...",
    actor_id="user_alice",
    workspace_id="ws_acme",
    reason="This pricing info was superseded",
)

# Resolve a conflict detected in a receipt
client.feedback(
    action="resolve_conflict",
    artifact_id="a1b2c3d4-...",
    span_id="s1e2f3g4-...",
    actor_id="user_alice",
    workspace_id="ws_acme",
    conflict_id="conflict_uuid",
    preferred_span_id="s1e2f3g4-...",
)
Response
{
  "feedback_id": "f1a2b3c4-...",
  "action": "pin",
  "applied": true,
  "created_at": "2026-03-09T14:35:00Z"
}