Skip to main content

​
Get All Amenities

Retrieve a list of all active amenities across all communities. 
curl -X GET "https://api.happyhabitat.com/api/amenities" \
  -H "Authorization: Bearer <your_token>"
Response Example: 
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "nombre": "Swimming Pool",
    "descripcion": "Olympic-size swimming pool with diving board and heated water",
    "reglas": "No running, no diving in shallow end, shower before entering, children under 12 must be supervised",
    "costo": 10.00,
    "fechaAlta": "2024-01-15T00:00:00Z",
    "imagen": "/images/amenities/pool.jpg",
    "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityName": "Residencial Los Pinos",
    "capacidadMaxima": 50,
    "numeroReservacionesSimultaneas": 5,
    "createdAt": "2024-01-15T10:30:00Z"
  },
  {
    "id": "8ba95f74-6827-5673-c4gd-3d074g77bgb7",
    "nombre": "Tennis Court",
    "descripcion": "Professional-grade tennis court with night lighting",
    "reglas": "Proper tennis shoes required, 2-hour time limit during peak hours",
    "costo": 15.00,
    "fechaAlta": "2024-02-01T00:00:00Z",
    "imagen": "/images/amenities/tennis.jpg",
    "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityName": "Residencial Los Pinos",
    "capacidadMaxima": 4,
    "numeroReservacionesSimultaneas": 1,
    "createdAt": "2024-02-01T08:00:00Z"
  }
]

​
Get Amenities by Community

Retrieve all amenities for a specific community. The communityId parameter is optional; if omitted or null, returns amenities without a specific community association. 
curl -X GET "https://api.happyhabitat.com/api/amenities/community/{communityId}" \
  -H "Authorization: Bearer <your_token>"
Path Parameters:
  • communityId (Guid, optional): Community unique identifier. If omitted or null, returns amenities without community association.
Response Example: 
[
  {
    "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
    "nombre": "Gym",
    "descripcion": "Fully equipped fitness center with modern equipment",
    "reglas": "Clean equipment after use, 90-minute session limit during peak hours",
    "costo": null,
    "fechaAlta": "2024-03-01T00:00:00Z",
    "imagen": "/images/amenities/gym.jpg",
    "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "communityName": "Residencial Los Pinos",
    "capacidadMaxima": 20,
    "numeroReservacionesSimultaneas": 20,
    "createdAt": "2024-03-01T06:00:00Z"
  }
]

​
Get Amenity by ID

Retrieve details of a specific amenity by its unique identifier. 
curl -X GET "https://api.happyhabitat.com/api/amenities/{id}" \
  -H "Authorization: Bearer <your_token>"
Path Parameters:
  • id (Guid, required): Amenity unique identifier
Response Example: 
{
  "id": "3fa85f64-5717-4562-b3fc-2c963f66afa6",
  "nombre": "Clubhouse",
  "descripcion": "Spacious clubhouse available for private events and community gatherings",
  "reglas": "Advanced reservation required, must be left clean, no smoking indoors, maximum 100 guests",
  "costo": 50.00,
  "fechaAlta": "2024-01-10T00:00:00Z",
  "imagen": "/images/amenities/clubhouse.jpg",
  "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
  "communityName": "Residencial Los Pinos",
  "capacidadMaxima": 100,
  "numeroReservacionesSimultaneas": 1,
  "createdAt": "2024-01-10T09:00:00Z"
}
Status Codes:
  • 200 OK - Amenity found and returned
  • 404 Not Found - Amenity with specified ID does not exist

​
Create Amenity

Create a new amenity for a community. 
curl -X POST "https://api.happyhabitat.com/api/amenities" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Basketball Court",
    "descripcion": "Full-size outdoor basketball court with professional hoops",
    "reglas": "No glass containers, respect other players, first come first served",
    "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "costo": null,
    "fechaAlta": "2024-03-15T00:00:00Z",
    "imagen": "/images/amenities/basketball.jpg",
    "capacidadMaxima": 10,
    "numeroReservacionesSimultaneas": 2,
    "createdByUserId": "9fa85f64-5717-4562-b3fc-2c963f66afa6"
  }'
Request Body: 
{
  "nombre": "string (required)",
  "descripcion": "string (required)",
  "reglas": "string (required)",
  "communityId": "Guid (required)",
  "costo": "decimal (optional)",
  "fechaAlta": "DateTime (required)",
  "imagen": "string (optional)",
  "capacidadMaxima": "integer (optional)",
  "numeroReservacionesSimultaneas": "integer (optional)",
  "createdByUserId": "Guid (optional)"
}
Response: Returns the created amenity object with 201 Created status and a Location header pointing to the new resource. Status Codes:
  • 201 Created - Amenity created successfully
  • 400 Bad Request - Invalid input data or business rule violation (e.g., invalid community ID)
Response Example: 
{
  "id": "4gb06g85-7928-6784-d5he-4e185h88chc8",
  "nombre": "Basketball Court",
  "descripcion": "Full-size outdoor basketball court with professional hoops",
  "reglas": "No glass containers, respect other players, first come first served",
  "costo": null,
  "fechaAlta": "2024-03-15T00:00:00Z",
  "imagen": "/images/amenities/basketball.jpg",
  "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
  "communityName": "Residencial Los Pinos",
  "capacidadMaxima": 10,
  "numeroReservacionesSimultaneas": 2,
  "createdAt": "2024-03-15T14:22:00Z"
}

​
Update Amenity

Update an existing amenity’s information. 
curl -X PUT "https://api.happyhabitat.com/api/amenities/{id}" \
  -H "Authorization: Bearer <your_token>" \
  -H "Content-Type: application/json" \
  -d '{
    "nombre": "Swimming Pool",
    "descripcion": "Olympic-size swimming pool with diving board, heated water, and new LED lighting",
    "reglas": "No running, no diving in shallow end, shower before entering, children under 12 must be supervised, pool closes at 10 PM",
    "communityId": "7fa85f64-5717-4562-b3fc-2c963f66afa6",
    "costo": 12.00,
    "fechaAlta": "2024-01-15T00:00:00Z",
    "imagen": "/images/amenities/pool-updated.jpg",
    "capacidadMaxima": 60,
    "numeroReservacionesSimultaneas": 6
  }'
Path Parameters:
  • id (Guid, required): Amenity unique identifier
Request Body: 
{
  "nombre": "string (required)",
  "descripcion": "string (required)",
  "reglas": "string (required)",
  "communityId": "Guid (required)",
  "costo": "decimal (optional)",
  "fechaAlta": "DateTime (required)",
  "imagen": "string (optional)",
  "capacidadMaxima": "integer (optional)",
  "numeroReservacionesSimultaneas": "integer (optional)"
}
Response: Returns the updated amenity object. Status Codes:
  • 200 OK - Amenity updated successfully
  • 400 Bad Request - Invalid input data or business rule violation
  • 404 Not Found - Amenity with specified ID does not exist

​
Delete Amenity

Soft delete an amenity. This operation marks the amenity as inactive rather than permanently removing it from the database, preserving historical data and relationships. 
curl -X DELETE "https://api.happyhabitat.com/api/amenities/{id}" \
  -H "Authorization: Bearer <your_token>"
Path Parameters:
  • id (Guid, required): Amenity unique identifier
Response: Returns 204 No Content on successful deletion. Status Codes:
  • 204 No Content - Amenity deleted successfully
  • 404 Not Found - Amenity with specified ID does not exist
Notes:
  • This operation performs a soft delete by setting the IsActive flag to false
  • The amenity data is retained in the system for historical purposes and reporting
  • Deleted amenities will not appear in standard listing queries (GET all amenities)
  • Related reservations and booking history are preserved

​
Error Handling

All endpoints may return the following error responses:

​
400 Bad Request

{
  "message": "Invalid operation or validation error description"
}
Common causes:
  • Invalid CommunityId (community does not exist)
  • Missing required fields
  • Invalid data format (e.g., invalid GUID, negative capacity)
  • Business rule violations

​
401 Unauthorized

{
  "message": "Unauthorized access - invalid or missing token"
}

​
403 Forbidden

{
  "message": "Insufficient permissions - requires ADMIN_COMPANY or SYSTEM_ADMIN role"
}

​
404 Not Found

{
  "message": "Resource not found"
}
Common causes:
  • Amenity ID does not exist
  • Attempting to access a soft-deleted amenity

​
Best Practices

  1. Amenity Creation
    • Always validate that the CommunityId exists before creating an amenity
    • Provide clear, descriptive names for easy identification by residents
    • Include comprehensive rules to set clear expectations
    • Use high-quality images (Imagen) for visual recognition in resident apps
  2. Capacity Management
    • Set CapacidadMaxima based on safety regulations and comfort
    • Configure NumeroReservacionesSimultaneas to prevent overbooking
    • Consider peak usage times when setting limits
    • Review and adjust capacity settings regularly based on usage patterns
  3. Cost Configuration
    • Leave Costo as null for free amenities
    • Set clear, transparent pricing for paid facilities
    • Consider maintenance and operational costs when determining pricing
    • Communicate cost changes to residents well in advance
  4. Update Operations
    • Fetch the current amenity data before updating to avoid overwriting recent changes
    • Update only the fields that need to change
    • Validate business rules before submitting updates
    • Include audit information (updatedByUserId) when available
  5. Deletion Strategy
    • Use soft delete (DELETE endpoint) instead of hard deletion
    • Never delete amenities with existing reservations
    • Archive inactive amenities rather than removing them permanently
    • Maintain historical records for reporting and analytics

Build docs developers (and LLMs) love

Get started for freeTalk to us