{ "openapi": "3.1.0", "info": { "title": "BuildBetter public website API", "version": "1.0.0", "description": "Discovery, public website content, the website assistant, and user-initiated forms. This specification does not describe the separate authenticated BuildBetter customer-data API or MCP service.\n\nVersioning: every response carries API-Version. Clients may pin a version with the API-Version request header; unsupported versions return 400. Breaking changes ship only under a new API-Version. A superseded version keeps working for at least 90 days, and its responses carry Deprecation (RFC 9745) and Sunset (RFC 8594) headers during that window.\n\nRate limits: responses carry RateLimit-Policy and RateLimit headers (IETF httpapi-ratelimit-headers) plus X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset. Limits are counted per client IP: 300 reads, 30 assistant requests, and 20 form submissions per minute. Exceeding a limit returns 429 with Retry-After.", "contact": { "name": "BuildBetter support", "email": "support@buildbetter.app", "url": "https://buildbetter.ai/contact" }, "x-api-versioning": { "strategy": "header", "header": "API-Version", "current": "1", "deprecationNotice": "Deprecation and Sunset response headers", "minimumSupportDays": 90 } }, "servers": [ { "url": "https://buildbetter.ai" } ], "externalDocs": { "description": "Product API and authenticated MCP documentation", "url": "https://docs.buildbetter.ai/" }, "paths": { "/api/contact": { "post": { "operationId": "contact", "summary": "Submit contact", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "inquiryType": { "type": "string" }, "message": { "type": "string" } }, "required": [ "name", "email", "inquiryType", "message" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/builder-waitlist": { "post": { "operationId": "builderWaitlist", "summary": "Submit builder waitlist", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "company": { "type": "string" }, "useCase": { "type": "string" } }, "required": [ "email", "name" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/development-waitlist": { "post": { "operationId": "developmentWaitlist", "summary": "Submit development waitlist", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "name": { "type": "string" }, "company": { "type": "string" }, "useCase": { "type": "string" } }, "required": [ "email", "name" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/embed-inquiry": { "post": { "operationId": "embedInquiry", "summary": "Submit embed inquiry", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "dataTypes": { "type": "string" }, "useCase": { "type": "string" } }, "required": [ "name", "email" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/mobile-reminder": { "post": { "operationId": "mobileReminder", "summary": "Submit mobile reminder", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/manifesto-download": { "post": { "operationId": "manifestoDownload", "summary": "Submit manifesto download", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "source": { "type": "string" }, "timestamp": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/csdemo": { "post": { "operationId": "csdemo", "summary": "Submit csdemo", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "format": "email" }, "process": { "type": "string" }, "goal": { "type": "string" }, "source": { "type": "string" } }, "required": [ "email" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/discounted-application": { "post": { "operationId": "discountedApplication", "summary": "Submit discounted application", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "orgType": { "type": "string" }, "companyName": { "type": "string" }, "domain": { "type": "string" }, "email": { "type": "string", "format": "email" }, "country": { "type": "string" }, "employees": { "type": "string" }, "fundingRaised": { "type": "string" }, "annualRevenue": { "type": "string" }, "partnerProgram": { "type": "string" }, "message": { "type": "string" } }, "required": [ "email", "companyName", "orgType" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/partner-application": { "post": { "operationId": "partnerApplication", "summary": "Submit partner application", "description": "User-initiated form submission. May send an email or notify the BuildBetter team. Agents must obtain the user’s authorization before submitting. A success response acknowledges acceptance; it does not confirm downstream delivery.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "partnerType": { "type": "string" }, "name": { "type": "string" }, "email": { "type": "string", "format": "email" }, "company": { "type": "string" }, "website": { "type": "string" }, "linkedin": { "type": "string" }, "expertise": { "type": "string" }, "audience": { "type": "string" }, "experience": { "type": "string" }, "message": { "type": "string" } }, "required": [ "email", "name", "company", "partnerType", "expertise", "experience" ] } } } }, "responses": { "200": { "description": "Submission accepted.", "content": { "application/json": { "schema": { "type": "object", "required": [ "success" ], "properties": { "success": { "const": true } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "415": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "500": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/agent": { "post": { "operationId": "askWebsiteAssistant", "summary": "Ask the public website assistant", "description": "Returns SSE data frames containing JSON events: status, text, citation, done, error, and ping. The stream is not a JSON document. Errors after streaming starts arrive as error events; HTTP validation/configuration failures use problem details. Maximum combined message content: 48,000 characters.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "messages" ], "properties": { "messages": { "type": "array", "minItems": 1, "maxItems": 30, "items": { "type": "object", "required": [ "role", "content" ], "properties": { "role": { "enum": [ "user", "assistant" ] }, "content": { "type": "string", "minLength": 1, "maxLength": 16000 } } } }, "currentPage": { "type": "string" }, "pageContext": { "type": "object", "description": "What the page shows, e.g. the BuildBetter University lesson and step. Unknown lessons are ignored.", "properties": { "lesson": { "type": "string", "example": "record-calls" }, "step": { "type": "integer", "minimum": 1 }, "t": { "type": "number", "minimum": 0, "description": "Seconds into the lesson film" } }, "required": [ "lesson" ] } } } } } }, "responses": { "200": { "description": "Server-sent events.", "content": { "text/event-stream": { "schema": { "type": "string" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "405": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "503": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/university/doc": { "get": { "operationId": "readUniversityDoc", "summary": "Read a BuildBetter docs page for University", "description": "Returns one docs.buildbetter.ai page as Markdown with its title and description, refreshed hourly from the live docs. Only docs.buildbetter.ai URLs are accepted.", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "url", "in": "query", "required": true, "schema": { "type": "string", "format": "uri" }, "example": "https://docs.buildbetter.ai/pages/Integrations/crm/hubspot" } ], "responses": { "200": { "description": "The docs page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "url", "title", "description", "markdown" ], "properties": { "url": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "markdown": { "type": "string" } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "404": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "502": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } } } }, "/api/pages": { "get": { "operationId": "listWebsitePages", "summary": "Discover current public website pages", "responses": { "200": { "description": "Canonical page index; review variants are excluded.", "content": { "application/json": { "schema": { "type": "object", "required": [ "site", "pages" ], "properties": { "site": { "type": "string", "format": "uri" }, "pages": { "type": "array", "items": { "type": "object", "required": [ "path", "title", "description", "category" ], "properties": { "path": { "type": "string" }, "title": { "type": "string" }, "description": { "type": "string" }, "category": { "type": "string" } } } } } } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } }, "parameters": [ { "$ref": "#/components/parameters/ApiVersion" } ] } }, "/api/content": { "get": { "operationId": "readWebsitePage", "summary": "Read a current public page as Markdown", "parameters": [ { "$ref": "#/components/parameters/ApiVersion" }, { "name": "path", "in": "query", "required": true, "schema": { "type": "string" }, "example": "/product/bob", "description": "A relative page path. Absolute URLs and arbitrary upstream hosts are not accepted." } ], "responses": { "200": { "description": "Markdown derived from the server-rendered page.", "content": { "text/markdown": { "schema": { "type": "string" } } }, "headers": { "Vary": { "schema": { "type": "string" }, "description": "Includes Accept and Accept-Encoding." }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "307": { "description": "Follow the canonical page URL.", "headers": { "Location": { "schema": { "type": "string" } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "308": { "description": "Permanent canonical page redirect.", "headers": { "Location": { "schema": { "type": "string" } }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "400": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "404": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "429": { "description": "Rate limit exceeded. Retry after the Retry-After interval.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "Retry-After": { "$ref": "#/components/headers/Retry-After" }, "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } }, "502": { "description": "RFC 9457 problem details; error remains a string for existing form clients.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/Problem" } } }, "headers": { "RateLimit-Policy": { "$ref": "#/components/headers/RateLimit-Policy" }, "RateLimit": { "$ref": "#/components/headers/RateLimit" }, "X-RateLimit-Limit": { "$ref": "#/components/headers/X-RateLimit-Limit" }, "X-RateLimit-Remaining": { "$ref": "#/components/headers/X-RateLimit-Remaining" }, "X-RateLimit-Reset": { "$ref": "#/components/headers/X-RateLimit-Reset" }, "API-Version": { "$ref": "#/components/headers/API-Version" } } } } } } }, "components": { "schemas": { "Problem": { "type": "object", "required": [ "type", "title", "status", "detail", "code", "resolution", "error" ], "properties": { "type": { "type": "string", "format": "uri-reference" }, "title": { "type": "string" }, "status": { "type": "integer", "minimum": 400, "maximum": 599 }, "detail": { "type": "string" }, "code": { "type": "string" }, "resolution": { "type": "string" }, "error": { "type": "string", "description": "Compatibility alias for detail." } } } }, "parameters": { "ApiVersion": { "name": "API-Version", "in": "header", "required": false, "description": "Pins the API version. Omit it to use the current version.", "schema": { "type": "string", "enum": [ "1" ], "default": "1" } } }, "headers": { "API-Version": { "description": "The API version that served the response.", "schema": { "type": "string" }, "example": "1" }, "RateLimit-Policy": { "description": "Quota and window in seconds for this endpoint class.", "schema": { "type": "string" }, "example": "\"read\";q=300;w=60" }, "RateLimit": { "description": "Requests remaining and seconds until the window resets.", "schema": { "type": "string" }, "example": "\"read\";r=299;t=60" }, "X-RateLimit-Limit": { "description": "Requests allowed in the current window.", "schema": { "type": "integer" }, "example": 300 }, "X-RateLimit-Remaining": { "description": "Requests left in the current window.", "schema": { "type": "integer" }, "example": 299 }, "X-RateLimit-Reset": { "description": "Seconds until the current window resets.", "schema": { "type": "integer" }, "example": 60 }, "Retry-After": { "description": "Seconds to wait before retrying.", "schema": { "type": "integer" } } }, "securitySchemes": { "buildbetterOAuth": { "type": "oauth2", "description": "OAuth 2.0 for the authenticated BuildBetter MCP server at https://mcp.buildbetter.app (protected-resource metadata: https://mcp.buildbetter.app/.well-known/oauth-protected-resource). The public website endpoints in this document require no authentication.", "flows": { "authorizationCode": { "authorizationUrl": "https://mcp.buildbetter.app/authorize", "tokenUrl": "https://mcp.buildbetter.app/token", "refreshUrl": "https://mcp.buildbetter.app/token", "scopes": { "openid": "Sign in with your BuildBetter account.", "profile": "Read your name and profile.", "email": "Read your email address.", "offline_access": "Keep access with a refresh token.", "service_account": "Act as a workspace service account." } } } } } } }