Read the caller's evaluated feature flags
The full flag bag for the authenticated user, evaluated server-side. A client fetches this once on launch so flag-gated surfaces render correctly on first paint instead of flickering through default values.
A flag is not an entitlement. Flags control rollout — whether a feature is being served at all — while GET /api/v1/billing/entitlements says whether this caller’s plan includes it.
To decide what to show, use surfaces, not the flags. It is each product surface’s state already resolved from the rollout and the plan together, so a client renders it rather than re-deriving the paywall. The API still enforces every entitlement on the request itself.
surface_reasons and limits carry the words to show about a locked surface or a limit, worded for the client named in X-Finput-Client, so no client writes its own.
Authentication
JWT access token obtained from POST /api/v1/auth/login, or a finput_sk_... API token
Headers
Which client is asking, so every message in the response is worded for it. ios and android get sentences that state a fact and nothing more: no plan, no price, no link. Absent means web, which keeps its existing wording. An unrecognised value is treated like ios and android.
Response
What each product surface is for the caller. Resolved on the server; clients render it and must not recompute it from flags or entitlements.
Why a surface is locked, worded for the client named in X-Finput-Client. Only locked surfaces have a key.
Each finite limit on a surface the caller can use. A key is absent when the limit does not apply: the plan is unlimited, or the surface is not usable.
Rollout switches evaluated for the caller, keyed by flag name. Values are booleans or strings, so type this as a map of string to boolean-or-string.
Flag names are not a public contract and change without notice. Decide what to show from surfaces, not from these.