Runbook — API Docs Portal

Finnest Power ships an interactive OpenAPI reference (a Scalar portal) for the regulatory APIs your runtime exposes. There are two surfaces: the hosted Finnest portal and the in-cluster portal you enable per deployment.

Hosted Finnest portal (reference-only)

Finnest publishes the current API reference at:

• https://api-docs.finnest.com.br

This is a reference view: it renders the banking, insurance, and public-directory OpenAPI specs so anyone can browse endpoints, schemas, and examples. Its "try it" panel is for exploring request/response shapes against the documented contract — it does not call your runtime. Point integrators here when they only need to read the API surface.

In-cluster portal (docs.<domain>)

Each deployment can publish its own portal at a dedicated public host, docs.<domain>, served from inside your cluster alongside the runtime. Its "try it" panel is wired to your own API at api.<domain>, so an operator or integrator can exercise the live runtime from the rendered page (subject to the API's normal auth).

Enabling it

The portal is off by default. Turn it on with the docs toggle on the deployment target in finnest.toml:

# Named target (profile) form — flat field:
[profile.bank-prod]
# …existing target fields…
docs_enabled = true

# Legacy single-target form — sub-table:
[deployment.docs]
enabled = true

Then run finnest deploy. When the portal is enabled and publicly exposed, the deploy result page prints the URL under Endpoints → docs.

TLS certificate timing (first enable)

docs.<domain> is a brand-new public host, so cert-manager requests its TLS certificate from Let's Encrypt after the Gateway/HTTPRoute applies. That issuance takes a few minutes on the first enable. If you open the URL immediately after deploy and the browser shows a certificate warning (for example NET::ERR_CERT_COMMON_NAME_INVALID), this is the expected transient state — wait a few minutes and reload.

The deploy result page carries this caveat next to the printed URL. To confirm the portal is actually reachable, run:

finnest doctor

The docs-portal checks (reachability + spec truth) run under doctor and report whether docs.<domain> is serving a valid cert and the expected specs.

Verification

• finnest deploy prints an Endpoints → docs field with https://docs.<domain> when the portal is on.
• After cert issuance, opening docs.<domain> renders the Scalar reference with no TLS warning.
• In the in-cluster portal, "try it" against a documented endpoint reaches api.<domain> and returns a real API response (not the portal's own HTML shell).
• finnest doctor reports the docs-portal reachability and spec-truth checks green.