REST API

A REST API

Seus sistemas leem o catálogo do Realton e o seu CRM e gravam clientes, notas, tarefas e etapas de negócios, em nome de quem criou a chave.

Plano Agency

Primeiros passos

No Realton, um proprietário ou um administrador abre Configurações › API e MCP, marca REST API e escolhe Criar chave. Copie na hora: ela só aparece uma vez.
Guarde-a no seu servidor, numa variável de ambiente:
```
export REALTON_API_KEY="rtk_live_…"
```

Faça sua primeira chamada:

curl "https://realton.ai/api/v1/projects?place=Dubai&beds=2&limit=5" \
  -H "Authorization: Bearer $REALTON_API_KEY"

Construindo com uma IA

Hoje, a maioria das integrações é escrita por uma IA. Passe a ela estes dois endereços e a tarefa em poucas palavras; ela lê o resto sozinha.

O resumo /docs/api.mdOpenAPI 3.1 /docs/openapi.json

Um prompt para copiar, com os colchetes preenchidos:

Quero conectar [meu site / meu CRM / meu sistema] à REST API do Realton.
Leia primeiro o resumo: https://realton.ai/docs/api.md
O documento OpenAPI completo: https://realton.ai/docs/openapi.json
Minha stack: [por exemplo, Next.js na Vercel].
O que eu quero: [por exemplo, mostrar no meu site os projetos do Realton em Dubai, atualizados uma vez por dia].
A chave de API está na variável de ambiente REALTON_API_KEY. Nunca me peça a chave e nunca a escreva no código.

Nunca cole a chave numa conversa. Defina pessoalmente a REALTON_API_KEY no servidor e diga à IA apenas o nome dela.

As regras

A chave

Toda chamada envia a chave no cabeçalho Authorization. Uma chave só libera a REST API se REST API foi marcado na criação, e só enquanto o espaço de trabalho estiver no Agency.

Authorization: Bearer rtk_live_…

Em nome de quem a chamada age

Uma chamada age em nome do membro que criou a chave, com o que ele pode ver: um corretor, os próprios clientes; um proprietário ou um administrador, os da imobiliária. Quando esse membro sai do espaço de trabalho, a chave para de funcionar.

Limites

Até 120 chamadas por minuto por chave. Acima disso, a resposta é 429 com RATE_LIMITED e retryAfterSec: aguarde esse número de segundos e chame de novo.

Paginação

GET /projects retorna até 100 projetos por vez: limit diz quantos, offset onde começar e total quantos existem ao todo.

IDs

A chave de um projeto vem de GET /projects, o id de um cliente de GET /clients e o id de um negócio da ficha do cliente, GET /clients/{id}, em deals[].id.

Nada vai para um cliente

Nenhuma chamada envia nada a um cliente: POST /brochures retorna um link para o corretor enviar. Os preços são os da própria incorporadora, na moeda dela.

Recusas

Uma recusa é um JSON com um code estável. Trate pelo código, nunca pela mensagem.

{ "code": "plan_required" }

Status HTTP	Código	O que significa
401	key_required	Não há cabeçalho Authorization com uma chave.
401	key_invalid	A chave é desconhecida ou foi revogada.
403	key_scope	A chave não libera a REST API. Crie uma com REST API marcado.
403	plan_required	O espaço de trabalho não está mais no Agency.
403	key_member_gone	A pessoa que criou a chave saiu do espaço de trabalho. Crie uma nova chave.
404	not_found	Não encontrado, ou fora do que este membro pode ver.
429	RATE_LIMITED	Chamadas demais neste minuto. Aguarde retryAfterSec segundos.
400	place_unknown, whatsapp_invalid, …	Um campo fora do intervalo ou um valor inválido. O código diz qual.

Referência

Cada chamada com seus campos e um exemplo, como no documento OpenAPI.

Endereço base

https://realton.ai/api/v1

Catálogo

GET/projectsSearch the catalog

Projects that fit, newest first, with their price from. Up to 100 a page.

Parâmetros

Nome	Tipo	O que é
q na query string	string ≤ 120	Words of a project's or a developer's name.
place na query string	string ≤ 80	A city or an emirate, by name or slug: Dubai, Batumi, Limassol.
area na query string	string ≤ 80	An area, by name or slug: Dubai Islands, JVC.
beds na query string	integer 0–9	Bedrooms: 0 is a studio, 4 is four and more.
maxPrice na query string	number	The most the client would pay, in `currency`.
currency na query string	string	The currency of `maxPrice`.
handoverBy na query string	integer 2025–2045	The latest handover year.
lang na query string	en \| he	The language of place and area names.
limit na query string	integer 1–100	How many projects in this page.
offset na query string	integer	How many to skip: the next page starts at offset + limit.

Resposta 200

Nome	Tipo	O que é
totalobrigatório	integer	How many projects fit, across all pages.
offsetobrigatório	integer	The offset of this page.
catalogDateobrigatório	string	The day the catalog was last built, YYYY-MM-DD.
projectsobrigatório	array

Cada um deles

Nome	Tipo	O que é
key	string	The project key, for `GET /projects/{key}` and `POST /brochures`.
name	string	The project's name.
developer	string \| null	The developer's name.
market	ae \| cy \| ge \| om \| sa	ae, cy, ge, om or sa.
place	string \| null	The city or emirate.
area	string \| null	The area.
stage	OFF_PLAN \| UNDER_CONSTRUCTION \| READY	OFF_PLAN, UNDER_CONSTRUCTION or READY.
handover	string \| null	When it is handed over, as the developer says it: Q4 2028.
priceFrom	number \| null	The lowest price, in `currency`.
currency	string	The developer's currency: AED, EUR, USD, OMR, SAR.
bedrooms	array	The bedroom counts it has; 0 is a studio.
commissionPct	number \| null	The agent's commission, in percent.
photo	string \| null	A photo of it.

Exemplo

{
  "total": 312,
  "offset": 0,
  "catalogDate": "2026-10-24",
  "projects": [
    {
      "key": "studio:soma-residences",
      "name": "Soma Residences",
      "developer": "Origami Properties",
      "market": "ae",
      "place": "Dubai",
      "area": "Dubai Islands",
      "stage": "OFF_PLAN",
      "handover": "Q4 2028",
      "priceFrom": 1670000,
      "currency": "AED",
      "bedrooms": [
        1,
        2,
        3
      ],
      "commissionPct": 5,
      "photo": "https://…/soma-residences.avif"
    }
  ]
}

curl

curl -X GET "https://realton.ai/api/v1/projects" \
  -H "Authorization: Bearer $REALTON_API_KEY"

GET/projects/{key}One project in full

Unit types with sizes and prices, payment plans, amenities, the gallery and what is nearby.

Parâmetros

Nome	Tipo	O que é
keyobrigatório no caminho	string	The project key from `GET /projects`.
lang na query string	en \| he	The language of names, plans and amenities.

Resposta 200

Nome	Tipo	O que é
entry	object	Its catalog line: the same figures as `GET /projects`, with `title` for the name and slugs for place and area.
placeName	string \| null	The city or emirate.
areaName	string \| null	The area.
unitTypes	array	Each unit type: label, beds, available (from the inventory), sizeSqft, sizeSqm, priceFrom, currency, pricePerArea, areaUnit.
plans	array	Payment plans: each with its steps (label, timing, percent, phase) and its share before and after handover.
dldPct	number \| null	Dubai's registration fee on booking, in percent; null elsewhere.
amenities	array	What the project offers.
gallery	object	count, and images with their url.
nearby	array	Places near it: category, name, km.

curl

curl -X GET "https://realton.ai/api/v1/projects/{key}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

Clientes

GET/clientsYour clients

An agent's own clients; an owner's or an admin's, the agency's. Last active first.

Parâmetros

Nome	Tipo	O que é
q na query string	string ≤ 80	A name, a number or an email to look for.

Resposta 200

Nome	Tipo	O que é
clientsobrigatório	array

Cada um deles

Nome	Tipo	O que é
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
source	string	Where they came from.
stage	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The stage of their most advanced open deal.
project	string \| null	The project of that deal.
lastActivityAt	string	The last thing that happened with them, ISO date-time.
ownerUserId	string	The member they belong to.
openTasks	integer	Their open tasks.

curl

curl -X GET "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clientsA new client

A name and at least one way to reach them is the usual; a name alone is accepted.

Corpo

Nome	Tipo	O que é
nameobrigatório	string ≤ 120	Their full name.
whatsapp	string ≤ 30	A number with its country code, +971 50 555 0147.
email	string ≤ 200	An email address.
language	string ≤ 5	The language they speak, a two-letter code: en, ar, he, ru…

Exemplo

{
  "name": "Elena Petrova",
  "whatsapp": "+971505550147",
  "language": "ru"
}

Resposta 201

Nome	Tipo	O que é
id	string	The client id.
name	string \| null	Their name.
language	string \| null	The language they speak.
whatsapp	string \| null	Their number, E.164.
email	string \| null	Their email.
ownerUserId	string	The member they belong to.
updatedAt	string	ISO date-time.

curl

curl -X POST "https://realton.ai/api/v1/clients" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name":"Elena Petrova","whatsapp":"+971505550147","language":"ru"}'

GET/clients/{id}A client's card

Their details, what they are looking for, and their deals with each deal's id for PATCH /deals/{id}.

Parâmetros

Nome	Tipo	O que é
idobrigatório no caminho	string	The client id from `GET /clients`.
lang na query string	en \| he	The language of place names.

Resposta 200

Nome	Tipo	O que é
id	string	The client id.
name	string \| null	Their name.
whatsapp	string \| null	Their number.
email	string \| null	Their email.
language	string \| null	The language they speak.
requirements	object	What they are looking for: places, bedrooms, budget, handover.
ownerName	string \| null	The member they belong to.
deals	array	Their deals: id, stage, projectKey, projectTitle, beds, unitLabel, price, currency, commissionPct, commission, lostReason.

curl

curl -X GET "https://realton.ai/api/v1/clients/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/clients/{id}/notesA note on a client's card

Free text on the client's timeline, as the member.

Parâmetros

Nome	Tipo	O que é
idobrigatório no caminho	string	The client id.

Corpo

Nome	Tipo	O que é
textobrigatório	string ≤ 4000	The note.

Exemplo

{
  "text": "Wants a sea view, budget AED 2M, moving in 2028."
}

Resposta 201

Nome	Tipo	O que é
idobrigatório	string	The note id.

curl

curl -X POST "https://realton.ai/api/v1/clients/{id}/notes" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"text":"Wants a sea view, budget AED 2M, moving in 2028."}'

Tarefas

GET/tasksYour tasks

The member's own tasks, with how many there are in each scope.

Parâmetros

Nome	Tipo	O que é
scope na query string	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

Resposta 200

Nome	Tipo	O que é
tasksobrigatório	array
countsobrigatório	object	How many tasks in overdue, today, upcoming, someday and done.

Cada um deles

Nome	Tipo	O que é
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X GET "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY"

POST/tasksA new task

A task at a time, on a day, or with no date; for a client when clientId is given.

Corpo

Nome	Tipo	O que é
titleobrigatório	string ≤ 200	What to do.
note	string ≤ 2000	More words about it.
dueAt	string ≤ 40	When: an ISO date-time with its offset, 2026-10-25T11:00:00+04:00. With dueKind DAY, any time on that day.
dueKind	AT \| DAY \| NONE	AT for a time, DAY for a whole day, NONE for no date.
clientId	string	The client the task is for.

Exemplo

{
  "title": "Call Elena about Soma Residences",
  "dueAt": "2026-10-25T11:00:00+04:00",
  "dueKind": "AT",
  "clientId": "cm2x8k1qz0001abcdeffghijk"
}

Resposta 201

Nome	Tipo	O que é
id	string	The task id.
title	string	What to do.
note	string \| null	More words about it.
dueAt	string \| null	When, ISO date-time.
dueKind	AT \| DAY \| NONE	AT, DAY or NONE.
doneAt	string \| null	When it was done.
scope	overdue \| today \| upcoming \| someday \| done	Where it stands now, in the member's time zone.
contact	object \| null	The client it is for: id and name.
dealId	string \| null	The deal it belongs to.

curl

curl -X POST "https://realton.ai/api/v1/tasks" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"title":"Call Elena about Soma Residences","dueAt":"2026-10-25T11:00:00+04:00","dueKind":"AT","clientId":"cm2x8k1qz0001abcdeffghijk"}'

Negócios

PATCH/deals/{id}Move a deal's stage

A deal's id is on its client's card (GET /clients/{id}, deals[].id).

Parâmetros

Nome	Tipo	O que é
idobrigatório no caminho	string	The deal id.

Corpo

Nome	Tipo	O que é
stageobrigatório	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

Exemplo

{
  "stage": "VIEWING"
}

Resposta 200

Nome	Tipo	O que é
okobrigatório	boolean

curl

curl -X PATCH "https://realton.ai/api/v1/deals/{id}" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"stage":"VIEWING"}'

Folhetos

POST/brochuresA brochure link

A brochure of a project in your brand, with open tracking, for the agent to send. Realton does not send it.

Corpo

Nome	Tipo	O que é
projectobrigatório	string	The project key.
clientId	string	The client it is for: their opens show on their card.
langobrigatório	en \| he	The language of the brochure.

Exemplo

{
  "project": "studio:soma-residences",
  "clientId": "cm2x8k1qz0001abcdeffghijk",
  "lang": "en"
}

Resposta 201

Nome	Tipo	O que é
idobrigatório	string	The link id.
urlobrigatório	string	The address to send: it opens the brochure in the agency's brand.
projectobrigatório	string	The project name.
langobrigatório	string	The language of the brochure.
clientobrigatório	string \| null	The client's name, when it is for one.

Exemplo

{
  "id": "cm2x9p0aa0002abcdeffghijk",
  "url": "https://realton.ai/b/Hk3…",
  "project": "Soma Residences",
  "lang": "en",
  "client": "Elena Petrova"
}

curl

curl -X POST "https://realton.ai/api/v1/brochures" \
  -H "Authorization: Bearer $REALTON_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"project":"studio:soma-residences","clientId":"cm2x8k1qz0001abcdeffghijk","lang":"en"}'