API for your project website
Show your projects, blocks and units with live status and prices on your own website or mobile app, and send website enquiries straight into the BuildOS sales pipeline.
OpenAPI 3.1 specification: /api/v1/openapi.json
Authentication
Create a key in Company Settings › API (owners and admins). Send it as Authorization: Bearer YOUR_KEY or X-API-Key. The key decides the company; it can only read that company's published projects.
Using the key in browser JavaScript? Add your site's origin (https://…) to the key and give it only the permissions the page needs (for a lead form: leads:write). Keys without origins work only server-to-server.
curl https://buildos.ge/api/v1/projects \
-H "Authorization: Bearer bos_your_key"Endpoints
| GET | /api/v1/projects | projects:read | Published projects: description, location, photos, progress %, unit counts |
| GET | /api/v1/projects/{id} | projects:read | One published project |
| GET | /api/v1/projects/{id}/blocks | units:read | Blocks and floors with available / reserved / sold counts |
| GET | /api/v1/projects/{id}/units | units:read | Visible units: type, rooms, m², floor, view, facade, status, price, floor plan. Filters: status, block, floor |
| GET | /api/v1/units/{id} | units:read | One visible unit |
| GET | /api/v1/projects/{id}/milestones | projects:read | Public construction milestones (if enabled for the project) |
| GET | /api/v1/projects/{id}/massing | massing:read | Automatic 3D massing: blocks, floors, unit slots (box geometry), status, price for available units + floor plans with unit polygons |
| POST | /api/v1/leads | leads:write | Send an enquiry from your website form |
Data API (integrations)
Read-only access to all of your company's BuildOS data for accounting, ERP, BI and your own apps: one scope per module (data:<module>:read). Endpoints: GET /api/v1/data (resources your key can read), GET /api/v1/data/{resource} (list; limit, offset, updated_since and equality filters), GET /api/v1/data/{resource}/{id}.
Only your company's and your own projects' records are returned. Personal data fields (names, phones, e-mails, IDs, IBANs, location) are added only with data:personal:read; passwords, tokens and file paths are never returned. Write access (create / update) will be added module by module in later releases.
Resources (127)
| data:projects:read | projects, project_zones, project_milestones, project_partners, block_locations, massing_blocks |
| data:sales:read | units, unit_payments, unit_price_history, unit_changes, unit_requests, unit_leases, customers, sales_leads, sales_lead_activities, sales_quotes, sales_campaigns, sales_price_premiums, sales_targets, sales_discount_requests, project_sales_settings |
| data:contracts:read | project_contracts, contract_items, change_orders, change_order_items, progress_payments, progress_payment_items, subcontractor_compliance_documents, budget_lines |
| data:takeoff:read | takeoff_entries, takeoff_recipes, takeoff_recipe_materials, unit_work_items, work_item_catalog |
| data:procurement:read | materials, catalog_items, suppliers, material_requests, material_quotes, goods_receipts, warehouses, warehouse_projects, site_inventory, stock_movements, stock_aliases, internal_transfers, stock_counts, stock_count_lines, writeoff_acts, petty_cash_entries, petty_cash_closings, rs_waybill_imports, rs_returns |
| data:hr:read | workers, worker_teams, worker_attendance, worker_checkins, worker_leaves, worker_payroll_items, worker_documents, worker_assets, worker_profiles |
| data:site:read | work_log_entries, site_daily_logs, daily_report_settings, punch_list_items, inspections, inspection_results, inspection_templates, equipment, equipment_fuel_logs, equipment_checklists, concealed_acts, concealed_act_items, concrete_pours, concrete_tests |
| data:schedule:read | schedule_activities, tasks, risks, meetings, meeting_actions, rfis, submittals, site_instructions, announcements |
| data:documents:read | project_documents, project_drawings, drawing_pins, attachments, floor_plans, floor_plan_units |
| data:hse:read | hse_incidents, hse_documents, hse_custom_rules |
| data:warranty:read | handover_slots, handover_bookings, handover_protocols, handover_templates, warranty_terms, warranty_sla, warranty_tickets, warranty_ticket_events, satisfaction_surveys |
| data:tenders:read | tenders, tender_items, tender_bids, tender_bid_items |
| data:estate:read | estates, estate_units, estate_contacts, estate_budgets, estate_budget_lines, estate_charges, estate_payments, estate_expenses, estate_cash_entries, estate_reports, estate_equipment, estate_work_orders, estate_announcements, estate_votes, estate_resources, estate_bookings |
| data:settings:read | companies, company_modules, approval_policies, role_templates |
Mobile app API (user login)
For the general BuildOS mobile app: users log in with their own BuildOS account, no API key needed. Every request uses the user's session token and returns only the records that user sees in the web app (own company, own projects, own trade for subcontractors, module permissions).
Flow: POST /api/app/v1/auth/login {email, password} → access_token + refresh_token; send Authorization: Bearer <access_token>; when it expires, POST /api/app/v1/auth/refresh {refresh_token}. GET /api/app/v1/me returns the user and companies, GET /api/app/v1/data/{resource} returns every Data API resource; units is the sales view (developer), site_units is the basic unit info everyone can see.
Creating and editing records: every action the web screens perform runs through POST /api/app/v1/actions/{name} with the same rules (validation, permissions, approvals, notifications, stock effects); body {"args": [...]} in the web parameter order. The list is regenerated from source on every release; only actions the web app already uses are available. Photos and files: POST /api/app/v1/uploads (bucket, path, file), then link them with the matching action. Error message language: X-BuildOS-Locale header (ka, tr, en, ru).
OpenAPI document: /api/app/v1/openapi.json
What the API returns
- Only projects switched to "Publish on website" and units marked visible.
- Prices only for available units; reserved and sold units have price: null.
- Never any buyer or lead personal data (names, phones, e-mails, payments).
- Photos and floor plans are signed links valid for 1 hour; fetch again to refresh.
Lists, paging and caching
Lists return data + pagination. Use limit (max 100) and offset; next_offset is null on the last page. updated_since returns only records changed since a time, for cheap syncing. Responses carry an ETag; send If-None-Match to get 304 when nothing changed. Rate limit: 600 requests/min per key, 120/min per IP.
curl "https://buildos.ge/api/v1/projects/PROJECT_ID/units?status=available&limit=50" \
-H "Authorization: Bearer bos_your_key"
# incremental sync: only units changed since your last fetch
curl "https://buildos.ge/api/v1/projects/PROJECT_ID/units?updated_since=2026-10-01T00:00:00Z" \
-H "Authorization: Bearer bos_your_key"const res = await fetch(
"https://buildos.ge/api/v1/projects/PROJECT_ID/units?status=available",
{ headers: { Authorization: "Bearer " + process.env.BUILDOS_KEY } },
);
const { data, pagination } = await res.json();
for (const unit of data) {
console.log(unit.number, unit.rooms, unit.area_m2, unit.price, unit.currency);
}Sending leads
POST /leads creates a lead with source "website" and notifies your sales team. Phone or e-mail is required. Repeated enquiries from the same phone/e-mail on the same project are added to the existing lead. Spam protection: 5 requests per 10 minutes per IP, a hidden honeypot field (website) and optional Cloudflare Turnstile (turnstile_token).
// Browser form: create a key with your site's origin (https://myproject.ge)
// and only the leads:write permission.
await fetch("https://buildos.ge/api/v1/leads", {
method: "POST",
headers: {
"Content-Type": "application/json",
"X-API-Key": "bos_your_form_key",
},
body: JSON.stringify({
project_id: "PROJECT_ID",
unit_id: "UNIT_ID", // optional
name: "Nino Beridze",
phone: "+995 555 12 34 56", // phone or email
email: "[email protected]",
message: "Is a 3-room flat still available?",
source: "landing-autumn",
website: "", // honeypot: keep this input hidden and empty
}),
});3D massing and floor plans
GET /projects/{id}/massing returns everything needed to draw your own 3D scene: block position/rotation/footprint, floor height, commercial ground floor and parking levels, each unit's box in block-local metres, and floor plan images (signed link, 1 hour) with unit polygons in 0..1 coordinates. Scope: massing:read. Only visible units; no personal data.
curl https://buildos.ge/api/v1/projects/PROJECT_ID/massing \
-H "Authorization: Bearer bos_your_key"{
"data": {
"project_id": "…",
"blocks": [{
"block": "A", "floor_height_m": 3, "ground_commercial": false,
"parking_levels": 1, "position": { "x_m": 0, "z_m": 0 }, "rotation_deg": 0,
"footprint": { "width_m": 21, "depth_m": 16 }, "height_m": 27,
"floors": [{ "floor": 1, "units": [{
"id": "…", "number": "A-101", "slot": 0, "type": "apartment",
"rooms": 2, "area_m2": 64.5, "status": "available",
"price": 72000, "currency": "USD", "floor_plan_url": "https://…",
"box": { "x": -7, "y": 1.5, "z": 4, "w": 6.8, "h": 2.75, "d": 7.8 }
}] }]
}],
"floor_plans": [{
"id": "…", "block": "A", "floor": 1, "image_url": "https://…", "aspect": 1.42,
"polygons": [{ "unit_id": "…", "points": [[0.1, 0.2], [0.4, 0.2], [0.4, 0.6], [0.1, 0.6]] }]
}]
}
}Website widget (one line)
To add the 3D building + floor plan picker + enquiry form to your site: create a key in Company Settings › API with massing:read and leads:write and your site's origin (https://…); switch the project to "Publish on website" and draw floor plans in Building & Units. Then paste the line below into your page. Only the key's origins can frame the widget. Options: data-lang (ka, en, ru, tr), data-color (#rrggbb primary colour), data-height (initial height), data-target (CSS selector to place the iframe in). Prefer no script? Use the iframe directly.
<!-- BuildOS: 3D + floor plan picker + enquiry form -->
<script src="https://buildos.ge/widget.js"
data-project="PROJECT_ID"
data-key="bos_your_browser_key"
data-lang="ka"
data-color="#0f766e"
async></script><iframe
src="https://buildos.ge/embed/PROJECT_ID?key=bos_your_browser_key&lang=en&color=%230f766e"
style="width:100%;height:720px;border:0" loading="lazy" allow="fullscreen"></iframe>Webhooks
Register an https URL in Company Settings › API to receive unit.status_changed, unit.price_changed and lead.created. Each request carries BuildOS-Signature: t=UNIX_TIME,v1=HMAC_SHA256(secret, "t.body"). Reply with 2xx; failed deliveries are retried (1 min, 5 min, 30 min, 2 h, 6 h) and can be resent from the delivery log. Payloads contain no personal data.
{
"id": "6f1c…",
"event": "unit.status_changed",
"created_at": "2026-10-06T10:15:00Z",
"data": {
"unit_id": "…", "project_id": "…", "unit_number": "A-12",
"old_status": "available", "status": "reserved"
}
}import crypto from "node:crypto";
// Express / Next.js route: read the RAW body before parsing JSON.
function verify(rawBody, header, secret) {
const parts = Object.fromEntries(header.split(",").map((p) => p.split("=")));
const age = Math.abs(Date.now() / 1000 - Number(parts.t));
if (age > 300) return false;
const expected = crypto
.createHmac("sha256", secret)
.update(parts.t + "." + rawBody)
.digest("hex");
return crypto.timingSafeEqual(Buffer.from(expected), Buffer.from(parts.v1));
}
// verify(raw, req.headers["buildos-signature"], process.env.BUILDOS_WEBHOOK_SECRET)Errors
Errors use HTTP status codes and a JSON body. Codes: unauthorized (401), forbidden / origin_not_allowed / insufficient_scope (403), not_found (404), invalid_request (400), rate_limited (429, see Retry-After), server_error (500).
{ "error": { "code": "insufficient_scope", "message": "Scope units:read required" } }