Skip to content
Embabel Worlds

Connect an API to this world, so it can be learned

POST
/api/v1/learn/apis
curl --request POST \
  --url http://localhost:11044/api/v1/learn/apis \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "fields": { "additionalProperty": "example" }, "headerName": "example", "mode": "example", "name": "example", "specUrl": "example", "token": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

The API to connect. mode is an auth-mode id from GET /api/v1/learn/apis/modes: none (the default when omitted), bearer or api-key; any other is refused with 400. specUrl (required, the OpenAPI document’s URL), name, token and headerName may be given top-level or inside fields, the top-level value winning. token is required unless the mode is none and is stored in the user’s wallet; headerName is used by api-key and defaults to X-API-Key; name defaults to the name the spec gives itself, slugged. The spec is fetched and parsed before anything is saved, and the world is rebuilt

Media typeapplication/json

How to reach an API, sent to POST /learn/apis: an auth mode and that mode’s fields, with the top-level specUrl, name, token and headerName accepted too, for a script that has them in hand

object
fields
required

Values for the mode’s form, keyed by each field’s name (specUrl, name, token, headerName). A top-level property of the same name takes precedence; blank values count as absent

object
key
additional properties
string
headerName

The header that carries the key, for mode api-key only; absent means X-API-Key. Not secret

string
mode

An auth-mode id from GET /learn/apis/modes: none, bearer or api-key. Absent means none; any other value is refused 400

string
name

The gateway namespace to register the API under, made into a slug; absent uses the spec’s own title

string
specUrl

URL of the API’s OpenAPI document, fetched to prove it answers. Required, here or as fields.specUrl

string
token

The bearer token or API key, required for modes bearer and api-key. Stored in the user’s wallet, never echoed back and never written to world YAML

string

Example generated

{
  "fields": {
    "additionalProperty": "example"
  },
  "headerName": "example",
  "mode": "example",
  "name": "example",
  "specUrl": "example",
  "token": "example"
}

Responses

Section titled “Responses”

400

Section titled “400”

Spec unreachable or unparseable, or a token missing for the mode

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