Skip to main content

​
Overview

The Housing Management API provides endpoints for creating, reading, updating, and deleting housing listings (hotels, accommodations). It also includes endpoints for managing housing tags and images.
All endpoints require JWT authentication via the Authorization: Bearer {token} header.

​
Get All Houses

Retrieve a list of all housing listings in the system. 
curl -X GET https://localhost:8443/v1/api/houses \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

​
houses
array
Array of HousingDTO objects
[
  {
    "code": 1,
    "location": "Barcelona, Spain",
    "name": "Hotel Mediterranean",
    "price": 150,
    "description": "Beautiful beachfront hotel with modern amenities",
    "stars": 4,
    "acepted": true,
    "tags": [
      { "id": "pool" },
      { "id": "wifi" },
      { "id": "beach" }
    ]
  },
  {
    "code": 2,
    "location": "Madrid, Spain",
    "name": "City Center Apartments",
    "price": 85,
    "description": "Comfortable apartments in the heart of Madrid",
    "stars": 3,
    "acepted": true,
    "tags": [
      { "id": "wifi" },
      { "id": "parking" }
    ]
  }
]

​
Status Codes

CodeDescription
200Successfully retrieved list of houses
403Forbidden - Access denied

​
Get House by ID

Retrieve a specific housing listing by its code (ID).
​
id
integer
required
Code/ID of the house to retrieve (e.g., 1)
curl -X GET https://localhost:8443/v1/api/houses/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

Returns a single HousingDTO object with all housing details. 
{
  "code": 1,
  "location": "Barcelona, Spain",
  "name": "Hotel Mediterranean",
  "price": 150,
  "description": "Beautiful beachfront hotel with modern amenities",
  "stars": 4,
  "acepted": true,
  "tags": [
    { "id": "pool" },
    { "id": "wifi" },
    { "id": "beach" }
  ]
}

​
Status Codes

CodeDescription
200Successfully retrieved house
404House not found
403Forbidden - Access denied

​
Create House

Create a new housing listing with the provided details. 
curl -X POST https://localhost:8443/v1/api/houses \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "Valencia, Spain",
    "name": "Coastal Resort",
    "price": 200,
    "description": "Luxury resort with ocean views",
    "stars": 5,
    "acepted": false,
    "tags": [
      { "id": "pool" },
      { "id": "spa" },
      { "id": "beach" }
    ]
  }'

​
Request Body

​
location
string
required
Physical location/address of the accommodation
​
name
string
required
Name of the housing/hotel
​
price
integer
required
Price per night
​
description
string
Detailed description of the accommodation
​
stars
integer
Star rating from 1 to 5
​
acepted
boolean
Approval status (typically false for new listings, requires admin approval)
​
tags
array
Array of Tag objects representing amenities/features

​
Response

Returns the created housing listing with an auto-generated code. 
{
  "code": 3,
  "location": "Valencia, Spain",
  "name": "Coastal Resort",
  "price": 200,
  "description": "Luxury resort with ocean views",
  "stars": 5,
  "acepted": false,
  "tags": [
    { "id": "pool" },
    { "id": "spa" },
    { "id": "beach" }
  ]
}

​
Status Codes

CodeDescription
201House created successfully
400Invalid input
403Forbidden - Access denied

​
Update House

Update an existing housing listing.
​
id
integer
required
Code/ID of the house to update (e.g., 1)
curl -X PUT https://localhost:8443/v1/api/houses/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "location": "Barcelona, Spain",
    "name": "Hotel Mediterranean Deluxe",
    "price": 175,
    "description": "Updated description with new facilities",
    "stars": 5,
    "acepted": true,
    "tags": [
      { "id": "pool" },
      { "id": "wifi" },
      { "id": "beach" },
      { "id": "gym" }
    ]
  }'

​
Request Body

All HousingDTO fields can be updated (see Create House for field descriptions).

​
Response

Returns the updated housing listing. 
{
  "code": 1,
  "location": "Barcelona, Spain",
  "name": "Hotel Mediterranean Deluxe",
  "price": 175,
  "description": "Updated description with new facilities",
  "stars": 5,
  "acepted": true,
  "tags": [
    { "id": "pool" },
    { "id": "wifi" },
    { "id": "beach" },
    { "id": "gym" }
  ]
}

​
Status Codes

CodeDescription
200House updated successfully
404House not found
400Invalid input
403Forbidden - Access denied

​
Delete House

Delete a housing listing by its code.
​
id
integer
required
Code/ID of the house to delete (e.g., 1)
curl -X DELETE https://localhost:8443/v1/api/houses/1 \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

No content is returned on successful deletion.

​
Status Codes

CodeDescription
204House deleted successfully
404House not found
403Forbidden - Access denied

​
Get Tags by House ID

Retrieve all tags (amenities/features) associated with a specific house.
​
id
integer
required
Code/ID of the house (e.g., 1)
curl -X GET https://localhost:8443/v1/api/houses/1/tags \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Response

​
tags
array
Array of TagDTO objects
[
  { "id": "pool" },
  { "id": "wifi" },
  { "id": "beach" },
  { "id": "parking" }
]

​
Status Codes

CodeDescription
200Successfully retrieved tags
404House not found
403Forbidden - Access denied

​
Housing Images

​
Get Housing Image

Retrieve the image for a specific housing listing. Endpoint: GET /v1/api/houses/{id}/image Authentication: JWT required
​
id
integer
required
Housing ID (code)
Response: Returns the image as image/jpeg Example: 
curl -X GET https://localhost:8443/v1/api/houses/1/image \
  -H "Authorization: Bearer YOUR_JWT_TOKEN"

​
Upload Housing Image

Upload or update the image for a housing listing. Endpoint: PUT /v1/api/houses/{id}/image Authentication: JWT required (Admin only)
​
id
integer
required
Housing ID (code)
Request Body: Multipart form data with the image file Example: 
curl -X PUT https://localhost:8443/v1/api/houses/1/image \
  -H "Authorization: Bearer YOUR_JWT_TOKEN" \
  -F "image=@/path/to/image.jpg"

​
Common Tag IDs

Common tag identifiers used in the Trippins platform:
  • pool - Swimming pool
  • wifi - WiFi internet access
  • beach - Beach access
  • parking - Parking facilities
  • gym - Fitness center/gym
  • spa - Spa facilities
  • restaurant - On-site restaurant
  • bar - Bar/lounge
  • pets - Pet-friendly
  • breakfast - Breakfast included

​
Authentication

All Housing Management endpoints require JWT authentication. Include your token in the Authorization header: 
Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

​
Error Responses

​
error
string
Error type
​
message
string
Detailed error message
{
  "error": "Not Found",
  "message": "House with code 999 not found"
}

Build docs developers (and LLMs) love

Get started for freeTalk to us