The Stay Sidekick REST API is a Flask application served by Gunicorn, accessible atDocumentation Index
Fetch the complete documentation index at: https://mintlify.com/sdurutr436/stay-sidekick/llms.txt
Use this file to discover all available pages before exploring further.
/api/ through the Nginx reverse proxy. All endpoints return JSON with a consistent {"ok": true/false} envelope. Authenticated endpoints require a JWT Bearer token obtained via POST /api/auth/login plus a CSRF token for all state-changing operations.
Base URL
| Environment | Base URL |
|---|---|
| Local (Docker Compose) | http://localhost/api |
| Production (Railway) | https://stay-sidekick.com/api |
Response Envelope
Every response from the Stay Sidekick API follows the same top-level structure:Success
Error
warnings array alongside ok: true when partial issues occur (e.g., XLSX import with skipped rows).
HTTP Status Codes
| Code | Meaning |
|---|---|
200 | OK — request succeeded |
201 | Created — resource was created |
400 | Bad Request — missing or malformed JSON body |
401 | Unauthorized — missing, expired, or invalid JWT |
403 | Forbidden — CSRF token invalid or insufficient role |
404 | Not Found — resource does not exist |
409 | Conflict — duplicate resource (e.g., duplicate email) |
413 | Payload Too Large — uploaded file exceeds size limit |
422 | Unprocessable Entity — validation error in request payload |
429 | Rate Limit Exceeded — too many requests from this IP |
Authentication
All protected endpoints require anAuthorization: Bearer <token> header. Obtain a token by calling POST /api/auth/login. State-changing endpoints also require an X-CSRF-Token header.
See the Authentication page for the full flow.
Rate Limiting
Rate limits are applied per IP using Flask-Limiter:| Endpoint | Limit |
|---|---|
POST /api/auth/login | 10 requests/hour |
POST /api/contact | Configurable via RATE_LIMIT_CONTACT (default: 5/hour) |
POST /api/contacto | 10 requests/hour |
GET /api/csrf-token | 30 requests/hour |
POST /api/apartamentos/sincronizacion/smoobu | 10 requests/hour |
POST /api/apartamentos/importacion | 20 requests/hour |
POST /api/apartamentos/importacion/preview | 30 requests/hour |
POST /api/heatmap/xlsx | 30 requests/hour |
POST /api/notificaciones/checkin-tardio/checkins | 20 requests/hour |
429 Too Many Requests.
Multi-Tenant Isolation
Every authenticated request automatically scopes data to the authenticated user’s company. Theempresa_id claim in the JWT is used to filter all database queries. It is not possible to access another company’s data through normal authenticated endpoints.
Superadmins can operate on any company by including
?empresa_id=<uuid> as a query parameter on user management endpoints.Health Check
TheGET /api/health endpoint returns a health status without requiring authentication. Use it to verify the backend is running:
API Reference
Authentication
Obtain a JWT token and understand CSRF protection for all state-changing requests.
Apartments
CRUD operations, Smoobu sync, and XLSX import for the apartment catalog.
Heat Map
Generate daily operational load from PMS or XLSX, configure intensity thresholds.
Notifications
Detect late check-ins and manage notification templates.
Contacts
Google OAuth 2.0 setup, sync operations, and CSV export fallback.
Vault
Template CRUD and AI assistance for communications.
Users & Companies
Multi-tenant management: companies (superadmin) and per-company users.
Profile
User profile, password change, and integration configuration.
Public Endpoints
Unauthenticated endpoints for the public contact and access-request forms.