Skip to main content

API reference

The Apiome REST API is a FastAPI application. Its reference is published two ways:

  • On this site — the REST API reference, generated from apiome-rest/openapi.yaml: a page per tag with every operation's parameters, request body and responses. It is regenerated whenever the OpenAPI document changes, and the site build fails if it was not.
  • On the running service — the interactive Swagger UI and ReDoc below, which can also send requests.

The REST service listens on http://localhost:8000 by default (the rest service in docker-compose.yml).

ReferenceURLWhat it is
Swagger UIhttp://localhost:8000/docsInteractive, try-it-out reference for every REST route
ReDochttp://localhost:8000/redocRead-optimized rendering of the same spec
OpenAPI documenthttp://localhost:8000/openapi.jsonThe raw machine-readable schema

In production, substitute your deployed host for localhost:8000 (e.g. https://api.example.com/docs). See runbooks/PRODUCTION_DEPLOY.md.

Authenticating in Swagger UI​

The schema declares two security schemes; click Authorize in /docs and supply either:

  • Bearer — a JWT from the UI session (Authorization: Bearer <token>), or
  • ApiKey — a workspace API key sent as the X-API-Key header (tenant-scoped access).

Create an API key in the UI under Dashboard → API keys (/ade/dashboard/api-keys).

Swagger UI for a published spec vs. the API reference​

There are two different Swagger UIs in Apiome — don't confuse them:

You want…Use
To explore the Apiome REST API (import, classes, versions, …)/docs (this page)
To explore a published OpenAPI spec authored in Apiome/v1/swagger/{tenant}/{project}/{version} — see Browse published specs