Skip to main content

​
Get started

This guide will walk you through making your first API calls to the Inmobiliaria API. You’ll learn how to check the server health, fetch property listings, and authenticate requests.
Before you begin, make sure you have the API server running. See the Installation guide if you need help setting up the development environment.

​
Quick health check

Start by verifying that the API server is running and healthy.
1

Check server status

Make a simple GET request to the root endpoint:
curl http://localhost:3000/
Expected response:
{
  "status": "ok",
  "message": "Inmobiliaria API Server",
  "timestamp": "2026-03-03T10:30:00.000Z",
  "database": {
    "status": "healthy"
  }
}
2

Verify database health

Check the database connection status:
curl http://localhost:3000/health
A 200 OK response indicates the database is healthy. A 503 Service Unavailable means the database is down.

​
Fetch property listings

Now let’s retrieve some property data from the API.
1

Get all properties

Fetch a paginated list of properties:
curl http://localhost:3000/api/properties
Response structure:
{
  "success": true,
  "data": [
    {
      "id": "123",
      "slug": "hermoso-departamento-palermo-4d",
      "title": "Hermoso departamento en Palermo",
      "price": 250000,
      "currency": "USD",
      "propertyType": "departamento",
      "listingType": "venta",
      "bedrooms": 2,
      "bathrooms": 1,
      "surfaceCoveredM2": 65,
      "images": ["https://..."],
      "location": {
        "city": "Buenos Aires",
        "province": "CABA",
        "neighborhood": "Palermo"
      }
    }
  ],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 47,
    "limit": 10
  }
}
2

Filter and search properties

Use query parameters to find specific properties:
curl "http://localhost:3000/api/properties?propertyType=departamento&listingType=venta&bedrooms=2&minPrice=100000&maxPrice=500000&location=Buenos%20Aires&page=1&limit=20"
Common query parameters:
  • query - Text search across title and location
  • propertyType - Filter by type (e.g., departamento, casa, local)
  • listingType - Filter by operation (e.g., venta, alquiler)
  • minPrice / maxPrice - Price range filter
  • bedrooms / bathrooms - Minimum number of rooms
  • location - Search by city, province, or neighborhood
  • page - Page number (default: 1)
  • limit - Results per page (default: 10)
See the List Properties documentation for all available filters.
3

Get a single property

Retrieve detailed information about a specific property by its ID:
curl http://localhost:3000/api/properties/123
Or by its SEO-friendly slug:
curl http://localhost:3000/api/properties/slug/hermoso-departamento-palermo-4d
Both endpoints return the complete property object with all images, location data, and features.

​
Authentication

Some endpoints require authentication. The API uses session-based authentication with HTTP-only cookies.
1

Understand authentication

The Inmobiliaria API uses Better Auth for authentication. Session cookies are automatically sent with requests when using a browser or properly configured HTTP client.Authentication levels:
  • Public endpoints - No authentication required (e.g., GET /api/properties)
  • User endpoints - Requires any authenticated user (e.g., GET /api/users/profile)
  • Admin endpoints - Requires admin role (e.g., POST /api/properties)
All Better Auth endpoints are available at /api/auth/*. This includes sign in, sign up, and OAuth flows.
2

Check your session

Verify if you have an active session:
curl http://localhost:3000/api/session \
  --cookie-jar cookies.txt \
  --cookie cookies.txt
Response with active session:
{
  "success": true,
  "data": {
    "user": {
      "id": "user_123",
      "name": "John Doe",
      "email": "[email protected]",
      "role": "user",
      "emailVerified": true
    },
    "session": {
      "id": "session_abc",
      "expiresAt": "2026-04-03T00:00:00.000Z"
    }
  }
}
Response without session:
{
  "success": true,
  "data": null
}
3

Make authenticated requests

When making authenticated requests, always include credentials:
curl http://localhost:3000/api/users/profile \
  -H "Content-Type: application/json" \
  --cookie-jar cookies.txt \
  --cookie cookies.txt
Always set credentials: 'include' (fetch) or withCredentials: true (axios) to ensure session cookies are sent with your requests.
4

Handle authentication errors

The API returns specific error responses for authentication failures:401 Unauthorized - No valid session:
{
  "success": false,
  "message": "Authentication required"
}
403 Forbidden - Valid session but insufficient permissions:
{
  "success": false,
  "message": "Admin access required"
}
See the Authentication guide for complete details on the auth flow.

​
Response format

All API responses follow a consistent structure: Successful response: 
{
  "success": true,
  "data": {
    // Response data here
  }
}
Error response: 
{
  "success": false,
  "message": "Error description"
}
Paginated response: 
{
  "success": true,
  "data": [...],
  "pagination": {
    "currentPage": 1,
    "totalPages": 5,
    "totalItems": 47,
    "limit": 10
  }
}

​
Next steps

Now that you’ve made your first API calls, explore these resources to build more advanced integrations:

API Reference

Explore all available endpoints and their parameters

Authentication Guide

Learn about sign up, sign in, and OAuth flows

Installation Guide

Set up your own development environment

Property Images

Learn how to upload and manage property images

Build docs developers (and LLMs) love

Get started for freeTalk to us