Skip to content
Embabel Worlds

Approve displayed decisions against the current draft digest. Recorded, not yet enforced

POST
/api/v1/learn/{id}/approval
curl --request POST \
  --url http://localhost:11044/api/v1/learn/example/approval \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "revision": "example", "subjects": [ "example" ] }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
id
required
string

Id of the held draft review (learn- plus a UUID, as returned by POST /api/v1/learn/sources/{name}/learn) whose decisions are approved; 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”

What the reviewer approves: revision is the draft revision they read (409 REVISION_STALE when the draft has moved on), and subjects the subjects of displayed decisions they approve, such as rename:Grant (400 DECISION_UNKNOWN when empty or naming one the review does not display). The approvals are recorded against the draft and shown on the review; they do not yet gate the install

Media typeapplication/json

Decisions a person approves, sent to POST /learn/{id}/approval. Approvals are recorded and shown, not yet enforced

object
revision
required

The revision the approver read; one that is no longer current is refused 409 REVISION_STALE

string
subjects
required

Subjects of displayed decisions, e.g. rename:Grant. An empty list, or a subject the review does not display, is refused 400 DECISION_UNKNOWN

Array<string>

Example generated

{
  "revision": "example",
  "subjects": [
    "example"
  ]
}

Responses

Section titled “Responses”

400

Section titled “400”

DECISION_UNKNOWN: no subjects, or one the review does not display

Media typeapplication/json

A refusal that names a machine-readable code beside its explanation

object
code
required

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.

string
Allowed values: REVISION_STALE WARNINGS_STALE WARNINGS_NOT_ACKNOWLEDGED DIGEST_STALE SOURCE_CHANGED LEARNING_IN_PROGRESS DECISION_UNKNOWN CHANGE_INVALID SOURCE_UNREADABLE
error
required

What was refused and what to do about it, written to be shown to the person reviewing

string

Example 

{
  "code": "REVISION_STALE"
}

404

Section titled “404”

No draft review of that id is held for this owner

409

Section titled “409”

REVISION_STALE: the review changed; fetch it again. SOURCE_CHANGED: the source served another description since; learn it again

Media typeapplication/json

A refusal that names a machine-readable code beside its explanation

object
code
required

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.

string
Allowed values: REVISION_STALE WARNINGS_STALE WARNINGS_NOT_ACKNOWLEDGED DIGEST_STALE SOURCE_CHANGED LEARNING_IN_PROGRESS DECISION_UNKNOWN CHANGE_INVALID SOURCE_UNREADABLE
error
required

What was refused and what to do about it, written to be shown to the person reviewing

string

Example 

{
  "code": "REVISION_STALE"
}