agent_desk

Approve Learning

"Teach it": activate the learning's document change(s) and save its test.

ONE TAP, ONE TRANSACTION (D23/D27). Everything a learning card offers happens here or not at all:

  1. The proposed version — and every SIBLING version in its group — goes live through control_documents.set_active_version, the existing activation door, so review incorporation and knowledge indexing fire exactly as they do for a human PUT. A category="both" learning is TWO versions (knowledge + policy) carrying the same review_ids; they activate together, because half of a learning is a document that contradicts its own policy — UNLESS a member's document has moved past it, in which case that member is SKIPPED and reported in skipped_versions (review finding: _version_is_stale judges every member, not only the tapped one, and a stale sibling must not 409 a tap the owner made on the other half).
  2. statement_override rewrites the customer-facing statement — change_summary plus the provenance statement, kept byte-equal. It NEVER touches the markdown. That boundary is the whole reason the override exists: the owner is correcting how their AgentDesk describes what it learned, not editing the document, and letting this endpoint write document text would make a one-tap button the least reviewed write path in the product.
  3. ANSWER TESTS ARE RETIRED (Jason, 2026-10-14). The learning's test_action and any test_override are ignored: no test is created or updated and no baseline run is enqueued. test/baseline_run_enqueued stay in the response (null/false) so readers keep their shape.
  4. A HELD LEARNING WHOSE DOCUMENT MOVED since it was drafted (its recorded base is no longer what is live) is not applied over the newer edit and not refused: its proposals are retired and the same correction is drafted again against what is live — redrafting: true with the correction payload to follow (:func:_redraft_held_learning). Learnings without a recorded base keep the old behaviour.

POLICY ACTIVATION IS ALLOWED HERE, and only because this is a human pressing a button — the same standing as the PUT door. get_user is asserted for exactly that reason (D14 keeps policy activation human-only; an unattended lane must never reach this endpoint).

Errors: 400 malformed id · 404 not this domain's version · 409 already activated/rejected, or not a learning proposal at all.

post/api/domains/{domain_id}/agent-desk/learnings/{version_id}/approve

Request

  • Base URL
    https://api-v1.unusual.ai (the document declares no server; this is the origin it was published from)
  • Auth
    OAuth 2
    Password
    Token URL: /auth/login

Path parameters

version_idstring required
domain_idstring required

Headers

x-view-asstring nullable

Request body

statement_overridestring nullable

Response

Successful Response

activated_versionsobject[] required
testobject nullable
regenerate_offerstring nullable
baseline_run_enqueuedboolean
skipped_versionsobject[]
redraftingboolean
correctionobject nullable
detailstring required

Changes

No recorded changes to this operation across all 1 revision of this API.