Interaction Models

Every interaction must carry something. An interaction with no content, shadow_content, expert_content, interacted_image_url, image_encoding, tools_used, citations, retrieved_learnings, and a user_action of none carries no information and can never produce a learning, so it is dropped from the batch. Your other interactions publish normally, so a single empty placeholder turn never fails the request. Whitespace-only text does not count as content. The response's warnings records how many interactions were skipped and at which indices.

A publish where every interaction is empty returns a 422: there is nothing to learn from.

// POST /api/publish_interaction
{"user_id": "user_123", "session_id": "session_abc",
 "interaction_data_list": [{"role": "User"}, {"role": "Agent"}]}

// 422 Unprocessable Entity
// every interaction is empty: at least one must set "content" (or any of: ...)

Two further rules return a 422, because they are contradictions rather than absences: a user_action other than none requires a user_action_description, and interacted_image_url and image_encoding cannot both be set. The message names the offending interaction_data_list index. All of these apply on both the synchronous and the default asynchronous publish path.

Unrecognised field names are ignored, but reported. Every field below is optional with a default, so a misspelled key binds to nothing and its value is discarded — a mis-keyed content produces an interaction that is then dropped as empty. As long as one interaction survives, the request still succeeds; if the mis-keying empties every interaction, you get the 422 above, and its message names the offending field. On success, the response's warnings names the unrecognised fields and the interaction_data_list index each appeared on, including nested paths such as tools_used[0].stat. Read that list; a correctly-shaped payload produces no payload warnings.

Two qualifications. The list is bounded — at most 5 names per interaction and 20 entries overall, each with a +N more suffix — so on a large broken batch treat it as a sample rather than an inventory. And per-interaction user_id and session_id are stripped without a warning, because callers routinely repeat those request-level fields on every interaction; their absence from the list is not evidence that they bound.

Still build your payload from an allowlist of the fields below rather than passing an internal record through — the warning tells you a field was dropped, it does not stop the drop.