{ "openapi": "3.1.0", "info": { "title": "GalaxyIDX API", "version": "0.1.0", "summary": "MLS/IDX listings, market stats and lead capture for real-estate websites, multi-tenant.", "description": "Server-rendered MLS listings and lead capture for any real-estate site. Docs for AI agents: https://docs.galaxyidx.com/llms.txt. Every request is limited to the tenant that owns the key. Errors are always `{\"error\":{\"code\":\"…\",\"message\":\"…\"}}`.", "contact": { "email": "support@galaxyidx.com" }, "x-contract-version": "0.1" }, "servers": [ { "url": "https://api.galaxyidx.com/v1" } ], "tags": [ { "name": "Listings" }, { "name": "Leads" }, { "name": "Sites" }, { "name": "Account" }, { "name": "MLS licensing" }, { "name": "Billing" } ], "paths": { "/listings": { "get": { "operationId": "listListings", "summary": "Search the site's listings", "tags": [ "Listings" ], "security": [ { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingPage" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Objective filters only (no 'safe', 'family-friendly' or demographic filters). Default sort is organic. A `scope=office` site only returns listings from the license's office_ids.", "parameters": [ { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The site the request is for. It must belong to the key's tenant (and equal the key's site when the key is site-scoped)." }, { "name": "status", "in": "query", "required": false, "schema": { "type": "string" }, "description": "e.g. `active`, `pending`, `sold`." }, { "name": "min_price", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Minimum list price." }, { "name": "max_price", "in": "query", "required": false, "schema": { "type": "number", "minimum": 0 }, "description": "Maximum list price." }, { "name": "beds", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 0 }, "description": "Minimum bedrooms." }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 24 }, "description": "Page size." }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" }, "description": "`next_cursor` from the previous page." } ] } }, "/listings/{listing_key}": { "get": { "operationId": "getListing", "summary": "Get one listing", "tags": [ "Listings" ], "security": [ { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListingDetail" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "listing_key", "in": "path", "required": true, "schema": { "type": "string" }, "description": "MLS listing key." }, { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The site the request is for. It must belong to the key's tenant (and equal the key's site when the key is site-scoped)." } ] } }, "/areas/{slug}/stats": { "get": { "operationId": "getAreaStats", "summary": "Market statistics for an area", "tags": [ "Listings" ], "security": [ { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AreaStats" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "slug", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Area slug, e.g. a city or subdivision slug." }, { "name": "site_id", "in": "query", "required": true, "schema": { "type": "string" }, "description": "The site the request is for. It must belong to the key's tenant (and equal the key's site when the key is site-scoped)." } ] } }, "/sites/{site_id}/snapshot": { "get": { "operationId": "getSiteSnapshot", "summary": "Full render snapshot for one site", "tags": [ "Listings" ], "security": [ { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Snapshot" } } }, "headers": { "ETag": { "schema": { "type": "string" } } } }, "304": { "description": "Not modified (matches If-None-Match)." }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id." }, { "name": "If-None-Match", "in": "header", "required": false, "schema": { "type": "string" } } ] } }, "/signup": { "post": { "operationId": "signup", "summary": "Start a trial tenant", "tags": [ "Account" ], "security": [], "responses": { "202": { "description": "Magic link sent", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Creates the tenant as `trial` and emails a sign-in magic link (15-minute, single use).", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SignupRequest" } } } } } }, "/auth/magic-link": { "post": { "operationId": "requestMagicLink", "summary": "Email a sign-in link", "tags": [ "Account" ], "security": [], "responses": { "202": { "description": "Magic link sent (also returned for unknown emails)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Accepted" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MagicLinkRequest" } } } } } }, "/auth/callback": { "get": { "operationId": "magicLinkCallback", "summary": "Consume a magic link", "tags": [ "Account" ], "security": [], "responses": { "302": { "description": "Sets the 30-day console session cookie and redirects to the dashboard.", "headers": { "Set-Cookie": { "schema": { "type": "string" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" } }, "parameters": [ { "name": "token", "in": "query", "required": true, "schema": { "type": "string" }, "description": "Single-use token from the email." } ] } }, "/tenant": { "get": { "operationId": "getTenant", "summary": "Get the caller's tenant", "tags": [ "Account" ], "security": [ { "consoleSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "With a secret key (tenant-wide or site-scoped) the billing fields (`billing_ref`) are omitted; they are for the console session only.", "x-key-scope": "Site-scoped key: allowed; billing fields omitted." }, "patch": { "operationId": "updateTenant", "summary": "Update the caller's tenant", "tags": [ "Account" ], "security": [ { "consoleSession": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Tenant" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TenantPatch" } } } } } }, "/sites": { "get": { "operationId": "listSites", "summary": "List the tenant's sites", "tags": [ "Sites" ], "security": [ { "consoleSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Site" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A site-scoped secret key sees only its own site.", "x-key-scope": "Site-scoped key: only its own site." }, "post": { "operationId": "createSite", "summary": "Add a site", "tags": [ "Sites" ], "security": [ { "consoleSession": [] } ], "responses": { "201": { "description": "Created (status `pending`)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SiteCreate" } } } } } }, "/sites/{site_id}": { "patch": { "operationId": "updateSite", "summary": "Update a site", "tags": [ "Sites" ], "security": [ { "consoleSession": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Site" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "409": { "$ref": "#/components/responses/Conflict" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SitePatch" } } } }, "x-interpretation": "Contract lists `PATCH /sites`; the site is addressed by id in the path." } }, "/sites/{site_id}/keys": { "post": { "operationId": "createKey", "summary": "Create an API key for a site", "tags": [ "Sites" ], "security": [ { "consoleSession": [] } ], "responses": { "201": { "description": "Created; the full key is in `key` and is shown only once", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreated" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "site_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Site id." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyCreate" } } } } } }, "/keys/{key_id}": { "delete": { "operationId": "revokeKey", "summary": "Revoke an API key", "tags": [ "Sites" ], "security": [ { "consoleSession": [] } ], "responses": { "204": { "description": "Revoked. Later calls with it fail 401 `key_revoked`." }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "parameters": [ { "name": "key_id", "in": "path", "required": true, "schema": { "type": "string" }, "description": "Key id." } ] } }, "/mls-licenses": { "get": { "operationId": "listMlsLicenses", "summary": "List MLS licenses", "tags": [ "MLS licensing" ], "security": [ { "consoleSession": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MlsLicense" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } } }, "post": { "operationId": "createMlsLicense", "summary": "Upload a broker's MLS authorization", "tags": [ "MLS licensing" ], "security": [ { "consoleSession": [] } ], "responses": { "201": { "description": "Created with status `pending_broker` or `submitted`", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MlsLicense" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Only an operator moves a license to `approved`; no API call can.", "requestBody": { "required": true, "content": { "multipart/form-data": { "schema": { "$ref": "#/components/schemas/MlsLicenseCreate" } } } } } }, "/billing/checkout": { "post": { "operationId": "createCheckout", "summary": "Start checkout", "tags": [ "Billing" ], "security": [ { "consoleSession": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckoutResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Two line items: software $10/month per site, and the MLS fee passed through at cost (may be $0)." } }, "/billing/webhook": { "post": { "operationId": "billingWebhook", "summary": "Billing provider webhook", "tags": [ "Billing" ], "security": [], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "received": { "type": "boolean" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "parameters": [ { "name": "Stripe-Signature", "in": "header", "required": true, "schema": { "type": "string" }, "description": "Verified before anything is processed." } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object" } } } } } }, "/leads": { "post": { "operationId": "createLead", "summary": "Capture a lead", "tags": [ "Leads" ], "security": [ { "publishableKey": [] }, { "secretKey": [] } ], "responses": { "201": { "description": "Stored; delivery runs asynchronously with retry", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCreated" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Publishable key: the browser `Origin` host must be one of the site's `domains`. Secret key: call from your server only (forward the visitor IP in `X-Forwarded-For`). Rate-limited per key and IP.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadCreate" } } } } }, "get": { "operationId": "listLeads", "summary": "List leads", "tags": [ "Leads" ], "security": [ { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadList" } } } }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "A site-scoped key sees only its own site's leads; naming another site returns 404.", "parameters": [ { "name": "site_id", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Only this site's leads." }, { "name": "since", "in": "query", "required": false, "schema": { "type": "string", "format": "date-time" }, "description": "Only leads created at or after this time." } ], "x-key-scope": "Site-scoped key: only its own site's leads; another site_id -> 404." } }, "/lead-routes": { "get": { "operationId": "listLeadRoutes", "summary": "Get lead routing", "tags": [ "Leads" ], "security": [ { "consoleSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadRouteList" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "The tenant default route (site_id null) and any per-site overrides. A site-scoped key gets only the default (read-only for it) and its own site's route.", "x-key-scope": "Site-scoped key: the default route and its own site's route only." }, "put": { "operationId": "putLeadRoute", "summary": "Set lead routing", "tags": [ "Leads" ], "security": [ { "consoleSession": [] }, { "secretKey": [] } ], "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadRoute" } } } }, "403": { "$ref": "#/components/responses/SiteForbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } }, "description": "Replaces the whole route for (tenant, site_id). A site with no route of its own uses the default, so a new site override must carry the default's `lofty` and `webhook` or those channels stop for that site.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeadRoutePut" } } } }, "x-key-scope": "Site-scoped key: only its own site's route; site_id null or another site -> 403 `site_forbidden`. Tenant-wide key or console session: any route." } } }, "components": { "securitySchemes": { "secretKey": { "type": "http", "scheme": "bearer", "bearerFormat": "sk_live_… / sk_test_…", "description": "Server-side only (WordPress PHP, SSR, MCP). Never ship it to a browser or commit it. Scoped to one tenant, optionally one site. A site-scoped key reads only its own site and its leads, writes only its own site's lead route (never the tenant default) and never sees billing fields; see `x-key-scope` on each operation." }, "publishableKey": { "type": "http", "scheme": "bearer", "bearerFormat": "pk_live_… / pk_test_…", "description": "Browser-safe. Only `POST /leads`, only from an Origin in the site's `domains`." }, "consoleSession": { "type": "apiKey", "in": "cookie", "name": "session", "description": "Dashboard session from a magic link (30 days)." } }, "schemas": { "Error": { "type": "object", "required": [ "error" ], "additionalProperties": false, "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine code, e.g. `key_revoked`.", "examples": [ "key_revoked", "unauthorized", "forbidden", "not_found", "invalid_request", "origin_not_allowed", "area_idx_disabled", "rate_limited", "site_forbidden", "key_scope_insufficient" ] }, "message": { "type": "string", "description": "Human-readable explanation." } } } }, "description": "Every error, on every endpoint, has exactly this shape." }, "Tenant": { "type": "object", "required": [ "id", "slug", "name", "plan", "status", "created_at" ], "properties": { "id": { "type": "string" }, "slug": { "type": "string" }, "name": { "type": "string" }, "plan": { "type": "string", "enum": [ "internal_free", "standard" ] }, "status": { "type": "string", "enum": [ "trial", "active", "past_due", "suspended" ] }, "billing_ref": { "type": [ "string", "null" ], "readOnly": true, "description": "Billing-provider customer reference (not a secret). Console session only: never returned to a secret key." }, "created_at": { "type": "string", "format": "date-time" } } }, "TenantPatch": { "type": "object", "additionalProperties": false, "properties": { "name": { "type": "string", "minLength": 1 } } }, "Geo": { "type": "object", "properties": { "cities": { "type": "array", "items": { "type": "string" } }, "counties": { "type": "array", "items": { "type": "string" } }, "subdivisions": { "type": "array", "items": { "type": "string" } }, "zips": { "type": "array", "items": { "type": "string" } } } }, "Site": { "type": "object", "required": [ "id", "tenant_id", "domain_primary", "domains", "scope", "status", "created_at" ], "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "domain_primary": { "type": "string", "description": "Host name, e.g. `www.example.com`." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Every host the site answers on. Publishable keys only work from these Origins." }, "scope": { "type": "string", "enum": [ "office", "area" ], "description": "`office` = only the tenant's own office listings. `area` = all brokers in the geo; refused unless the MLS approved the domain and the operator flag is on." }, "geo": { "$ref": "#/components/schemas/Geo" }, "home_priority": { "type": "integer", "description": "Higher wins when two of the tenant's sites match a listing." }, "status": { "type": "string", "enum": [ "pending", "live", "paused" ] }, "created_at": { "type": "string", "format": "date-time" } } }, "SiteCreate": { "type": "object", "required": [ "domain_primary" ], "additionalProperties": false, "properties": { "domain_primary": { "type": "string", "description": "Host name, e.g. `www.example.com`." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Every host the site answers on. Publishable keys only work from these Origins." }, "scope": { "type": "string", "enum": [ "office", "area" ], "description": "`office` = only the tenant's own office listings. `area` = all brokers in the geo; refused unless the MLS approved the domain and the operator flag is on." }, "geo": { "$ref": "#/components/schemas/Geo" }, "home_priority": { "type": "integer", "description": "Higher wins when two of the tenant's sites match a listing." } } }, "SitePatch": { "type": "object", "additionalProperties": false, "properties": { "domain_primary": { "type": "string", "description": "Host name, e.g. `www.example.com`." }, "domains": { "type": "array", "items": { "type": "string" }, "description": "Every host the site answers on. Publishable keys only work from these Origins." }, "scope": { "type": "string", "enum": [ "office", "area" ], "description": "`office` = only the tenant's own office listings. `area` = all brokers in the geo; refused unless the MLS approved the domain and the operator flag is on." }, "geo": { "$ref": "#/components/schemas/Geo" }, "home_priority": { "type": "integer", "description": "Higher wins when two of the tenant's sites match a listing." }, "status": { "type": "string", "enum": [ "live", "paused" ], "description": "`live` is accepted only when the go-live rule holds (tenant active or internal_free AND an approved license covers the site)." } } }, "MlsLicense": { "type": "object", "required": [ "id", "tenant_id", "mls", "kind", "office_ids", "status", "approved_domains", "created_at" ], "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "mls": { "type": "string", "examples": [ "GAMLS", "FMLS" ] }, "kind": { "type": "string", "enum": [ "idx", "backoffice" ] }, "office_ids": { "type": "array", "items": { "type": "string" } }, "status": { "type": "string", "enum": [ "pending_broker", "submitted", "approved", "revoked" ], "description": "Moves pending_broker -> submitted -> approved only by an operator action." }, "approved_domains": { "type": "array", "items": { "type": "string" } }, "evidence_ref": { "type": [ "string", "null" ], "description": "Reference to the stored broker authorization document." }, "created_at": { "type": "string", "format": "date-time" } } }, "MlsLicenseCreate": { "type": "object", "required": [ "mls", "kind", "office_ids", "authorization" ], "properties": { "mls": { "type": "string" }, "kind": { "type": "string", "enum": [ "idx", "backoffice" ] }, "office_ids": { "type": "array", "items": { "type": "string" } }, "authorization": { "type": "string", "contentMediaType": "application/octet-stream", "description": "The MLS authorization form signed by the customer's BROKER (PDF)." } } }, "ApiKey": { "type": "object", "required": [ "id", "tenant_id", "kind", "prefix", "created_at" ], "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ], "description": "Set when the key is limited to one site." }, "kind": { "type": "string", "enum": [ "publishable", "secret" ] }, "prefix": { "type": "string", "description": "First 8 characters, for recognising a key. The full key is stored only as a SHA-256 hash." }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "ApiKeyCreated": { "type": "object", "required": [ "id", "kind", "prefix", "key" ], "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ], "description": "Set when the key is limited to one site." }, "kind": { "type": "string", "enum": [ "publishable", "secret" ] }, "prefix": { "type": "string", "description": "First 8 characters, for recognising a key. The full key is stored only as a SHA-256 hash." }, "created_at": { "type": "string", "format": "date-time" }, "revoked_at": { "type": [ "string", "null" ], "format": "date-time" }, "key": { "type": "string", "description": "The full key. Returned ONCE, at creation; it cannot be read again. Store it in an environment variable / secret store, never in source control." } }, "x-interpretation": "Contract stores only hash+prefix, so the plaintext must be returned once at creation." }, "ApiKeyCreate": { "type": "object", "required": [ "kind" ], "additionalProperties": false, "properties": { "kind": { "type": "string", "enum": [ "publishable", "secret" ] } } }, "Delivery": { "type": "object", "properties": { "channel": { "type": "string", "enum": [ "email", "lofty", "webhook" ] }, "status": { "type": "string", "examples": [ "pending", "sent", "failed" ] }, "attempts": { "type": "integer" }, "last_error": { "type": [ "string", "null" ] }, "at": { "type": [ "string", "null" ], "format": "date-time" } } }, "LeadCreate": { "type": "object", "required": [ "site_id", "action", "name", "email", "page_url" ], "properties": { "site_id": { "type": "string" }, "listing_key": { "type": [ "string", "null" ] }, "action": { "type": "string", "enum": [ "tour", "ask", "save", "price_alert", "register", "contact" ] }, "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "tour": { "type": [ "object", "null" ], "properties": { "date": { "type": "string", "format": "date" }, "part_of_day": { "type": "string", "enum": [ "morning", "afternoon", "evening" ] } }, "description": "A requested window, never a promised time; the agent confirms." }, "page_url": { "type": "string", "format": "uri" }, "referrer": { "type": [ "string", "null" ] }, "utm": { "type": "object", "additionalProperties": { "type": "string" } }, "consent": { "type": "object", "properties": { "email_marketing": { "type": "boolean", "default": false, "description": "Opt-in only; defaults to false." }, "sms": { "type": "boolean", "const": false, "description": "Always false: SMS is not offered. Any other value is rejected." } } }, "honeypot": { "type": "string", "maxLength": 0, "description": "Hidden form field. Must be empty or absent; a filled value is silently dropped as spam." } }, "x-interpretation": "Honeypot field name `honeypot`; site_id is in the body for both key kinds." }, "LeadCreated": { "type": "object", "required": [ "id" ], "properties": { "id": { "type": "string" } } }, "Lead": { "type": "object", "required": [ "id", "tenant_id", "site_id", "action", "name", "email", "created_at" ], "properties": { "id": { "type": "string" }, "tenant_id": { "type": "string" }, "site_id": { "type": "string" }, "listing_key": { "type": [ "string", "null" ] }, "action": { "type": "string", "enum": [ "tour", "ask", "save", "price_alert", "register", "contact" ] }, "name": { "type": "string", "minLength": 1 }, "email": { "type": "string", "format": "email" }, "phone": { "type": [ "string", "null" ] }, "message": { "type": [ "string", "null" ] }, "tour": { "type": [ "object", "null" ], "properties": { "date": { "type": "string", "format": "date" }, "part_of_day": { "type": "string", "enum": [ "morning", "afternoon", "evening" ] } }, "description": "A requested window, never a promised time; the agent confirms." }, "page_url": { "type": "string", "format": "uri" }, "referrer": { "type": [ "string", "null" ] }, "utm": { "type": "object", "additionalProperties": { "type": "string" } }, "consent": { "type": "object", "properties": { "email_marketing": { "type": "boolean" }, "sms": { "type": "boolean", "const": false } } }, "created_at": { "type": "string", "format": "date-time" }, "deliveries": { "type": "array", "items": { "$ref": "#/components/schemas/Delivery" } } } }, "LeadList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Lead" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "LeadRoute": { "type": "object", "required": [ "tenant_id", "site_id", "email_to" ], "properties": { "tenant_id": { "type": "string" }, "site_id": { "type": [ "string", "null" ], "description": "null = the tenant default route; a site route overrides it." }, "email_to": { "type": "array", "items": { "type": "string", "format": "email" } }, "email_cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "lofty": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "cred_ref": { "type": [ "string", "null" ], "description": "NAME of the secret holding the CRM credential, never the credential." } } }, "webhook": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri" }, "secret_ref": { "type": [ "string", "null" ], "description": "NAME of the HMAC secret, never the secret." } } } } }, "LeadRoutePut": { "type": "object", "required": [ "site_id", "email_to" ], "additionalProperties": false, "properties": { "site_id": { "type": [ "string", "null" ], "description": "null = the tenant default route; a site route overrides it." }, "email_to": { "type": "array", "items": { "type": "string", "format": "email" } }, "email_cc": { "type": "array", "items": { "type": "string", "format": "email" } }, "lofty": { "type": [ "object", "null" ], "properties": { "enabled": { "type": "boolean" }, "cred_ref": { "type": [ "string", "null" ], "description": "NAME of the secret holding the CRM credential, never the credential." } } }, "webhook": { "type": [ "object", "null" ], "properties": { "url": { "type": "string", "format": "uri" }, "secret_ref": { "type": [ "string", "null" ], "description": "NAME of the HMAC secret, never the secret." } } } }, "x-interpretation": "PUT upserts the one route identified by (tenant, site_id)." }, "LeadRouteList": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeadRoute" } } } }, "Address": { "type": "object", "properties": { "street": { "type": [ "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "county": { "type": [ "string", "null" ] }, "subdivision": { "type": [ "string", "null" ] }, "display": { "type": "boolean", "description": "false = the seller opted out of showing the address. Street/unit are then null and must not be shown." } }, "x-interpretation": "Address sub-fields are not enumerated in the contract (`address{…, display}`)." }, "Photo": { "type": "object", "required": [ "url", "order" ], "properties": { "url": { "type": "string", "format": "uri" }, "w": { "type": [ "integer", "null" ] }, "h": { "type": [ "integer", "null" ] }, "order": { "type": "integer" } }, "description": "Display resized only: no crop, no overlay, no text on the photo." }, "Compliance": { "type": "object", "required": [ "listing_firm", "disclaimer", "last_updated" ], "properties": { "listing_firm": { "type": "string" }, "listing_firm_phone": { "type": [ "string", "null" ] }, "listing_firm_email": { "type": [ "string", "null" ] }, "mls_logo_url": { "type": [ "string", "null" ], "format": "uri" }, "disclaimer": { "type": "string" }, "last_updated": { "type": "string", "format": "date-time" } }, "description": "Must be shown with every listing display (card or page)." }, "Listing": { "type": "object", "required": [ "listing_key", "mls", "status", "compliance", "updated_at" ], "properties": { "listing_key": { "type": "string" }, "mls": { "type": "string" }, "office_id": { "type": [ "string", "null" ] }, "status": { "type": "string", "examples": [ "active", "pending", "sold" ] }, "property_type": { "type": [ "string", "null" ], "description": "As the MLS reports it; null when absent.", "x-interpretation": "Not in contract v0.1; optional, used only to pick the schema.org type." }, "price": { "type": [ "number", "null" ] }, "beds": { "type": [ "integer", "null" ] }, "baths": { "type": [ "number", "null" ] }, "sqft": { "type": [ "integer", "null" ] }, "acres": { "type": [ "number", "null" ] }, "year_built": { "type": [ "integer", "null" ] }, "address": { "$ref": "#/components/schemas/Address" }, "geo": { "type": [ "object", "null" ], "properties": { "lat": { "type": "number" }, "lng": { "type": "number" } } }, "remarks_public": { "type": [ "string", "null" ] }, "photos": { "type": "array", "items": { "$ref": "#/components/schemas/Photo" } }, "history": { "type": "array", "items": { "type": "object", "description": "Dated MLS events only (no estimated series)." } }, "open_houses": { "type": "array", "items": { "type": "object" } }, "compliance": { "$ref": "#/components/schemas/Compliance" }, "home_site_id": { "type": [ "string", "null" ] }, "updated_at": { "type": "string", "format": "date-time" } }, "description": "Engine-owned. Every fact comes from the MLS feed; a missing fact is null (render it as an em dash). Fields the MLS forbids (compensation, showing instructions, private remarks, contract/expiration dates) are never present." }, "HomeSite": { "type": "object", "required": [ "domain", "path" ], "properties": { "site_id": { "type": "string" }, "domain": { "type": "string" }, "path": { "type": "string" }, "url": { "type": "string", "format": "uri" } } }, "ListingDetail": { "allOf": [ { "$ref": "#/components/schemas/Listing" }, { "type": "object", "required": [ "home_site", "is_home" ], "properties": { "home_site": { "$ref": "#/components/schemas/HomeSite" }, "is_home": { "type": "boolean", "description": "true when the requesting site is the listing's one indexed home. When false, link to `home_site` instead of rendering an indexable page." } } } ] }, "ListingPage": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Listing" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "Metric": { "type": "object", "required": [ "key", "value", "period_from", "period_to", "source" ], "properties": { "key": { "type": "string" }, "label": { "type": "string" }, "value": { "type": [ "number", "string", "null" ] }, "unit": { "type": [ "string", "null" ] }, "period_from": { "type": "string", "format": "date" }, "period_to": { "type": "string", "format": "date" }, "source": { "type": "string", "description": "Cite this next to the number." } } }, "AreaStats": { "type": "object", "required": [ "area", "metrics" ], "properties": { "area": { "type": "object", "properties": { "slug": { "type": "string" }, "name": { "type": "string" } } }, "site_id": { "type": "string" }, "metrics": { "type": "array", "items": { "$ref": "#/components/schemas/Metric" } } } }, "Snapshot": { "type": "object", "required": [ "site", "listings", "generated_at" ], "additionalProperties": true, "properties": { "site": { "$ref": "#/components/schemas/Site" }, "listings": { "type": "array", "items": { "$ref": "#/components/schemas/ListingDetail" } }, "generated_at": { "type": "string", "format": "date-time" } }, "description": "Everything a renderer needs for one site. The engine may add fields." }, "SignupRequest": { "type": "object", "required": [ "email", "tenant_name", "site_domain" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" }, "tenant_name": { "type": "string" }, "site_domain": { "type": "string" } } }, "MagicLinkRequest": { "type": "object", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "format": "email" } } }, "Accepted": { "type": "object", "properties": { "status": { "type": "string", "examples": [ "magic_link_sent" ] } } }, "CheckoutResponse": { "type": "object", "required": [ "checkout_url" ], "properties": { "checkout_url": { "type": "string", "format": "uri" } } } }, "responses": { "BadRequest": { "description": "Invalid request (`invalid_request`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing, unknown or revoked key (`unauthorized`, `key_revoked`).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Key not allowed here: wrong tenant/site, Origin not in the site's domains, or area IDX not enabled.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Not found in the caller's tenant (another tenant's ids also return this).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Conflict": { "description": "The change breaks a rule (e.g. going live without an approved license).", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "SiteForbidden": { "description": "Refused (`site_forbidden`): a site-scoped key named `site_id: null` (the tenant default) or another site. Only a tenant-wide key or the console session may change the default route.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "RateLimited": { "description": "Too many requests (`rate_limited`); see Retry-After.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }