REST API

您的系统以密钥创建者的身份读取 Realton 的项目库和您的 CRM，并写入客户、备注、任务和交易阶段。

Agency 套餐

快速开始

在 Realton 中，由所有者或管理员打开设置 › API 和 MCP，勾选 REST API，然后选择创建密钥。请立即复制：密钥只显示一次。
将密钥保存在服务器的环境变量中：
```
export REALTON_API_KEY="rtk_live_…"
```

发起第一次调用：

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

用 AI 来开发

如今大多数集成都由 AI 编写。把这两个地址和简短的任务说明交给它，其余内容它会自己读。

简介 /docs/api.mdOpenAPI 3.1 /docs/openapi.json

可复制的提示词，填好方括号中的内容：

我想把[我的网站 / 我的 CRM / 我的系统]接入 Realton 的 REST API。
请先阅读简介：https://realton.ai/docs/api.md
完整的 OpenAPI 文档：https://realton.ai/docs/openapi.json
我的技术栈：[例如，部署在 Vercel 上的 Next.js]。
我想实现：[例如，在我的网站上展示 Realton 的迪拜项目，每天刷新一次]。
API 密钥在环境变量 REALTON_API_KEY 中。不要向我索要密钥，也不要把它写进代码。

切勿把密钥粘贴到聊天中。请您自己在服务器上设置 REALTON_API_KEY，只告诉 AI 变量名。

规则

密钥

每次调用都在 Authorization 请求头中发送密钥。只有创建时勾选了 REST API 的密钥才能访问 REST API，且仅在工作区使用 Agency 套餐期间有效。

Authorization: Bearer rtk_live_…

调用以谁的身份执行

调用以创建密钥的成员身份执行，权限与其相同：经纪人只能访问自己的客户，所有者或管理员可以访问全公司的客户。该成员离开工作区后，密钥即失效。

限制

每个密钥每分钟最多 120 次调用。超出后会返回 429，附带 RATE_LIMITED 和 retryAfterSec：等待相应秒数后再调用。

分页

GET /projects 每次最多返回 100 个项目：limit 指定数量，offset 指定起始位置，total 表示总数。

各类 ID

项目标识来自 GET /projects，客户 ID 来自 GET /clients，交易 ID 来自客户卡片 GET /clients/{id} 中的 deals[].id。

不会向客户发送任何内容

任何调用都不会向客户发送内容：POST /brochures 返回一个链接，由经纪人发送。价格均为开发商的原价，使用开发商的货币。

拒绝响应

拒绝响应是带有固定 code 的 JSON。请根据 code 判断，不要根据消息文本判断。

{ "code": "plan_required" }

状态	代码	含义
401	key_required	没有携带密钥的 Authorization 请求头。
401	key_invalid	密钥无法识别或已被撤销。
403	key_scope	该密钥无法访问 REST API。请创建一个勾选了 REST API 的密钥。
403	plan_required	该工作区已不再使用 Agency 套餐。
403	key_member_gone	创建该密钥的人已离开工作区。请创建新密钥。
404	not_found	未找到，或该成员无权查看。
429	RATE_LIMITED	本分钟调用次数过多。请等待 retryAfterSec 秒。
400	place_unknown, whatsapp_invalid, …	字段超出范围，或取值无效。code 会指明是哪个字段。

参考

每个调用的字段和示例，与 OpenAPI 文档一致。

基础地址

https://realton.ai/api/v1

项目库

GET/projectsSearch the catalog

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

参数

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

响应 200

名称	类型	说明
total必填	integer	How many projects fit, across all pages.
offset必填	integer	The offset of this page.
catalogDate必填	string	The day the catalog was last built, YYYY-MM-DD.
projects必填	array

其中每一项

名称	类型	说明
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.

示例

{
  "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.

参数

名称	类型	说明
key必填路径参数	string	The project key from `GET /projects`.
lang 查询参数	en \| he	The language of names, plans and amenities.

响应 200

名称	类型	说明
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"

客户

GET/clientsYour clients

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

参数

名称	类型	说明
q 查询参数	string ≤ 80	A name, a number or an email to look for.

响应 200

名称	类型	说明
clients必填	array

其中每一项

名称	类型	说明
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.

请求体

名称	类型	说明
name必填	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…

示例

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

响应 201

名称	类型	说明
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}.

参数

名称	类型	说明
id必填路径参数	string	The client id from `GET /clients`.
lang 查询参数	en \| he	The language of place names.

响应 200

名称	类型	说明
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.

参数

名称	类型	说明
id必填路径参数	string	The client id.

请求体

名称	类型	说明
text必填	string ≤ 4000	The note.

示例

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

响应 201

名称	类型	说明
id必填	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."}'

任务

GET/tasksYour tasks

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

参数

名称	类型	说明
scope 查询参数	open \| overdue \| today \| upcoming \| someday \| done	open is every task not done.

响应 200

名称	类型	说明
tasks必填	array
counts必填	object	How many tasks in overdue, today, upcoming, someday and done.

其中每一项

名称	类型	说明
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.

请求体

名称	类型	说明
title必填	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.

示例

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

响应 201

名称	类型	说明
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"}'

交易

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

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

参数

名称	类型	说明
id必填路径参数	string	The deal id.

请求体

名称	类型	说明
stage必填	NEW \| CONTACTED \| VIEWING \| EOI \| BOOKED \| WON \| LOST	The new stage.
lostReason	string ≤ 200	Why it was lost; read only with LOST.

示例

{
  "stage": "VIEWING"
}

响应 200

名称	类型	说明
ok必填	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"}'

宣传册

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.

请求体

名称	类型	说明
project必填	string	The project key.
clientId	string	The client it is for: their opens show on their card.
lang必填	en \| he	The language of the brochure.

示例

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

响应 201

名称	类型	说明
id必填	string	The link id.
url必填	string	The address to send: it opens the brochure in the agency's brand.
project必填	string	The project name.
lang必填	string	The language of the brochure.
client必填	string \| null	The client's name, when it is for one.

示例

{
  "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"}'