> ## Documentation Index
> Fetch the complete documentation index at: https://docs.tied.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Knowledge proposals

> Current administrator review queue and revision decisions.

All five operations require an authenticated administrator of the URL account and
its `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.

| Operation | Request | Result |
| - | - | - |
| `GET /api/v1/accounts/{account_id}/knowledge_proposals` | `status`, `page` query inputs | `payload` and `meta.count/current_page`; 25 rows per page |
| `GET .../knowledge_proposals/{id}` | No body | One serialized revision, including an older revision |
| `PATCH .../knowledge_proposals/{id}` | Top-level `question`, `answer`, `confidence` | 201; a new proposed revision with a new id |
| `POST .../knowledge_proposals/{id}/approve` | Optional top-level edits | 200; approved row, or a new approved revision when editing |
| `POST .../knowledge_proposals/{id}/reject` | Optional top-level `reason` | 200; rejected row |

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.

| Starting row | Edit | Approve | Reject |
| - | - | - | - |
| Current proposed | New proposed revision (201) | Approved (200); edits create a new human revision | Rejected (200) |
| Older proposed revision | 409 | 409 | 409 |
| Approved, rejected, superseded or revoked | 409 | 409 | 409 |
| Expired current proposed | 409 | 409 | Rejected (200) |
| Held agent proposal (signal learning enabled) | New proposed human revision | 409 unless an actual human text edit overrides the held text | Rejected (200) |

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](https://linear.app/tied/issue/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.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.