Skip to content
Embabel Worlds

Change a connected API. The spec is fetched first; a failed fetch changes nothing

PUT
/api/v1/learn/apis/{name}
curl --request PUT \
  --url http://localhost:11044/api/v1/learn/apis/example \
  --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”

Parameters

Section titled “Parameters”

Path Parameters

Section titled “Path Parameters”
name
required
string

Name of the connected API to change, as listed by GET /api/v1/learn/sources; 404 when it is not an API this user connected

Request Bodyrequired

Section titled “Request Bodyrequired”

The new connection, in the shape POST /api/v1/learn/apis takes. specUrl is required, mode defaults to none, a blank token keeps the stored one, and headerName defaults to X-API-Key; a name in the body is ignored, since the path names the API. The spec is fetched first and nothing changes when that fails; a saved change drops the reviews held for this source and rebuilds the world

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

404

Section titled “404”

Not an API this user connected

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