Build a tool for EstateLensThe connected-tools API · contract 2
Last updated: November 2026
An agent on EstateLens can connect outside tools to their account. A tool can be anything that makes HTTPS requests: a browser extension, a web page, a server. It pairs through a link the agent answers in EstateLens, says what it offers in its own words, and from then on receives the posts the agent marks for it, does them, and reports what happened.
You need no approval from us and no API key of your own. The pairing the agent makes is the only credential: it opens that agent's jobs for your tool and nothing else.
How it works
- Pair. Your tool asks to connect and opens the link it gets for the agent: EstateLens's own page, where they see your tool's name and options and approve. Your tool collects its key.
- Ready. Until your tool can post, it says so: still setting up, or getting ready. The agent sees it on your tool in Settings → Connected tools (כלים מחוברים).
- Offer. Each option you declare becomes a switch in EstateLens, under your tool's name, where the agent publishes a listing's post.
- Targets (optional). If an option posts to places the agent chooses between (boards, pages, channels), list them. The agent switches on the ones to use.
- Jobs. When the agent publishes a post with your option on, EstateLens queues a job for each target. Your tool takes the jobs one at a time: put a copy up, see that it is still there, take it down.
- Answers. For every job, your tool reports what happened, with the link to the copy. The agent sees it in EstateLens next to the post.
Basics
Every endpoint is under https://api.estatelens.ai/tool-api. Bodies and answers are JSON. Any origin may call these endpoints (CORS answers *); never send cookies, since none are used. Photo links on img.estatelens.ai can be read from any origin too.
| Header | Value |
|---|---|
Authorization | Bearer <key> on every request after pairing. |
X-Tool-Contract | 2. Without it you speak contract 1, and are handed only jobs to put copies up. |
X-Tool-Install | An id your tool makes for itself once and keeps for good: 8–64 characters of A–Z a–z 0–9 _ - (a UUID works). Send it on every request, pairing included. When the same install pairs again, it gets its own connection back, with everything it put out there, instead of a new one. A service that runs your tool for many agents (a browser it hosts for each) may send one install for all of them: connections are per agent, so each agent who pairs again, from any device, gets back their own. |
1. Pair
POST/tool-api/connect
Ask to connect, naming your tool and its options.
{
"name": "My Board Poster",
"return_to": "https://myboard.example/connected",
"logo": "data:image/png;base64,iVBORw0KGgo...",
"actions": [
{ "key": "my_board", "place": "listing_post", "label": "Post to My Board",
"hint": "One post per board", "targets_label": "Boards" }
]
}| Field | Rules |
|---|---|
name | Required, up to 60 characters. The agent sees it when approving, and on every switch. |
logo | Optional: your logo, as the image itself — a data:image/png;base64,… URI of a PNG, JPEG or WebP image, at most 32 KB (square, 128×128 or more, reads best). The agent sees it when approving and on your connection. Never an address: EstateLens fetches nothing from your servers. Sent again when you connect again, it replaces the one before. |
actions | 1 to 10 options. |
key | Required, unique, up to 40 of a–z 0–9 _. Jobs name it in action. |
place | Required. Where the switch shows. Today one place: listing_post, a post about a listing. |
label | Required, up to 60 characters: the switch's words. |
hint | Optional, up to 120 characters, under the label. |
targets_label | Optional, up to 30 characters. Set it when the option posts to targets you list (step 3); it names them. |
return_to | Required, up to 500 characters: where the agent goes back to after answering on your link (below). https, or http to localhost, 127.0.0.1 or [::1] while you build. No #fragment and no user:password@. Put your own state in its query if you need one. |
The answer is 201 with { "code", "claim", "expires_in", "allow_url" }. Keep the claim secret: it collects your key. Without return_to the answer is 403 { "error": "tool_connect_server_only" }: a tool connects only by sending the agent back to an address of its own.
Send the agent to the link
Open allow_url for the agent: EstateLens's own page, with the code in it, valid for expires_in seconds (10 minutes). Signed in to EstateLens, the agent sees your tool's name, its options and the code (6 characters; show it on your side too, so they see it is the same), and answers there. The page shows them your return_to's host and then takes them back to it, with estatelens=approved and a one-time proof, or estatelens=declined, added to its query. The address is fixed when you ask to connect, so whoever holds the link cannot change it.
The proof is what ties the agent who answered to the browser that comes back: your key is handed only with it, so finish the connection where the agent arrives — in their session with you — never in one that did not receive it. A link someone else started and sent to the agent cannot be finished by them: they hold the claim, never the proof.
POST/tool-api/connect/key
Send { "claim": "...", "proof": "..." } once the agent is back, the proof as the address they came back to carries it. Asked before the agent has approved, the answer is 202 { "pending": true }. Once they have, it is 200 { "key", "tool_id" }, handed once: store the key. A link answered yes, asked without its proof or with another, is 403 { "error": "tool_connect_proof" } and takes nothing: ask again with the proof. If the agent answered no on your link, it is 403 { "error": "tool_connect_declined" }, once: stop asking. The agent can disconnect your tool in EstateLens at any time; the key then stops working.
A new connection starts as ok. If your tool cannot post yet, say so as soon as you have the key: setup or preparing (see Who you are).
2. Who you are
GET/tool-api/me
Answers { "tool": { "id", "name" }, "actions": [...], "state", "state_told_at" }. Use it to check the key still works, for example when your tool starts.
Disconnecting yourself
DELETE/tool-api/me
Your tool disconnects itself, for example when the agent closes their account with you. The answer is 200 { "disconnected": true }: it is the same as the agent disconnecting you in EstateLens. The key stops working, and the jobs still waiting for you are cancelled. It works even when the agent's plan no longer allows posting. Asked again, the answer is 401. Pairing the same install later gives the connection back.
Telling the agent where you stand
PUT/tool-api/me/state
Whenever your tool cannot post, say so: it is not set up yet, it is getting ready, or the place you post to stopped it and only the agent can fix that. This matters most for a tool nobody is looking at, such as one running on a server. EstateLens shows the state on your tool in the agent's Settings. When you move into a state that needs the agent, it notifies them once, with your page for fixing it. ok and preparing need nothing from them: they notify nothing, and a notification sent before goes away. Send a state when it changes. You may also send it again after each check of your own, changed or not: EstateLens keeps when you last told it, and a state told again notifies nobody.
{ "state": "setup", "note": "Sign in to the site in your account with us", "fix_url": "https://yours.example/account" }
{ "state": "preparing", "note": "Reading your boards. This can take a few minutes" }
{ "state": "needs_sign_in", "note": "The site signed us out", "fix_url": "https://yours.example/login" }| Field | Rules |
|---|---|
state | Required. ok (you can post); setup (connected, but your own setting up is not done: the agent finishes it with you); preparing (set up, and getting ready by yourself, such as reading the targets the agent will pick from: the agent sees your tool loading, and its targets list too while it is empty); needs_sign_in (your sign-in at the place is gone); needs_confirm (the place asks the agent to confirm something); held (the place stopped you for a while); refused (the place refuses the account). |
until | Only with held, optional: when the hold ends, ISO 8601 with Z, within 30 days. |
note | Optional, up to 120 characters: your own words for the agent. Dropped with ok. |
fix_url | Optional: your page where the agent fixes it. The rules of return_to apply. Dropped with ok. |
The answer is 200 { "state": "..." }. GET /tool-api/me also returns your state, as EstateLens holds it, and state_told_at: when you last told it (ISO 8601 with Z; null before you first do).
A usual start: setup right after pairing, until the agent finishes with you; preparing while you read your targets; send them (section 3); then ok.
3. Targets
PUT/tool-api/targets
For an option with a targets_label, list the targets the agent may pick from, as they are now.
{
"action": "my_board",
"targets": [
{ "ref": "board-12", "name": "Tel Aviv flats" },
{ "ref": "board-31", "name": "Haifa flats", "needs": "my_ads", "why": "This board takes ads only" }
]
}refis your own id for the target (up to 200 characters, unique);nameis what the agent sees and searches (up to 200). Up to 500 targets.- The list is the whole list. A target you leave out is set aside, and comes back as it was if you list it again. So never send an empty or partial list because a page failed to load.
- Reading the list takes a while the first time? Say
preparing(section 2) until you send it: the agent sees the list loading, not empty. - A new target comes in switched off. The agent switches on the ones they use.
needs(optional) is the key of another of your options that a post must also have on for this target, withwhy(up to 120 characters) shown to the agent. EstateLens then holds that target's job until the other option's copy is out, and cancels it if it never will be.nullclears it; leaving the field out keeps what you said before.
The answer is { "listed", "added", "renamed", "gone" }.
4. Take jobs
GET/tool-api/jobs/due
Answers { "due": n } and takes nothing. Ask it often (once a minute is plenty), and only open whatever your tool works in when there is something due.
POST/tool-api/jobs/next
Takes the next job: 200 with the job, or 204 when nothing is due. Both endpoints accept ?kinds=publish,check,remove to ask for some kinds only. For example, a tool that has reached its own daily limit for posts can still take down and check.
A job you take is yours until you answer it. One left unanswered for 2 hours is closed as failed and never handed out again, so a copy is never put up twice. Take-downs come first, then copies to put up (oldest first), then checks.
Each copy has its own link
A job's post.link is that copy's own link to the listing, and post.text already contains it in place of the post's link. Use them as given. EstateLens counts the opens of each copy's link by the option it went out in, and by its target when it has one. The agent sees what your tool brought in the last 30 days in a box of its own among their posts: copies up, opens, replies (section 6) and copies not up, for your tool as a whole and for each target, best first. An option without targets (a listing on a site, say) is counted as a place of its own.
post.text can also differ from copy to copy in the order of its lines, when the agent turns that on. It is always the agent's own lines, each exactly as written, with every number and link unchanged. Post the text exactly as given.
Putting a copy up
{
"id": 4182,
"kind": "publish",
"action": "my_board",
"target": { "ref": "board-12", "name": "Tel Aviv flats" },
"post": {
"text": "4 rooms in Ramat Gan, renovated, 98 m² ...",
"photos": ["https://img.estatelens.ai/listing-photos/..."],
"link": "https://estatelens.ai/share/...",
"page_link": "https://...",
"published_at": "2026-11-02T09:14:03Z"
},
"listing": {
"id": 5120044,
"listing_type": "sale",
"property_type": "...",
"city": "...",
"neighborhood": "...",
"rooms_count": 4,
"square_meters": 98,
"price": 1860000,
"...": "..."
},
"previous": null
}targetis one of your targets, ornullfor an option without targets.postis what the agent published: itstext, itsphotos(public links), thelinkit carries,page_link(the post where the agent published it, when there is one) andpublished_at.listingis the listing as its public share page shows it:listing_type,property_type,city,neighborhood,street,rooms_count,square_meters,floor,price,description,amenitiesand more.nullwhen the listing is no longer shown.previous: when the agent repeats a post, later rounds carry the same target's copy from before,{ "state", "link", "finished_at" }, so you can renew or replace it rather than post twice. Otherwisenull.
Seeing a copy is still there, or taking it down
{
"id": 4190,
"kind": "check",
"action": "my_board",
"target": { "ref": "board-12", "name": "Tel Aviv flats" },
"copy": { "id": 88, "link": "https://myboard.example/posts/88231", "text": "4 rooms in Ramat Gan ..." },
"listing": { "id": 5120044 }
}kind is check or remove. copy is what you reported when you put it up: its link, and the text it was put up with — and its id, the one /tool-api/copies names, for telling what you see of it (section 6).
What waits, to show the agent
GET/tool-api/jobs/waiting
{
"jobs": [
{
"id": 4191,
"kind": "remove",
"action": "my_board",
"target": { "ref": "board-12", "name": "Tel Aviv flats" },
"listing": { "id": 5120044, "city": "Ramat Gan", "rooms_count": 4, "...": "..." },
"after": null,
"due_at": "2026-11-04T19:44:33Z"
}
],
"checks": 2
}Lists the jobs due now and those coming within the next 24 hours (a scheduled post's, a repeat's next round), in the order /jobs/next hands them, and takes nothing. Use it to show the agent what your tool has and when it will do each, for example while your own hours or pace hold it. Each job has its kind, action, target, due_at (when it is handed: now or later) and the listing it is of (as a job that puts a copy up carries it; just its id when the listing is no longer shown). after names the option whose copy must be out first (see needs), otherwise null. checks is how many checks are still due today. Contract 1 lists only copies to put up.
5. Answer each job
POST/tool-api/jobs/{id}
{
"state": "done",
"link": "https://myboard.example/posts/88231",
"detail": null
}| Job | state | Means | The agent sees |
|---|---|---|---|
publish | done | It is up. | Live |
publish | held | It is there, waiting for someone (an admin, a review). | Waiting |
publish | failed | It never went up. | Failed |
check | done | Still there. | Live |
check | held | Still waiting. | Waiting |
check | gone | Not there any more. | Removed |
check | failed | Could not tell. It stays as it was; checked again the next day. | No change |
remove | done | Taken down. | Removed |
remove | gone | Already was not there. | Removed |
remove | failed | Could not take it down. It stays as it was. | No change |
link: the address of the copy you made,https://only, up to 500 characters. Send it whenever you have it: checks and take-downs are handed it back, and without it your tool has to find the copy some other way.detail: optional, a few words on why (up to 300 characters), shown to the agent.- The answer is
{ "ok": true }. A state this kind of job does not take is refused.
What you see of a copy
With any answer, and most usefully when you check that a copy is still there, you may add "measures": { "reactions": 12, "comments": 3, "shares": 0, "views": 240 }. Send only the counts the place shows you, each a whole number as it stands now. EstateLens keeps each copy's latest counts and shows them on the copy in the agent's posts, beside the opens of its link.
Trying a copy again
POST/tool-api/jobs/{id}/retry
When the agent asks your tool to try again a copy that did not go up, send the id of the job that put it up and failed. The copy goes back in line, due now, and comes to you from /jobs/next as a new job. The agent can ask the same from EstateLens. A second ask, from either place, asks nothing more: the answer says the copy is already on its way, or up.
{ "asked": 1, "state": "planned" } // back in line
{ "asked": 0, "state": "working" } // already on its way, or up: nothing more asked| Status | error | Why it will not go again |
|---|---|---|
| 404 | tool_job_not_found | Not a job of yours that put a copy up. |
| 409 | tool_retry_not_failed | The last try in that place did not fail (it was taken down, or found gone). |
| 409 | tool_retry_post_gone | The agent deleted the post, or it never went out. |
| 409 | tool_retry_target_off | The agent switched that target off, or you no longer list it. |
| 409 | tool_retry_needs_option | The target needs another option, and that option's copy is neither out nor on its way. |
6. What you see of your copies
People reply to a copy where it was put up. That is often the first thing a buyer does. Your tool can tell EstateLens what it sees of its copies at any time, not only when answering a job: the counts the place shows, and who wrote. EstateLens keeps it, shows it on the copy in the agent's posts, counts it in the agent's results, and tells the agent when someone new writes.
Your copies
GET/tool-api/copies
Your copies that are up or waiting, put up in the last 30 days, newest first (at most 500), each with the link you reported for it. Use it to recognise your own copies where you look.
{ "copies": [
{ "id": 80, "action": "boards", "target": "b-1", "link": "https://…", "state": "live", "at": "2026-11-13T08:00:00Z" }
] }Tell what you saw
POST/tool-api/copies/{id}/seen
{
"measures": { "reactions": 12, "comments": 3 },
"inquiries": [
{ "ref": "c-1001", "name": "Dana", "text": "Is it still available?", "at": "2026-11-13T09:12:00Z",
"link": "https://…", "answered": false },
{ "ref": "c-1002", "parent": "c-1001", "name": "Ron", "text": "Me too", "at": "2026-11-13T09:40:00Z" }
]
}measures: optional, the same counts as on a job's answer.inquiries: optional, up to 100.refis your own id for the reply (required, unique per tool);parentis therefit answers;nameas the place shows it;text(required, kept up to 2,000 characters);link(https) to the reply itself;atwhen it was written (UTC, never ahead of now);answeredwhether the agent already answered it there.- Send a reply again whenever you see it: EstateLens keeps each
refonce and brings it up to date (its text,answered). Only new ones are counted and told to the agent. - The answer is
{ "ok": true, "new": 1 }. A copy that is not yours is404tool_copy_not_found; anything malformed is400.
Look as a person would. Most places tell their member when someone replies to them: read that once in a while and open only the copies something happened on, rather than every copy every time.
When checks come
A copy that is up is checked the day after it went up, then every week. A waiting copy is checked every day for a week. A check that could not tell is tried again the next day. Your tool is handed at most 10 checks a day.
Errors
A refusal answers { "error": "<code>" }, with field naming what was wrong when there is one.
| Status | error | What to do |
|---|---|---|
| 400 | tool_manifest_invalid | Fix the field named in field. |
| 401 | tool_key_invalid | The key opens nothing (the agent disconnected your tool, say). Pair again. |
| 403 | tool_owner_not_allowed | The agent's plan does not publish now. Stop, and try again later. |
| 403 | tool_connect_proof | Your link was answered yes, and the key needs the proof the agent came back with. Ask again with it. |
| 403 | tool_connect_declined | The agent said no on your link. Stop collecting; pair again only when the agent asks to. |
| 404 | tool_job_not_found | Not a job you hold, or already answered. |
| 429 | rate_limited | Too many requests. Wait a few minutes. |
Limits
- 600 requests per 15 minutes for each key.
- 30 codes per 15 minutes for each install (for each tool name, when no install is sent), under a ceiling shared by every tool; a service sending one install for all its agents shares those 30. Collecting the key: 300 requests per 15 minutes for each claim.
- Text is refused when it is longer than its field allows (the widths above).
A complete example
In JavaScript, for a page or an extension. installId, openForTheAgent, agentCameBack (the query your return_to page received) and doTheJob are yours to write.
const API = "https://api.estatelens.ai/tool-api";
const INSTALL = await installId(); // made once, kept for good (see Basics)
async function call(path, { method = "GET", body, key } = {}) {
const res = await fetch(API + path, {
method,
headers: {
"Content-Type": "application/json",
"X-Tool-Contract": "2",
"X-Tool-Install": INSTALL,
...(key ? { Authorization: `Bearer ${key}` } : {}),
},
body: body ? JSON.stringify(body) : undefined,
});
if (res.status === 204) return null;
const data = await res.json();
if (!res.ok) throw Object.assign(new Error(data.error), { status: res.status, data });
return { status: res.status, data };
}
// 1. Pair: open the link for the agent, wait for them to approve
const { data: asked } = await call("/connect", {
method: "POST",
body: {
name: "My Board Poster",
return_to: "https://myboard.example/connected",
actions: [{ key: "my_board", place: "listing_post", label: "Post to My Board", targets_label: "Boards" }],
},
});
openForTheAgent(asked.allow_url);
// the agent comes back to return_to: ?estatelens=approved&proof=... (or estatelens=declined)
const back = await agentCameBack();
if (back.get("estatelens") !== "approved") throw new Error("the agent said no");
const got = await call("/connect/key", { method: "POST", body: { claim: asked.claim, proof: back.get("proof") } });
const key = got.data.key; // handed once: store it
// 2. Getting ready: the agent sees your tool loading while you read your boards
await call("/me/state", { method: "PUT", key, body: { state: "preparing" } });
// 3. Say where you can post (the agent switches on the ones to use), then that you are ready
await call("/targets", { method: "PUT", key, body: {
action: "my_board",
targets: [{ ref: "board-12", name: "Tel Aviv flats" }, { ref: "board-31", name: "Haifa flats" }],
}});
await call("/me/state", { method: "PUT", key, body: { state: "ok" } });
// 4. Once a minute: take what is due, do it, answer it
setInterval(async () => {
const { data } = await call("/jobs/due", { key });
if (!data.due) return;
const got = await call("/jobs/next", { method: "POST", key });
if (!got) return;
const job = got.data;
let answer;
try {
answer = await doTheJob(job); // { state: "done" | "held" | "gone", link }
} catch (e) {
answer = { state: "failed", detail: String(e.message).slice(0, 300) };
}
await call(`/jobs/${job.id}`, { method: "POST", key, body: answer });
}, 60_000);Your tool, your responsibility
A tool acts for the agent who connected it. Its maker is responsible for what it does, and for following the terms of every service it works with. EstateLens hands a tool only the posts its agent marks for it, and the agent can disconnect it at any time.
Questions: support@estatelens.ai