Skip to main content

API reference

The API reference screen lets you open the interactive documentation of the Control Plane API (Swagger UI, ReDoc, OpenAPI JSON) and read the metadata the API publishes about itself. Portal path: /developer/api. It is used by developers who call the API directly or generate a client.

What the screen shows​

  • Three cards, each opening a new browser tab:
    • Swagger UI: the address <api-url>/docs.
    • ReDoc: the address <api-url>/redoc.
    • OpenAPI JSON: the address <api-url>/openapi.json. <api-url> is the address of the Control Plane API configured in the portal. Each card shows the full address under its label.
  • API metadata: the JSON answer of GET /v1/meta.

Actions​

Button or actionWhat it doesAPI callRoles
Swagger UI cardOpens the interactive documentation in a new tab.None (link)Every signed in user
ReDoc cardOpens the ReDoc documentation in a new tab.None (link)Every signed in user
OpenAPI JSON cardOpens the OpenAPI document in a new tab.None (link)Every signed in user
Retry (error state of API metadata)Reads the metadata again.GET /v1/metaEvery signed in user

Roles​

The portal asks no role on this screen. The links only open the documentation; every call you make from Swagger UI still goes through the authentication and the roles of each route.

Typical tasks​

Try a route from Swagger UI​

  1. Open Swagger UI. It lists every route with its body. Click the Swagger UI card. Expected result: a new tab opens on <api-url>/docs. If it fails: the browser blocked the tab, or the API is not reachable at this address.
  2. Authenticate. Every /v1 route needs a token or an API key. Use the authorize dialog of Swagger UI with your token. Expected result: the routes answer instead of 401. If it fails: create an API key on the API keys page.
  3. Call the route. Fill the parameters and run it. Expected result: the answer of the route. If it fails: read the error code; 403 means a role is missing.

Download the OpenAPI document​

  1. Open the document. Click OpenAPI JSON. Expected result: the JSON document opens. If it fails: check the address shown under the card.
  2. Save it. Save the page from the browser and feed it to your client generator. Expected result: a client of the API. If it fails: compare with the published copy docs/api/openapi-v1.json.

Troubleshooting​

SymptomCauseFix
Error state in API metadataGET /v1/meta failed.Click Retry, then check that the Control Plane runs.
"The Control Plane API cannot be reached"The API is down or the API address of the portal is wrong.Check the Control Plane and the NEXT_PUBLIC_EAI_API_URL setting of the portal.
A card opens a blank pageThe address of the API in the portal is not the public one.Fix the API address of the portal.