Developer API Guide

Creating an API Key

To create an API key, navigate to Organization > API.

Click the Generate button to create a new API key. The key will be displayed once — copy it immediately and store it in a secure location.

Important: Generating a new key will immediately revoke any existing key. Only one API key can be active at a time.

Authentication

All API requests must include a valid API key in the Authorization header using the Bearer token scheme.

Authorization: Bearer YOUR_API_KEY

Example Request

curl -X GET https://app.avaroai.com/api/v1/listings \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Accept: application/json"

Rate Limiting

API requests are limited to 20 requests per minute.

When the rate limit is exceeded, the API returns a 429 Too Many Requests response. Wait for the current window to expire before continuing.

Endpoints

The remainder of this guide covers individual API endpoints.

Get Listings

Retrieve a paginated list of your organization’s active listings (20 per page). Use the page query parameter to navigate between pages.

GET https://app.avaroai.com/api/v1/listings
GET https://app.avaroai.com/api/v1/listings?page=2

The endpoint returns the following response.

{
    "data": [
        {
            "id": "9f3a2b1c-...",
            "private_reference": "ORG-001",
            "public_reference": 10042,
            "coordinator": "Jane Smith",
            "property": "Villa",
            "rating": "Premium",
            "rental": false,
            "bedrooms": 3,
            "bathrooms": 2,
            "reception_rooms": 1,
            "parking": ["Garage", "Driveway"],
            "plot_size": 450.00,
            "covered_area": 210.50,
            "title": "Charming Villa with Sea Views",
            "line_1": "12 Coastal Road",
            "line_2": "Seaside Quarter",
            "city": "Paphos",
            "region": "Paphos",
            "post_code": "8042",
            "coordinates": "34.7553,32.4042",
            "published_price": 350000,
            "description": "A beautiful villa...",
            "custom_fields": {
                "habitation_license": 2005
            },
            "photos": [{
                "id": "a1b2c3d4-...",
                "caption": "Front exterior",
                "index": 0,
                "floor_plan": false,
                "large": "url-to-image.jpg",
                "small": "url-to-image.jpg"
            }],
            "created_at": "2026-01-15T10:30:00.000000Z",
            "updated_at": "2026-02-20T14:45:00.000000Z"
        }
    ],
    "links": {
        "first": "https://app.avaroai.com/api/v1/listings?page=1",
        "last": null,
        "prev": null,
        "next": "https://app.avaroai.com/api/v1/listings?page=2"
    },
    "meta": {
        "current_page": 1,
        "from": 1,
        "path": "https://app.avaroai.com/api/v1/listings",
        "per_page": 20,
        "to": 20
    }
}

Each of the fields are described below.

Field	Type	Description
id	string	Unique identifier for the listing.
private_reference	string	Internal reference visible only to your organization.
public_reference	integer	Public-facing reference number.
coordinator	string	Name of the team member managing the listing.
property	string	Property type (e.g. Villa, Apartment, Townhouse).
rating	string	Quality rating assigned to the listing.
rental	boolean	Whether the listing is a rental or a sale.
bedrooms	integer	Number of bedrooms.
bathrooms	integer	Number of bathrooms.
reception_rooms	integer	Number of reception rooms.
parking	array	List of parking types available (e.g. Garage, Driveway).
plot_size	float	Total plot size in square meters.
covered_area	float	Covered (built) area in square meters.
title	string	Display title for the listing.
line_1	string	First line of the property address.
line_2	string	Second line of the property address.
city	string	City where the property is located.
region	string	Region or district of the property.
post_code	string	Postal code.
coordinates	string	Geographic coordinates (latitude, longitude).
published_price	integer	Listed price in the organization’s currency.
description	string	Full property description.
custom_fields	object	Keys and values for custom fields associated with the listing.
photos	array	Collection of photos associated with the listing. See below.
created_at	string	ISO 8601 timestamp of when the listing was created.
updated_at	string	ISO 8601 timestamp of when the listing was last updated.

Each listing includes an array of photos ordered by their index position.

Field	Type	Description
id	string	Unique identifier for the photo.
caption	string	Descriptive caption for the photo.
index	integer	Display order position (starting from 0).
floor_plan	boolean	Whether the photo is a floor plan.
large	string	URL to the full-size image.
small	string	URL to the thumbnail image.

Rules for using photos

If you want to display the photos on your website, then you will need to download them and host your own copies.

AvaroAI does not permit the use of its platform as an image host for your external website. Hotlinking is also not permitted.

Failure to comply with these rules may result in your organization being refused API access, or in extreme cases, suspension from the platform.

You should only use the API to fetch the images if and when they change, then store them on your own server, and display them to your users.