Skip to content
Embabel Worlds

Get a cached discovery by name

GET
/api/v1/discovery
curl --request GET \
  --url 'http://localhost:11044/api/v1/discovery?name=example' \
  --header 'X-Embabel-Api-Key: <X-Embabel-Api-Key>'

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Query Parameters

Section titled “Query Parameters”
name
required
string

The discovery name assigned when the API was discovered

Responses

Section titled “Responses”

200

Section titled “200”

The cached discovery

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

404

Section titled “404”

No cached discovery with that name