API Reference

All Flo API endpoints are versioned and documented via Swagger/OpenAPI.

API Structure

API	Base Path	Auth Required	Description
Private	/api/v1/...	Yes (cookie)	Main application API
Public	/api/public/v1/...	API token or none	External integrations
Swagger	/swagger	No (dev only)	Interactive API documentation

Endpoint Groups

Authentication

Method	Endpoint	Auth	Description
POST	/api/v1/auth/login	No	Password login
POST	/api/v1/auth/register	No	User registration
POST	/api/v1/auth/forgot-password	No	Request password reset
POST	/api/v1/auth/reset-password	No	Reset password with token
POST	/api/public/v1/otp/request	No	Request OTP code
POST	/api/public/v1/otp/verify	No	Verify OTP code

Users

Method	Endpoint	Auth	Description
GET	/api/v1/users/me	User	Get current user profile
PUT	/api/v1/users/me	User	Update own profile
GET	/api/v1/users/user/{id}/bookings	Admin	Get user's bookings
GET	/api/v1/users/user/{id}/subscriptions	Admin	Get user's subscriptions

Activities & Bookings

Method	Endpoint	Auth	Description
GET	/api/v1/activities	User	List activities
POST	/api/v1/activities	Admin	Create activity
GET	/api/v1/bookings	User	List own bookings
POST	/api/v1/bookings	User	Create booking
DELETE	/api/v1/bookings/{id}	User	Cancel booking

Admin

Method	Endpoint	Auth	Description
GET	/api/v1/admin/feature-flags	Admin	Get feature flags
POST	/api/v1/admin/feature-flags	Admin	Update feature flags
GET	/api/v1/admin/configs	Admin	Get app configuration

Dynamic Entities

Method	Endpoint	Auth	Description
GET	/api/v1/schema/entities	Admin	List dynamic entity schemas
GET	/api/v1/{entity}	Admin	List entity records
POST	/api/v1/{entity}	Admin	Create entity record
PUT	/api/v1/{entity}/{id}	Admin	Update entity record
DELETE	/api/v1/{entity}/{id}	Admin	Delete entity record

Other Endpoints

• Newsletter — Subscription management and sending
• Gallery — Media upload and management
• Locations — Venue/location CRUD
• Translations — Multi-language entity content
• Analytics — Business metrics and KPIs
• Webhooks — Webhook configuration and testing
• Diagnostics — Version, health, performance counters

Response Caching

GET endpoints use Cache-Control headers with tiered durations:

Duration	Data Type	Examples
24h	Static reference data	Geographic provinces, analytics categories
1h	Near-static data	Geographic comuni, diagnostics version
10min	Schema metadata	Entity schemas, augmented fields
5min	Config data	Feature flags, admin configs
2min	Semi-stable lists	Locations, studio closures, professionals
No cache	Real-time data	Auth, bookings, analytics counters, 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}/bookings")]
public class BookingsController : ControllerBase

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.

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 specific hosts (origin validation)
3. Rate-limited via Nginx and application-level limiting
4. Token is passed via Authorization: Bearer <token> header

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