Skip to content
Embabel Worlds

Mine, curate and probe a source. Writes nothing — returns the proposal to review

POST
/api/v1/learn/sources/{name}/learn
curl --request POST \
  --url http://localhost:11044/api/v1/learn/sources/example/learn \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "consent": "example", "descriptionsOnly": true, "purpose": "example" }'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

Name of the source to learn, as listed by GET /api/v1/learn/sources; 404 when no reachable source has that name

Request Body

Section titled “Request Body”

Optional; omitted, the source is learned as a realm from metadata alone. consent sets how much may be read, case-insensitive: METADATA (the default, also used for an unrecognised value), DISTINCT_VALUES or SAMPLE_ROWS. purpose is one line on what the source is, used as evidence by the curation. descriptionsOnly: true drafts a database description instead of a realm, and then takes only METADATA or SAMPLE_ROWS (400 otherwise). Nothing is written to the world either way

Media typeapplication/json

How to learn a source, sent to POST /learn/sources/{name}/learn. The body is optional: absent learns a realm under metadata consent with no purpose

object
consent

What learning may read: metadata, distinct_values or sample_rows, in any case. Absent or unrecognised means metadata. With descriptionsOnly only metadata and sample_rows apply; distinct_values is refused 400

string
descriptionsOnly
required

True drafts only a description of a connected ClickHouse database and answers a description proposal rather than a realm proposal; false (the default) learns a realm

boolean
purpose

One line about what the source is, given to the curator alongside the metadata; absent when none

string

Example generated

{
  "consent": "example",
  "descriptionsOnly": true,
  "purpose": "example"
}

Responses

Section titled “Responses”

404

Section titled “404”

No such source, or it is unreachable

Media typeapplication/json

A refusal carrying only its explanation, with no code to branch on

object
error
required

What went wrong, written to be shown. Carries the underlying driver’s or parser’s own message where there is one

string

Example generated

{
  "error": "example"
}

409

Section titled “409”

LEARNING_IN_PROGRESS: this source is being learned with a different consent or purpose

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

502

Section titled “502”

SOURCE_UNREADABLE: the source’s current description could not be fetched

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