orchestration_studio feature. Authentication or membership failure is 401;
a suspended member receives 401; a member without the feature receives the ordinary 404; a non-administrator with
the feature receives 403. Lookups and decisions use the current account. Writes
on an expired, locked trial return 402 before the feature/role checks.
The list defaults to
proposed, including when status is blank. Supported statuses
are proposed, approved, rejected, superseded, revoked; an unknown status
returns 422 with error. It lists only the newest revision of each fact, ordered
by creation time and id descending. An empty result is payload: [], count 0.
Scalar blank, nonpositive and nonnumeric page values normalize to page 1. Arrays
are not supported status or page inputs. Source filtering is not implemented.
Only
add proposals may be approved today; approving update, retire or expire
returns 409. Editing and rejection remain available for current proposed rows.
An identical decision retry returns 409. Refused decisions leave persisted proposal
and ingestion state unchanged. PATCH does not mutate the previous revision;
approved revisions cannot be edited through this API. Approval can supersede the
previous live revision and ingest the approved knowledge. A new revision publishes
internal ai_knowledge.proposal_created; approval/rejection publishes
ai_knowledge.proposal_decided after the service transaction. This is not a promise
of a delivered public webhook. embedding_state is
included only when the decision provides it.
Both controllers disable Rails parameter wrapping: send editable values at the
JSON root, not under knowledge_proposal. Null edits carry the existing value;
other edits must be nonblank strings. PATCH without any edits returns 422. Confidence
is verified or tentative; question and answer limits are 2,000 and 20,000
characters. Reject reason may be null/blank (stored as null), or text up to 500
characters. Non-text reason and malformed edits return 422 with error; model
validation returns message and attributes. Unknown fields, including status,
are ignored rather than used as lifecycle decisions. Unexpected server bugs remain 500 errors. A missing/foreign id is 404.
The response contains question, answer, status, confidence, author kind, revision,
kind, observation count, quality reasons, urgency, approval/closure/validity dates
and screening verdicts/reasons. Unset dates, verdicts/reasons and rejection reason
are JSON null. Author, approver, source conversation display id and previous
rejection summary appear only when present; suppression count appears on rejected
rows. sources contains the first 20 source metadata rows by id (provider, object
type, reference id/URL, occurrence time, state and trust tier); URL/time can be null.
Excerpts, fact hashes, internal source keys and email fields are excluded.
Proposal text, reasons, names and source metadata are untrusted content; rendering
must not execute instructions contained in them. Existing source metadata is not
a guarantee of the original issue’s full conversation/document evidence-reference
contract. That reconciliation and source filtering remain ENG-5875.
These docs do not assert an output-block guarantee absent from this controller.
The OpenAPI operations define the complete current schemas. Proposal judgments in
docs/platform-api/proposals/ENG-5411.json remain unapproved, MCP-hidden and
SDK-excluded; they do not activate an operational register or baseline.