API Reference

All Flo API endpoints are versioned and documented via Swagger/OpenAPI. This page groups the surface by area; for each group it lists the base path, the typical auth level and representative endpoints.

API Structure

API	Base Path	Auth	Description
Private	/api/v1/...	Cookie session (or OpenIddict bearer)	Main application API
Public	/api/public/v1/...	API token or none	External integrations and public site
Public (misc)	/api/v1/public/..., /api/v1/user/...	API token, none, or OpenIddict bearer	OTP auth, user upsert, immobili access, /user/me
Swagger	/swagger	No (development only)	Interactive API documentation
Health	/health, /health/ready, /health/commerce	No	Liveness/readiness probes

Auth levels used below: none (anonymous), User, Pro, Admin, SuperAdmin, token (public API token with the named permission).

Endpoint Groups

Group	Base path	Typical auth
Authentication	/api/v1/auth, /api/v1/public/auth/otp, /api/v1/oauth, /api/v1/external-auth	none / cookie
Users	/api/v1/users	User / Pro / Admin / SuperAdmin
Activities, Services & Bookings	/api/v1/activities	User / Pro / Admin
Locations	/api/v1/locations	User / Admin
Closures	/api/v1/sc	User / Admin
Subscriptions	/api/v1/studio-plans, /api/v1/client-subscriptions, /api/v1/subscription-plans, /api/v1/subscription-features, /api/v1/my	Pro / Admin / SuperAdmin
Payments	/api/v1/payments	User / Admin / none (webhooks)
Commerce	/api/v1/commerce	User / Admin
Invoicing	/api/v1/einvoicing/*	Admin / SuperAdmin
Blog	/api/v1/articles, /api/v1/categories, /api/v1/authors, /api/v1/comments, /api/v1/strapi-comments	Pro / Admin
Immobili	/api/v1/immobiles, /api/v1/immobili/*	Pro
Catalogo	/api/v1/catalog-items	Pro
Galleries & dynamic content	/api/v1/galleries	User / Pro / SuperAdmin
Website states	/api/v1/website-states	Pro
Forms	/api/v1/forms	Pro / Admin / SuperAdmin
Contacts	/api/v1/contacts	Pro
Communication & Newsletter	/api/v1/newsletter	Pro / Admin / SuperAdmin
Translations	/api/v1/translation	Pro / Admin
Branding	/api/v1/admin/branding, /api/v1/brand-kit, /api/v1/config-editor	Pro / SuperAdmin
Analytics	/api/v1/analytics, /api/v1/business-analytics, /api/v1/web-analytics	Admin / Pro
Settings	/api/v1/admin, /api/v1/api-tokens, /api/v1/webhook-configs, /api/v1/cors-origins, /api/v1/audit-logs, /api/v1/auth-events, /api/v1/email-delivery-logs, /api/v1/logs, /api/v1/quotas, /api/v1/maintenance	Admin / SuperAdmin / maintenance key
Diagnostics	/api/v1/diagnostics, /health	authenticated / SuperAdmin

---

Authentication

Method	Endpoint	Auth	Description
POST	/api/v1/auth/login	none	Password login (rate-limited)
POST	/api/v1/auth/register	none	Registration (gated by enable_registration)
GET	/api/v1/auth/verify-session	none	Verify the current session cookie
POST	/api/v1/auth/logout	cookie	Sign out
POST	/api/v1/auth/forgot-password	none	Request password reset
POST	/api/v1/auth/reset-password	none	Reset password with token
POST	/api/v1/auth/set-password	none (action token)	Set password from an activation link
POST	/api/v1/auth/enable-user	none (action token)	Enable account from an activation link
POST	/api/v1/auth/resend-confirmation	Admin	Resend email confirmation
POST	/api/v1/auth/resend-password-creation	Admin	Resend password-creation email
POST	/api/v1/public/auth/otp/request	none	Request an OTP code (Turnstile)
POST	/api/v1/public/auth/otp/validate	none	Verify an OTP code
POST	/api/v1/public/auth/otp/resend	none	Resend an OTP code (Turnstile)
GET	/api/v1/public/auth/otp/check-email	none	Check whether an email can receive an OTP
GET/POST	/api/v1/oauth/authorize	none	OIDC authorization endpoint (PKCE)
POST	/api/v1/oauth/token	none	OIDC token endpoint
GET/POST	/api/v1/oauth/userinfo	bearer	OIDC userinfo
GET/POST	/api/v1/oauth/logout	none	OIDC end-session
GET	/api/v1/external-auth/config	none	Social-login availability (Google/Apple flags)
POST	/api/v1/external-auth/google	none	Google sign-in
POST	/api/v1/external-auth/apple	none	Apple sign-in
GET/PUT	/api/v1/external-auth-settings	SuperAdmin	Social-login client ids
GET	/api/v1/user/me	OpenIddict bearer	Current user profile for token clients

Users

Method	Endpoint	Auth	Description
GET	/api/v1/users	Pro/Admin	List users (access-policy scoped)
POST	/api/v1/users	Admin	Create user
GET	/api/v1/users/{id}	self/Pro/Admin	User detail
GET	/api/v1/users/check-availability	Pro/Admin	Email/phone availability check
GET	/api/v1/users/{id}/full-detail	SuperAdmin	Full profile (sensitive)
GET	/api/v1/users/{id}/deletion-impact	Admin	What deleting the user would touch
GET	/api/v1/users/me/password-status	User	Whether a password change is forced
PUT	/api/v1/users/me/preferred-content-language	User	Preferred content language
GET	/api/v1/users/pros	User	List professionals
GET	/api/v1/users/user/{userId}/bookings	User	A user's bookings
POST	/api/v1/users/add-entries	Admin	Grant subscription entries
GET/PUT	/api/v1/users/subscriptions, /user/{userId}/subscriptions	Admin	Subscription entitlements
POST	/api/v1/users/{id}/delete	Admin	Delete user
GET	/api/v1/users/gdpr-export?userId=	self/Admin	GDPR data export (JSON download)
POST	/api/v1/users/gdpr-delete	self/Admin	GDPR deletion (email + password confirmation)
POST	/api/v1/users/{id}/enable	Admin	Enable/disable user
POST	/api/v1/users/{id}/set-pro / set-admin	Admin	Role change
POST	/api/v1/users/{id}/set-superadmin	SuperAdmin	Grant/revoke SuperAdmin
POST	/api/v1/users/{id}/change-password	Admin	Force a password change
GET	/api/v1/users/professionals, /{id}/professional-profile	User	Professional profiles
GET/PUT	/api/v1/users/{id}/professional-profile	Pro	Edit professional profile
GET	/api/v1/users/{id}/services	Pro	Services assigned to a professional
POST	/api/v1/users/{userId}/photos	Pro	Add profile photos

Activities, Services, Schedules & Bookings

Base: /api/v1/activities.

Method	Endpoint	Auth	Description
GET	/api/v1/activities/activities	User	List activities (filterBookable, includeHidden, locale)
POST	/api/v1/activities/create	Pro/Admin	Create activity
POST	/api/v1/activities/update	Pro/Admin	Update activity
DELETE	/api/v1/activities/{id}	Pro/Admin	Delete activity
GET	/api/v1/activities/{id}	User	Activity detail
GET	/api/v1/activities/{id}/deletion-impact	Admin	Deletion impact
GET	/api/v1/activities/{id}/subscription-entitlement	User	Subscription entitlement for the activity
GET	/api/v1/activities/schedules	User	Schedules (week/day views)
POST	/api/v1/activities/availability	User	Slot availability
POST	/api/v1/activities/book	User	Create a booking
POST	/api/v1/activities/cancel-book	User	Cancel a booking
POST	/api/v1/activities/{activityId}/photos	Pro	Gallery photos
PUT	/api/v1/activities/{activityId}/photos/main	Pro	Set main photo
POST	/api/v1/activities/positions	Admin	Reorder activities
GET/PUT	/api/v1/activities/admin-overbooking-config	Admin	allow_admin_overbooking toggle
POST	/api/v1/activities/check-capacity-conflicts(-batch)	Admin	Capacity guard checks
POST	/api/v1/activities/cancel-capacity-change	Admin	Cancel scheduled capacity change

Admin bookings slot layout, admin override and excess-user tracking are served by these same endpoints plus /api/v1/users/user/{userId}/bookings and /api/v1/users/users-for-schedule.

Locations

Base: /api/v1/locations.

Method	Endpoint	Auth	Description
GET	/api/v1/locations	User	List locations
GET	/api/v1/locations/{id}	User	Location detail
POST	/api/v1/locations	Admin	Create location
PUT	/api/v1/locations/{id}	Admin	Update location
DELETE	/api/v1/locations/{id}	Admin	Delete location

Closures

Base: /api/v1/sc (studio closures).

Method	Endpoint	Auth	Description
GET	/api/v1/sc	User	List closures
GET	/api/v1/sc/reasons	User	Closure reasons
POST	/api/v1/sc/create	Admin	Create closure
POST	/api/v1/sc/update	Admin	Update closure
DELETE	/api/v1/sc/{id}	Admin	Delete closure
POST/PUT/DELETE	/api/v1/sc/groups[/{id}]	Admin	Closure groups

Subscriptions

Method	Endpoint	Auth	Description
GET	/api/v1/studio-plans	Pro	List studio plans
POST/PUT/DELETE	/api/v1/studio-plans[/{id}]	Admin	Studio plan CRUD
PATCH	/api/v1/studio-plans/{id}/daily-limit	Admin	Daily booking limit
PATCH	/api/v1/studio-plans/{id}/toggle	Admin	Activate/deactivate
GET	/api/v1/client-subscriptions	Pro/Admin	List client subscriptions
GET	/api/v1/client-subscriptions/stats	Pro/Admin	Dashboard stats
GET	/api/v1/client-subscriptions/{id}	Pro/Admin	Detail with check-in history
POST	/api/v1/client-subscriptions / batch / custom	Admin	Create subscriptions
PATCH	/api/v1/client-subscriptions/{id}/suspend / validity / reactivate / cancel	Admin	Lifecycle
POST	/api/v1/client-subscriptions/{id}/refund	Admin	Refund
POST	/api/v1/client-subscriptions/{id}/check-in	Admin	Check in a booking
POST	/api/v1/client-subscriptions/{id}/credit-entry	Admin	Credit an entry
GET/POST/PUT/DELETE	/api/v1/subscription-features[/{id}]	SuperAdmin	Feature catalog
GET/POST/PUT/DELETE	/api/v1/subscription-plans[/{id}]	SuperAdmin	Platform plan catalog
GET/POST/PUT	/api/v1/organization/subscription[/{id}]	Admin/SuperAdmin	Organization subscription
GET	/api/v1/my/subscription, /my/subscriptions, /my/check-ins	User	Self-service view
POST	/api/v1/my/check-in	User	Self-service check-in

Payments

Base: /api/v1/payments (requires enable_online_payments for checkout).

Method	Endpoint	Auth	Description
GET	/api/v1/payments/admin/readiness	Admin	Provider/flag readiness
POST	/api/v1/payments/booking-checkout	User	Start a booking checkout
POST	/api/v1/payments/{provider}/webhook	none	Provider webhook (Stripe/PayPal)
GET	/api/v1/payments/orders/{id}	User	Own order
GET	/api/v1/payments/admin/orders[/{id}]	Admin	Order list/detail
POST	/api/v1/payments/admin/orders/{id}/review	Admin	Review order
POST	/api/v1/payments/orders/{id}/invoice/retry	Admin	Retry invoice emission

Commerce (Orders)

Base: /api/v1/commerce.

Method	Endpoint	Auth	Description
GET	/api/v1/commerce/offers	User	Available offers
POST	/api/v1/commerce/studio-plan-checkout	User	Buy a studio plan
GET	/api/v1/commerce/orders	User	Own orders
GET	/api/v1/commerce/orders/{id}	User	Order detail
POST	/api/v1/commerce/orders/{id}/reconcile	User	Reconcile payment state
GET	/api/v1/commerce/admin/orders[/{id}]	Admin	Admin order list/detail
POST	/api/v1/commerce/admin/orders/{id}/review	Admin	Review order
POST	/api/v1/commerce/admin/orders/{id}/invoice/retry	Admin	Retry invoice emission

Invoicing (Fatture)

Base: /api/v1/einvoicing.

Method	Endpoint	Auth	Description
GET	/api/v1/einvoicing/fatture	Admin	List invoices
POST	/api/v1/einvoicing/fatture	Admin	Create invoice
POST	/api/v1/einvoicing/fatture/import	Admin	Import incoming invoices
POST	/api/v1/einvoicing/fatture/{id}/send / resend	Admin	Send to SDI
POST	/api/v1/einvoicing/fatture/offline/booking/{id} / offline/subscription/{id}	Admin	Offline invoice
POST	/api/v1/einvoicing/fatture/collective	Admin	Collective invoice
GET	/api/v1/einvoicing/fatture/export, /{id}/pdf, /{id}/pdf-branded, /{id}/allegati, /{id}/notifica	Admin	Export/PDF/attachments/notifications
POST	/api/v1/einvoicing/fatture/sync, /{id}/sync	Admin	Sync with the gateway
GET	/api/v1/einvoicing/fatture/unread-count	Admin	Unread incoming count
POST	/api/v1/einvoicing/fatture/{id}/mark-read, /{id}/forward-email	Admin	Mark read / forward by email
CRUD	/api/v1/einvoicing/aziende[/{id}]	SuperAdmin	Company registry
GET/PUT	/api/v1/einvoicing/settings	Admin/SuperAdmin	Gateway settings
POST	/api/v1/einvoicing/settings/test-connection	Admin	Test gateway credentials
GET/PUT	/api/v1/einvoicing/billing-profiles/{userId}	Admin	Billing profile

Blog (Native + Legacy)

Native blog (gated by enable_native_blog), generated controllers:

Method	Endpoint	Auth	Description
CRUD	/api/v1/articles[/{id}]	Pro	Articles (drafts, publish/unpublish, bulk)
GET	/api/v1/articles/admin/by-locale/{locale}, /admin/all	Pro	Admin listings
CRUD	/api/v1/categories[/{id}], /api/v1/authors[/{id}]	Pro	Categories and authors
GET	/api/v1/comments, /comments/reports	Pro	Comment moderation
PATCH/DELETE	/api/v1/comments/{commentId}	Pro	Approve/block/delete comments
POST	/api/v1/comments/reports/{reportId}/resolve	Pro	Resolve a report

Legacy Strapi-backed blog (gated by enable_blogs):

Method	Endpoint	Auth	Description
GET	/api/v1/strapi-comments/flat	Admin	Flat comment list from Strapi
PUT	/api/v1/strapi-comments/{commentId}/approve / block / unblock	Admin	Moderation

Public blog reads: /api/public/v1/articles (article.read), /articles/by-slug/{slug}, /authors (author.read), /categories (category.read); public comments: /api/public/v1/comments/article/{articleId} (GET/POST, Turnstile) and /comments/{commentId}/report.

Immobili

Method	Endpoint	Auth	Description
CRUD	/api/v1/immobiles[/{id}]	Pro	Real-estate entities (generated; custom validation)
GET	/api/v1/immobili/matching/{immobileId}	Pro	Matching preferences
PUT	/api/v1/immobili/matching/{immobileId}/preference/{preferenceId}/status	Pro	Preference status
CRUD	/api/v1/immobili/preferences/...	Pro	Preference templates and per-user/contact preferences
GET	/api/v1/immobili/users/{id}/access-history	Pro	Access history
POST	/api/v1/public/immobili/grant-access	cookie/bearer	Grant client access (accepts terms, logs first access)
GET	/api/v1/public/immobili/check-access/{immobileId}	cookie/bearer	Check access (logs each visit)
POST	/api/v1/public/immobili/accept-terms	cookie/bearer	Accept terms / newsletter preferences

Public API: /api/public/v1/immobiles (immobile.read).

Catalogo

Method	Endpoint	Auth	Description
CRUD	/api/v1/catalog-items[/{id}]	Pro	Catalog entities (generated)
GET	/api/v1/catalog-items/categories	Pro	Categories
CRUD	/api/public/v1/catalog-items[/{id}]	token	Public CRUD (catalog-item.read / catalog-item.write)
POST	/api/public/v1/catalog-items/bulk-delete / bulk-publish / bulk-unpublish	token	Bulk operations
GET	/api/public/v1/catalog-items/published, /by-slug/{slug}	token/none	Published items
POST	/api/public/v1/catalog-items/{id}/attachments/presign / confirm	token	Attachment upload

Galleries & Dynamic Contents (+ History)

Base: /api/v1/galleries (reads available to User; Pro needs the website.gallery access permission).

Method	Endpoint	Auth	Description
GET	/api/v1/galleries[/{id}]	User/Pro	List/detail
POST/PUT/DELETE	/api/v1/galleries[/{id}]	Pro	Create/update/delete
POST/DELETE	/api/v1/galleries/{galleryId}/media	Pro	Add/remove media
GET	/api/v1/galleries/{id}/versions[/{versionId}]	Pro	Content history (requires enable_content_history)
POST	/api/v1/galleries/{id}/versions/{versionId}/restore	Pro	Restore a version
DELETE	/api/v1/galleries/{id}/versions/{versionId}	Pro	Delete a version
GET/PUT	/api/v1/galleries/structure-lock	SuperAdmin	_system_lock_dynamic_content_structure
GET/POST/DELETE/PUT	/api/v1/galleries/{id}/attachments[...]	Pro	Attachments (confirm, reorder, public toggle)
GET	/api/public/v1/galleries/{id}	token (galleries.read)	Public gallery

Dynamic entity CRUD is generated per bounded context (/api/v1/immobiles, /api/v1/catalog-items, …) from Flo.BE/Schemas/*; see Dynamic Entities.

Website States

Method	Endpoint	Auth	Description
GET/PUT	/api/v1/website-states	Pro	Localized date-based states
GET	/api/public/v1/website-state	token (website-states.read)	Public state

Forms (Admin + Public Submit)

Admin (enable_public_forms):

Method	Endpoint	Auth	Description
GET	/api/v1/forms, /forms/overview	Pro	List forms / overview
POST/PUT	/api/v1/forms[/{id}]	Pro	Create/update form
POST	/api/v1/forms/{id}/publish	Pro	Publish
GET	/api/v1/forms/submissions[/{submissionId}], /forms/audit, /forms/export	Pro	Submissions, audit, export
PUT	/api/v1/forms/submissions/{id}/status / contact / legal-hold	Pro	Triage
DELETE	/api/v1/forms/submissions/{id}	Pro	Delete submission
GET/PUT	/api/v1/forms/settings	Admin	Form settings

Public: GET /api/public/v1/forms/{slug}, POST /api/public/v1/forms/{slug}/files/presign, POST /api/public/v1/forms/{slug}/files/{fileId}/confirm, POST /api/public/v1/forms/{slug}/submissions (forms.read / forms.write, Turnstile required).

Contacts

Base: /api/v1/contacts (Communication module).

Method	Endpoint	Auth	Description
GET	/api/v1/contacts	Pro	List contacts
GET	/api/v1/contacts/categories, /labels	Pro	Categories and labels
POST/PUT/DELETE	/api/v1/contacts[/{id}]	Pro	Contact CRUD
POST	/api/v1/contacts/import/preview / import	Pro	CSV import
GET/POST	/api/v1/contacts/import/undo	Pro	Undo an import
GET	/api/v1/contacts/importable-users	Pro	Users importable as contacts
DELETE	/api/v1/contacts	Pro	Bulk delete

Communication & Newsletter

Base: /api/v1/newsletter (Pro base; settings and quota operations are Admin/SuperAdmin).

Method	Endpoint	Auth	Description
GET/POST/PUT/DELETE	/api/v1/newsletter/get-all, create, update, {id}	Pro	Subscriber CRUD
POST	/api/v1/newsletter/import / send	Pro	Import subscribers / send
GET	/api/v1/newsletter/template, /templates/list, /templates/composable, /templates/{name}/preview	Pro	Template registry/preview
GET	/api/v1/newsletter/messages, /messages/library, /messages/{id}	Pro	Message editor/library
POST/PUT/DELETE	/api/v1/newsletter/messages/...	Pro	Draft, confirm, edit, duplicate, clear, delete
GET	/api/v1/newsletter/send-jobs[/{id}], /preflight, /preview	Pro	Send jobs
POST	/api/v1/newsletter/send-jobs/{id}/cancel	Pro	Cancel a job
POST	/api/v1/newsletter/custom/preview / custom/send	Pro	Composed newsletter
GET/PUT	/api/v1/newsletter/settings	SuperAdmin	Provider/quota settings
GET/PUT	/api/v1/newsletter/auto-config	Admin	Automations config
GET/PUT	/api/v1/newsletter/double-opt-in	Admin	Double opt-in
POST	/api/v1/newsletter/settings/reset-quota	SuperAdmin	Reset the monthly quota
POST	/api/v1/newsletter/unsubscribe / resubscribe, suppressions	none/Pro	Opt-out handling
POST	/api/public/v1/newsletter/subscribe, GET /confirm, POST /unsubscribe/one-click	none (newsletters.write)	Public subscribe/confirm/unsubscribe

Translations

Method	Endpoint	Auth	Description
GET	/api/v1/translation/status	Pro/Admin	Provider status
POST	/api/v1/translation/translate	Pro/Admin	Translate content (Ollama/DeepL)

Branding

Method	Endpoint	Auth	Description
GET	/api/v1/admin/branding	Pro/SuperAdmin	Effective branding config
PUT	/api/v1/admin/branding/theme, /brand-meta, /pwa, /login	SuperAdmin	Branding sections
POST/DELETE	/api/v1/admin/branding/assets, /pwa-assets, /login-assets	SuperAdmin	Branding assets
GET/PUT	/api/v1/brand-kit, /brand-kit/library	Pro	Brand kit and library
GET/PUT	/api/v1/config-editor/keys, /theme, /brand-config, /whitelabel	SuperAdmin	Low-level config editor
GET	/api/public/v1/branding	none	Public branding bootstrap

Analytics

Method	Endpoint	Auth	Description
GET	/api/v1/analytics/counters, /counters/{category}/{name}/today, /statistics	Admin	Raw counters
GET	/api/v1/analytics/summary, /dashboard, /categories, /categories/{category}/names	Admin	Dashboard and categories
GET	/api/v1/analytics/pwa-installed-users[/export]	Admin	PWA adoption
DELETE	/api/v1/analytics/purge	SuperAdmin	Purge counters
GET	/api/v1/business-analytics/dashboard	Admin/Pro	Business KPIs
GET	/api/v1/web-analytics/dashboard, /overview, /timeseries, /breakdown, /search, /status	Admin/Pro	GA4/GSC dashboard
GET/PUT/POST	/api/v1/web-analytics/config, /config/test, /backfill	Admin	Analytics configuration

Settings

Method	Endpoint	Auth	Description
GET	/api/v1/admin/feature-flags	none (bootstrap)	Feature flags (no-store)
POST	/api/v1/admin/feature-flags	Admin	Save flags
POST	/api/v1/admin/invalidate-sessions	Admin	Invalidate all sessions
GET	/api/v1/admin/configs	none (bootstrap)	Registration/login branding/storage config
GET/POST/PUT/DELETE	/api/v1/api-tokens[/{id}], /permissions	SuperAdmin	Public API tokens
GET/POST/PUT/DELETE	/api/v1/webhook-configs[/{id}], /entity/{entityName}	SuperAdmin	Webhooks (+ /trigger, /{id}/test)
CRUD	/api/v1/cors-origins[/{id}], /active, /initialize	SuperAdmin	DB-backed CORS origins
GET	/api/v1/audit-logs, /export-query, /entity/{entityName}/{entityId}, /user/{userId}	Admin	Audit trail
GET/POST/PUT/DELETE	/api/v1/audit-logs/export/user/{userId}, /anonymize/user/{userId}, /retention, /purge	SuperAdmin	GDPR/retention operations
POST	/api/v1/auth-events/client	none	Client auth event beacon
GET	/api/v1/auth-events	SuperAdmin	Auth event list
GET	/api/v1/email-delivery-logs[/availability]	SuperAdmin	Email delivery log viewer
GET	/api/v1/logs, /user/{userId}, `/export/csv	json, /periods, /diagnostic, /levels`	SuperAdmin
GET	/api/v1/quotas	Admin	Metered resource quotas
POST	/api/v1/maintenance/purge-users, /email/replay-failed, /mode, /feature-flags/invalidate, /auth/invalidate-sessions	X-Maintenance-Key	Operations endpoints
GET/PUT	/api/v1/localization/settings	Admin/SuperAdmin	Content languages
GET	/api/v1/sidebar/config	authenticated	Server-driven sidebar
GET	/api/v1/schema, /schema/entities, /schema/augmented[/{name}], /schema/entities/{name}	Admin/SuperAdmin	Schema metadata
CRUD	/api/v1/enum-values/...	Admin	Enum value management
GET	/api/v1/geographic/province, /comuni, /cap	User	Geographic reference data
POST	/api/v1/pwa/heartbeat	authenticated	PWA install heartbeat
GET	/manifest.webmanifest	none	PWA manifest
POST	/api/v1/storage/presign, /upload, /confirm, /rename	User	Upload flow (see Media Storage)
POST	/api/v1/media-scan/run / cancel	SuperAdmin	Trigger/cancel a media compatibility scan
GET	/api/v1/media-scan/status / runs	Admin/SuperAdmin	Scan status and run history
GET	/api/v1/media-scan/flagged	Pro	Flagged media (all types or one)

Diagnostics & Health

Method	Endpoint	Auth	Description
GET	/api/v1/diagnostics/version	authenticated	Version, commit, branch, build time
GET	/api/v1/diagnostics/appsettings/development / production	SuperAdmin	Effective configuration (redacted)
GET	/health	none	Liveness + DB check
GET	/health/ready	none	Readiness
GET	/health/commerce	none	Commerce readiness

Response Caching

GET endpoints use HTTP Cache-Control via [ResponseCache]. There is no server-side output cache; booking-boundary reads are explicitly forbidden from using one.

Duration	Data Type	Examples
24h	Static reference data	Geographic province/CAP, analytics categories and names, log periods/levels
1h	Near-static data	Geographic comuni, diagnostics version, immobile preference templates
10min	Schema metadata	Generic schema endpoint (cookie-varying)
No cache	Real-time / flow-critical data	Auth, feature flags, admin configs, schema admin endpoints, locations, home/sidebar, website states, branding, organizations, user data, mutations

API Versioning

All endpoints use URL-based versioning:

/api/v{version:apiVersion}/resource

Controllers use the [ApiVersion] attribute:

[ApiVersion("1.0")]
[Route("api/v{version:apiVersion}/locations")]
public class LocationController : ControllerBase

X-Api-Version is also accepted as a header.

TypeScript Client Generation

The frontend uses auto-generated TypeScript clients from the OpenAPI spec:

cd Flo.FE
npm run generate-proxies

This produces:

• src/app/services/client.ts — Private API client with all DTOs
• src/app/services/public-api-client.ts — Public API client

Run this command whenever backend endpoints change (requires the backend running on localhost:10001).

Public API Tokens

External consumers can access public endpoints using API tokens:

1. SuperAdmin creates tokens in Settings > API Tokens
2. Tokens are scoped to permissions (e.g. activities.read, media.write) and validated against the request Origin/Referer
3. Rate-limited at the Nginx layer and by application-level limiters (presign, media upload, public browser flows)
4. Token is passed via Authorization: Bearer <token> header

Public API groups: activities, professionals, galleries, media, attachments, forms, newsletter, website-state, branding, localization, articles/authors/categories/comments, catalog-items, immobiles.

Swagger

In development, Swagger UI is available at /swagger with two specs:

• Private API: /swagger/v1/swagger.json
• Public API: /swagger/public-v1/swagger.json