---
title: "Approve Learning"
method: POST
path: "/api/domains/{domain_id}/agent-desk/learnings/{version_id}/approve"
tags: ["agent_desk"]
---

# Approve Learning

`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)
- URL: `https://api-v1.unusual.ai/api/domains/{domain_id}/agent-desk/learnings/{version_id}/approve`
- Auth: OAuth 2
  - Password
  - Token URL: `/auth/login`

"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.

## Path parameters

- `version_id` string, required
- `domain_id` string, required

## Headers

- `x-view-as` string, nullable

## Request body

- LearningApprove
  - `statement_override` string, nullable
  - `test_override` LearningTestOverride: D27's editable bundle. Either new wording, or `drop: true` — never both in spirit; `drop` wins if both arrive, because dropping is the destructive choice and a client that sends both is confused about what it is asking for.
    - `question` string, nullable
    - `expectation` string, nullable
    - `drop` boolean

## Response `200`

Successful Response

- LearningApproveOut
  - `activated_versions` object[], required
  - `test` object, nullable
  - `regenerate_offer` string, nullable
  - `baseline_run_enqueued` boolean
  - `skipped_versions` object[]
  - `redrafting` boolean
  - `correction` object, nullable
  - `detail` string, required

## Other responses

- `422`: Validation Error

---

[API](https://skmtc.dev/unusual/apis/dashboard-server.md) - [All operations](https://skmtc.dev/unusual/apis/dashboard-server/llms.txt) - [OpenAPI document](https://skmtc.dev/unusual/apis/dashboard-server/revisions/89f716930ead?raw)