Change one displayed name or description to a person's words, and re-emit the draft
const url = 'http://localhost:11044/api/v1/learn/example/change';const options = { method: 'POST', headers: {'X-Embabel-Api-Key': '<X-Embabel-Api-Key>', 'Content-Type': 'application/json'}, body: '{"revision":"example","subject":"example","value":"example"}'};
try { const response = await fetch(url, options); const data = await response.json(); console.log(data);} catch (error) { console.error(error);}curl --request POST \ --url http://localhost:11044/api/v1/learn/example/change \ --header 'Content-Type: application/json' \ --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \ --data '{ "revision": "example", "subject": "example", "value": "example" }'Authorizations
Section titled “Authorizations”Parameters
Section titled “Parameters”Path Parameters
Section titled “Path Parameters”Id of the held draft review (learn- plus a UUID, as returned by POST /api/v1/learn/sources/{name}/learn) in which a decision is changed; 404 when no draft of that id is held for this user, which includes an expired id and a database-description review
Request Bodyrequired
Section titled “Request Bodyrequired”One change in a person’s own words: revision is the draft revision they read (409 REVISION_STALE when the draft has moved on), subject a displayed name or description decision, and value the wording that replaces it. A subject that is not a name or description, or a value the draft cannot carry, is refused with 400 CHANGE_INVALID. The draft is re-emitted with the change recorded under the caller’s name
A person’s own words for one displayed name or description, sent to POST /learn/{id}/change
object
The revision the person read; one that is no longer current is refused 409 REVISION_STALE
The subject of a displayed rename or description decision, e.g. rename:Grant; any other kind is refused 400 CHANGE_INVALID, and one not displayed 400 DECISION_UNKNOWN
The new value, trimmed: for a rename, one word of letters, digits and underscores starting with a letter; for a description, its whole text. Empty or unchanged is refused 400 CHANGE_INVALID
Example generated
{ "revision": "example", "subject": "example", "value": "example"}Responses
Section titled “Responses”OK
A learning proposal to review before anything is written: what was read, what was decided and asked, the realm it would install, and where it stands. Answered by the learn, proposal, answer, approval and change endpoints; every part is flattened into one object
object
The proposal’s id, for the /learn/{id} endpoints. Held in memory for its owner only; another user’s or an expired one answers 404
Name of the source it was learned from, as SourceWire.name gives it
One line to show when the pass finishes: tables, decisions, joins that returned rows, open questions and decisions applied unconfirmed
Example generated
{ "id": "example", "source": "example", "summary": "example"}CHANGE_INVALID: not a name or description, or a value the draft cannot carry; DECISION_UNKNOWN
A refusal that names a machine-readable code beside its explanation
object
The refusal’s code, for a client that branches rather than reads. Every value comes from the sealed LearningReviewRefusal hierarchy, except SOURCE_UNREADABLE which the 502 path builds directly.
What was refused and what to do about it, written to be shown to the person reviewing
Example
{ "code": "REVISION_STALE"}No draft review of that id is held for this owner
REVISION_STALE: the review changed; fetch it again
A refusal that names a machine-readable code beside its explanation
object
The refusal’s code, for a client that branches rather than reads. Every value comes from the sealed LearningReviewRefusal hierarchy, except SOURCE_UNREADABLE which the 502 path builds directly.
What was refused and what to do about it, written to be shown to the person reviewing
Example
{ "code": "REVISION_STALE"}