Skip to content
Embabel Worlds

Discover an API from a description or URL

POST
/api/v1/discovery
curl --request POST \
  --url http://localhost:11044/api/v1/discovery \
  --header 'Content-Type: application/json' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>' \
  --data '{ "query": "example" }'

Authorizations

Section titled “Authorizations”

Request Bodyrequired

Section titled “Request Bodyrequired”

What to discover, in query: a URL starting http:// or https:// (a website, docs page or spec) is probed for a spec first and read as docs when none is found; anything else is a natural-language description such as weather API, searched for on the web and read by an LLM, unless a cached discovery’s name already contains it, which is returned instead. A result read from docs is cached under its name, which POST /discovery/install takes; a spec the URL probe finds directly is not cached

Media typeapplication/json

Body of POST /discovery: what API to find, described in words or given as a URL.

object
query
required

A natural-language description of the API (e.g. weather API), or an http:// / https:// URL of its website, docs or spec. A URL is probed for a spec first and falls back to reading the docs; a description is matched against cached discoveries by name before searching

string

Example generated

{
  "query": "example"
}

Responses

Section titled “Responses”

200

Section titled “200”

OK

Media type*/*

An API found by discovery. Returned by POST /discovery, GET /discovery and GET /discovery/cache; a result discovered by reading docs is kept in the server’s in-memory cache, which POST /discovery/install reads by name.

object
authDetails
required

Auth specifics read from the docs, keyed headerName and keyLocation when known. Empty when none were found

object
key
additional properties
string
authType
required

Authentication the API appears to need: none, apiKey, bearer or oauth2, as read from its docs

string
baseUrl

The API’s base URL. Null when discovery did not establish one

string
description
required

What the API does, as discovery summarised it

string
discoveredAt
required

When this discovery ran, as an ISO-8601 instant

string format: date-time
endpoints
required

Key endpoints discovery found in the docs. Unauthenticated GET endpoints that did not answer a probe with 2xx are dropped. Empty when the API was found from a spec URL directly

Array<object>

One endpoint of a discovered API, as read from its documentation; listed in a discovery’s endpoints.

object
description
required

What the endpoint does, as discovery read it from the docs

string
method
required

HTTP method, e.g. GET or POST

string
parameters
required

Query and path parameters the endpoint takes, as discovery read them

Array<object>

A query or path parameter on a discovered endpoint, used when install has to synthesize the API’s spec.

object
description

Short description of the parameter for tooling and model hints. Null when the docs gave none

string
location
required

Where the parameter goes: query or path

string
name
required

Parameter name exactly as the API expects it, e.g. latitude

string
required
required

Whether the API requires the parameter

boolean
type
required

JSON Schema primitive type: string, integer, number, boolean or array

string
path
required

Path relative to the API’s base URL, possibly with {param} templates

string
verified
required

True when a live GET to the endpoint answered 2xx. Only unauthenticated GET endpoints without path templates are probed; false for every other endpoint means not probed, not failed

boolean
name
required

Human-readable API name (e.g. OpenWeatherMap); the key, case-insensitive, that the cache and install look it up by

string
sources
required

URLs of the documentation read during discovery

Array<string>
specType
required

Kind of spec at specUrl, lowercase: normally openapi or graphql

string
specUrl
required

Where install learns the API from: the OpenAPI document or GraphQL endpoint. When no spec was found (synthesized true) this is the API’s base URL instead

string
synthesized
required

True when no spec file was found and install will have to assemble one from endpoints; false when specUrl names a real spec

boolean