{ "openapi": "3.1.0", "info": { "title": "StageGrow API", "version": "1.0.0", "summary": "Organization-scoped API for home staging companies.", "description": "StageGrow (formerly DesignGrow) is the operating system for US home staging companies. Every call is scoped to one organization.\n\n**For AI agents, the MCP server at `/mcp` is the primary interface**: it exposes every capability of the app (hard parity rule) and accepts an organization MCP API key or an OAuth 2.0 access token. See https://my.designgrow.app/docs#mcp.\n\nThe REST endpoints marked with the `session` scheme are the endpoints the StageGrow web app calls with a signed-in browser session. Webhook subscriptions use the Zapier OAuth token.\n\nRate limits: endpoints that are expensive or abuse-prone carry per-IP burst limits (for example OAuth client registration: 10 per minute; public form endpoints: 5 to 10 per minute).\n\nA throttled request gets HTTP 429 with a `Retry-After` header in seconds. Wait that long, then retry.\n\nFair-use targets per plan (growth 500/hour, professional 1000/hour) are published but not enforced per request today.\n\nWebhook events: project.created, project.updated, project.status_changed, project.deleted, client.created, client.updated, client.deleted, inventory.created, inventory.updated, inventory.status_changed, inventory.deleted, service.created, service.updated, service.deleted.", "contact": { "name": "StageGrow support", "email": "support@designgrow.app", "url": "https://my.designgrow.app/docs" }, "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" } }, "externalDocs": { "description": "Developer docs", "url": "https://my.designgrow.app/docs" }, "servers": [ { "url": "https://my.designgrow.app/api/v1", "description": "Production, version 1 (also served unversioned at /api)" } ], "tags": [ { "name": "Projects", "description": "Manage staging projects, assignments, and lifecycle" }, { "name": "Inventory", "description": "Manage furniture and decor inventory items" }, { "name": "Clients", "description": "Manage client contacts and companies" }, { "name": "Webhooks", "description": "Subscribe to real-time event notifications" }, { "name": "Services", "description": "Manage service offerings and pricing" }, { "name": "OAuth", "description": "OAuth 2.1 discovery, connector authorization, and grant management" }, { "name": "Agent discovery", "description": "Public, unauthenticated documents agents use to find and connect to StageGrow (AgentReady v2.0)" } ], "paths": { "/projects": { "get": { "operationId": "getProjects", "summary": "Get paginated list of projects with optional filters", "description": "List all projects in your organization\n\nResponse shape: `{ projects: Project[], total: number }`\n\nRequires the professional plan or higher.", "tags": [ "Projects" ], "x-required-tier": "professional", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 100)", "schema": { "type": "number" }, "example": "50" }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "number" }, "example": "0" }, { "name": "status", "in": "query", "required": false, "description": "Filter by status (planning, in_progress, staging, completed, cancelled)", "schema": { "type": "string" }, "example": "staging" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "List of projects with client and assignment details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postProjects", "summary": "Create a staging project with optional client association", "description": "Create a new project\n\nResponse shape: `{ project: Project }`\n\nRequires the professional plan or higher.", "tags": [ "Projects" ], "x-required-tier": "professional", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Project name" }, "client_id": { "type": "string", "format": "uuid", "description": "Associated client ID" }, "address": { "type": "string", "description": "Property address" }, "city": { "type": "string", "description": "City" }, "state": { "type": "string", "description": "State" }, "zip": { "type": "string", "description": "ZIP code" }, "stage_date": { "type": "string", "format": "date", "description": "Staging date (ISO 8601)" }, "destage_date": { "type": "string", "format": "date", "description": "Destaging date (ISO 8601)" }, "status": { "type": "string", "description": "Initial status (default: planning)" } }, "required": [ "name" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The created project", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/projects/{id}": { "get": { "operationId": "getProjectsById", "summary": "Retrieve full project details including rooms and inventory", "description": "Get a specific project by ID\n\nResponse shape: `{ project: Project }`\n\nRequires the professional plan or higher.", "tags": [ "Projects" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Project with full details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "putProjectsById", "summary": "Update project fields (partial updates supported)", "description": "Update a project\n\nResponse shape: `{ project: Project }`\n\nRequires the professional plan or higher.", "tags": [ "Projects" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "The updated project", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteProjectsById", "summary": "Permanently delete a project and all associated data", "description": "Delete a project\n\nResponse shape: `{ success: true }`\n\nRequires the professional plan or higher.", "tags": [ "Projects" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Success confirmation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/inventory": { "get": { "operationId": "getInventory", "summary": "Get paginated inventory with search and filters", "description": "List all inventory items\n\nResponse shape: `{ items: InventoryItem[], total: number }`\n\nRequires the professional plan or higher.", "tags": [ "Inventory" ], "x-required-tier": "professional", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 1000)", "schema": { "type": "number" }, "example": "100" }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "number" }, "example": "0" }, { "name": "search", "in": "query", "required": false, "description": "Search by name, SKU, or location", "schema": { "type": "string" }, "example": "sofa" }, { "name": "categories", "in": "query", "required": false, "description": "Comma-separated category filters", "schema": { "type": "string" }, "example": "Seating,Tables" }, { "name": "availability", "in": "query", "required": false, "description": "Filter by status (available, staged, maintenance)", "schema": { "type": "string" }, "example": "available" }, { "name": "warehouse", "in": "query", "required": false, "description": "Filter by warehouse location", "schema": { "type": "string" }, "example": "Main Warehouse" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "List of inventory items", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postInventory", "summary": "Add a new item to inventory with optional images", "description": "Create a new inventory item\n\nResponse shape: `{ item: InventoryItem }`\n\nRequires the professional plan or higher.", "tags": [ "Inventory" ], "x-required-tier": "professional", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Item name" }, "sku": { "type": "string", "description": "Stock keeping unit (auto-generated if not provided)" }, "category_id": { "type": "string", "format": "uuid", "description": "Category ID" }, "quantity": { "type": "number", "description": "Stock quantity (default: 1)" }, "rental_price": { "type": "number", "description": "Rental price per period" }, "purchase_price": { "type": "number", "description": "Original purchase price" }, "location": { "type": "string", "description": "Storage location/warehouse" }, "description": { "type": "string", "description": "Item description" }, "dimensions": { "type": "string", "description": "Dimensions (e.g., \"72x36x30\")" }, "color": { "type": "string", "description": "Primary color" }, "material": { "type": "string", "description": "Primary material" } }, "required": [ "name" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The created inventory item", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/inventory/{id}": { "get": { "operationId": "getInventoryById", "summary": "Retrieve full item details including project assignments", "description": "Get a specific inventory item\n\nResponse shape: `{ item: InventoryItem }`\n\nRequires the professional plan or higher.", "tags": [ "Inventory" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Inventory item with full details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "put": { "operationId": "putInventoryById", "summary": "Update item fields (partial updates supported)", "description": "Update an inventory item\n\nResponse shape: `{ item: InventoryItem }`\n\nRequires the professional plan or higher.", "tags": [ "Inventory" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "The updated inventory item", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteInventoryById", "summary": "Permanently delete an item from inventory", "description": "Delete an inventory item\n\nResponse shape: `{ success: true }`\n\nRequires the professional plan or higher.", "tags": [ "Inventory" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Success confirmation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/contacts": { "get": { "operationId": "getContacts", "summary": "One row per real party, folded from clients, companies, sales accounts, sales contacts and cross-entity leads. Read-only; filter by role and lifecycle. Each row lists every place it was found, so duplicates are visible.", "description": "The contact directory — every party, once\n\nResponse shape: `{ contacts: DirectoryEntry[], total: number, directory_total: number, facets: { roles, lifecycles, sources, duplicates }, truncated: boolean, skipped_sources: string[] }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Match name, email, phone or company", "schema": { "type": "string" }, "example": "jessica" }, { "name": "role", "in": "query", "required": false, "description": "realtor | brokerage | team | builder | seller | homeowner | partner | franchise_prospect", "schema": { "type": "string" }, "example": "realtor" }, { "name": "lifecycle", "in": "query", "required": false, "description": "prospect | engaged | customer | dormant | lost", "schema": { "type": "string" }, "example": "customer" }, { "name": "party_type", "in": "query", "required": false, "description": "person | organization", "schema": { "type": "string" }, "example": "organization" }, { "name": "source", "in": "query", "required": false, "description": "Only parties found in this table: contact | company | sales_account | sales_contact | lead", "schema": { "type": "string" }, "example": "lead" }, { "name": "duplicates_only", "in": "query", "required": false, "description": "Set to 1 for only parties found in more than one place", "schema": { "type": "string" }, "example": "1" }, { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 100, max: 200)", "schema": { "type": "number" }, "example": "50" }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "number" }, "example": "0" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Folded directory entries plus facet counts", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/clients": { "get": { "operationId": "getClients", "summary": "Get paginated list of clients with search", "description": "List all clients\n\nResponse shape: `{ clients: Client[], total: number }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "limit", "in": "query", "required": false, "description": "Max results (default: 100)", "schema": { "type": "number" }, "example": "50" }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "number" }, "example": "0" }, { "name": "search", "in": "query", "required": false, "description": "Search by name, email, or phone", "schema": { "type": "string" }, "example": "john" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "List of clients", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postClients", "summary": "Add a client contact with optional company association", "description": "Create a new client\n\nResponse shape: `{ client: Client }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Client name" }, "email": { "type": "string", "description": "Email address" }, "phone": { "type": "string", "description": "Phone number" }, "company_id": { "type": "string", "format": "uuid", "description": "Associated company ID" }, "is_realtor": { "type": "boolean", "description": "Whether client is a realtor" }, "notes": { "type": "string", "description": "Additional notes" } }, "required": [ "name" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The created client", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/clients/{id}": { "get": { "operationId": "getClientsById", "summary": "Retrieve full client details with project history", "description": "Get a specific client\n\nResponse shape: `{ client: Client }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Client with full details", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/clients/{id}/roles": { "get": { "operationId": "getClientsByIdRoles", "summary": "Current roles for a contact (realtor, brokerage, seller, …). Supersedes the is_realtor boolean.", "description": "List a contact's roles\n\nResponse shape: `{ roles: ContactRole[] }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "include_ended", "in": "query", "required": false, "description": "Set to 1 to include ended roles as history", "schema": { "type": "string" }, "example": "1" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Roles on the contact", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postClientsByIdRoles", "summary": "Roles are multi-valued and dated — a realtor selling her own house holds two", "description": "Give a contact a role\n\nResponse shape: `{ role: ContactRole }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "role": { "type": "string", "description": "realtor | brokerage | team | builder | seller | homeowner | partner | franchise_prospect" }, "started_at": { "type": "string", "description": "ISO date the role began (default: today)", "examples": [ "2026-10-02" ] }, "source": { "type": "string", "description": "manual | import | agent (default: manual)" } }, "required": [ "role" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The assigned role", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteClientsByIdRoles", "summary": "Sets ended_at instead of deleting, so the history survives", "description": "End a contact's role\n\nResponse shape: `{ role: ContactRole }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "role", "in": "query", "required": true, "description": "The role to end", "schema": { "type": "string" } }, { "name": "ended_at", "in": "query", "required": false, "description": "ISO date the role ended (default: today)", "schema": { "type": "string" }, "example": "2026-10-02" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "The ended role", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/clients/{id}/relationships": { "get": { "operationId": "getClientsByIdRelationships", "summary": "Dated edges: agent_of (realtor → brokerage/team), team_of, employee_of, referred_by. direction=to lists a brokerage's agents.", "description": "List a contact's relationships\n\nResponse shape: `{ relationships: ContactRelationship[] }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "direction", "in": "query", "required": false, "description": "from (default) | to", "schema": { "type": "string" } }, { "name": "relationship", "in": "query", "required": false, "description": "agent_of | team_of | employee_of | referred_by", "schema": { "type": "string" } }, { "name": "include_ended", "in": "query", "required": false, "description": "Set to 1 to include ended edges as history", "schema": { "type": "string" }, "example": "1" } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Edges", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postClientsByIdRelationships", "summary": "Idempotent while the same edge is live; an ended edge can be opened again", "description": "Open a relationship from this contact\n\nResponse shape: `{ relationship: ContactRelationship }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "to_contact_id": { "type": "string", "description": "The other contact" }, "relationship": { "type": "string", "description": "agent_of | team_of | employee_of | referred_by" }, "started_at": { "type": "string", "description": "ISO date (default: today)" }, "is_primary": { "type": "boolean", "description": "Make this the primary live edge of its kind" } }, "required": [ "to_contact_id", "relationship" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The edge", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteClientsByIdRelationships", "summary": "Sets ended_at; the edge stays as history", "description": "End a relationship\n\nResponse shape: `{ relationship: ContactRelationship }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "relationship_id", "in": "query", "required": true, "description": "The edge to end", "schema": { "type": "string" } }, { "name": "ended_at", "in": "query", "required": false, "description": "ISO date (default: today)", "schema": { "type": "string" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "The ended edge", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/clients/{id}/identifiers": { "get": { "operationId": "getClientsByIdIdentifiers", "summary": "License numbers by state, MLS agent/office ids, NRDS numbers", "description": "List a contact's identifiers\n\nResponse shape: `{ identifiers: ContactIdentifier[] }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Identifiers", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postClientsByIdIdentifiers", "summary": "Normalized; 409 names the contact that already holds it (a duplicate to merge)", "description": "Record an identifier\n\nResponse shape: `{ identifier: ContactIdentifier }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "id_type": { "type": "string", "description": "license | mls_agent_id | mls_office_id | nrds" }, "id_value": { "type": "string", "description": "The number" }, "scope": { "type": "string", "description": "Two-letter state for a license; MLS code for an MLS id" } }, "required": [ "id_type", "id_value" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The identifier", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteClientsByIdIdentifiers", "summary": "For a wrongly entered number", "description": "Remove an identifier\n\nResponse shape: `{ identifier: ContactIdentifier }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "identifier_id", "in": "query", "required": true, "description": "The identifier", "schema": { "type": "string" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "The removed identifier", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/realtors": { "get": { "operationId": "getRealtors", "summary": "Contacts with the realtor role, their current brokerage and listing counts", "description": "List realtors\n\nResponse shape: `{ realtors: Realtor[], total: number }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Name, email or phone", "schema": { "type": "string" } }, { "name": "brokerage_id", "in": "query", "required": false, "description": "Only realtors currently with this brokerage", "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "description": "1–200 (default 100)", "schema": { "type": "number" } }, { "name": "offset", "in": "query", "required": false, "description": "Pagination offset", "schema": { "type": "number" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Realtors", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/realtors/{id}": { "get": { "operationId": "getRealtorsById", "summary": "Identifiers, current brokerage, brokerage history with dates, projects listed or booked", "description": "Get a realtor\n\nResponse shape: `{ realtor, brokerage, affiliations, identifiers, projects, project_count }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Realtor detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/realtors/{id}/affiliation": { "post": { "operationId": "postRealtorsByIdAffiliation", "summary": "Ends the previous primary brokerage on the move date and keeps it as history", "description": "Set a realtor's brokerage\n\nResponse shape: `{ affiliation, ended, demoted }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "brokerage_id": { "type": "string", "description": "A contact with the brokerage or team role" }, "started_at": { "type": "string", "description": "Move date (default: today)" }, "end_previous": { "type": "boolean", "description": "false keeps the old brokerage live but not primary" } }, "required": [ "brokerage_id" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The new and ended affiliations", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/brokerages": { "get": { "operationId": "getBrokerages", "summary": "Brokerages and teams with current/past realtor counts and attributed projects", "description": "List brokerages\n\nResponse shape: `{ brokerages: Brokerage[], total: number }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "search", "in": "query", "required": false, "description": "Name", "schema": { "type": "string" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Brokerages", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/brokerages/{id}": { "get": { "operationId": "getBrokeragesById", "summary": "Current and past realtors with dates; projects attributed as of when the work happened", "description": "Get a brokerage\n\nResponse shape: `{ brokerage, current_agents, past_agents, projects }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Brokerage detail", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/projects/{id}/listing-agent": { "put": { "operationId": "putProjectsByIdListingAgent", "summary": "Links a realtor contact and mirrors her name and brokerage into the project's realtor text; null unlinks", "description": "Set a project's listing agent\n\nResponse shape: `{ project, brokerage }`\n\nRequires the professional plan or higher.", "tags": [ "Clients" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "contact_id": { "type": "string", "description": "Realtor contact id, or null" } }, "required": [ "contact_id" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The project link", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/webhooks/subscribe": { "get": { "operationId": "getWebhooksSubscribe", "summary": "Get all webhook subscriptions for your organization", "description": "List active webhook subscriptions\n\nResponse shape: `{ subscriptions: WebhookSubscription[] }`\n\nRequires the growth plan or higher.", "tags": [ "Webhooks" ], "x-required-tier": "growth", "security": [ { "zapierOAuth": [] } ], "responses": { "200": { "description": "List of active subscriptions", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postWebhooksSubscribe", "summary": "Create a new webhook subscription for event notifications", "description": "Subscribe to webhook events\n\nResponse shape: `{ id: string, event_type: string, target_url: string }`\n\nRequires the growth plan or higher.", "tags": [ "Webhooks" ], "x-required-tier": "growth", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "event_type": { "type": "string", "description": "Event type to subscribe to (e.g., project.created)", "examples": [ "project.created" ] }, "target_url": { "type": "string", "description": "URL to receive webhook payloads", "examples": [ "https://example.com/webhook" ] }, "secret": { "type": "string", "description": "Shared secret for signature verification" } }, "required": [ "event_type", "target_url" ] } } } }, "security": [ { "zapierOAuth": [] } ], "responses": { "200": { "description": "The created subscription", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteWebhooksSubscribe", "summary": "Remove a webhook subscription", "description": "Unsubscribe from webhook events\n\nResponse shape: `{ success: true }`\n\nRequires the growth plan or higher.", "tags": [ "Webhooks" ], "x-required-tier": "growth", "parameters": [ { "name": "id", "in": "query", "required": true, "description": "Subscription ID to delete", "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "zapierOAuth": [] } ], "responses": { "200": { "description": "Success confirmation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/services": { "get": { "operationId": "getServices", "summary": "Get available staging services and pricing", "description": "List all services\n\nResponse shape: `{ services: Service[] }`\n\nRequires the professional plan or higher.", "tags": [ "Services" ], "x-required-tier": "professional", "security": [ { "session": [] } ], "responses": { "200": { "description": "List of services", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postServices", "summary": "Add a new service offering", "description": "Create a new service\n\nResponse shape: `{ service: Service }`\n\nRequires the professional plan or higher.", "tags": [ "Services" ], "x-required-tier": "professional", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "name": { "type": "string", "description": "Service name" }, "description": { "type": "string", "description": "Service description" }, "base_price": { "type": "number", "description": "Base price" }, "unit": { "type": "string", "description": "Pricing unit (e.g., per_month, per_room)" } }, "required": [ "name" ] } } } }, "security": [ { "session": [] } ], "responses": { "200": { "description": "The created service", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-protected-resource": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getWellKnownOauthProtectedResource", "summary": "Discover the MCP protected resource and its authorization server", "description": "Discover the MCP protected resource and its authorization server", "tags": [ "OAuth" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-authorization-server": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getWellKnownOauthAuthorizationServer", "summary": "Discover OAuth authorization, token, registration, scope, and PKCE metadata", "description": "Discover OAuth authorization, token, registration, scope, and PKCE metadata", "tags": [ "OAuth" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/oauth/register": { "servers": [ { "url": "https://my.designgrow.app" } ], "post": { "operationId": "postOauthRegister", "summary": "Dynamically register an MCP OAuth client and its validated redirect URIs", "description": "Dynamically register an MCP OAuth client and its validated redirect URIs", "tags": [ "OAuth" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/oauth/authorize": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getOauthAuthorize", "summary": "Show the authenticated user an OAuth connector consent screen", "description": "Show the authenticated user an OAuth connector consent screen", "tags": [ "OAuth" ], "x-required-tier": "free", "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/oauth/authorize/decision": { "servers": [ { "url": "https://my.designgrow.app" } ], "post": { "operationId": "postOauthAuthorizeDecision", "summary": "Approve or deny consent and issue a single-use PKCE authorization code", "description": "Approve or deny consent and issue a single-use PKCE authorization code", "tags": [ "OAuth" ], "x-required-tier": "free", "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/api/oauth/token": { "servers": [ { "url": "https://my.designgrow.app" } ], "post": { "operationId": "postOauthToken", "summary": "Exchange a code or rotating refresh token for an MCP access token", "description": "Exchange a code or rotating refresh token for an MCP access token", "tags": [ "OAuth" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/settings/oauth-grants": { "get": { "operationId": "getSettingsOauthGrants", "summary": "List OAuth connector grants for the owner's organization", "description": "List OAuth connector grants for the owner's organization\n\nRequires the professional plan or higher.", "tags": [ "OAuth" ], "x-required-tier": "professional", "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/settings/oauth-grants/{id}": { "delete": { "operationId": "deleteSettingsOauthGrantsById", "summary": "Revoke an OAuth connector grant in the owner's organization", "description": "Revoke an OAuth connector grant in the owner's organization\n\nRequires the professional plan or higher.", "tags": [ "OAuth" ], "x-required-tier": "professional", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "security": [ { "session": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mcp": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getMcp", "summary": "Open or inspect an MCP Streamable HTTP session using an API key or OAuth access token", "description": "Open or inspect an MCP Streamable HTTP session using an API key or OAuth access token\n\nRequires the professional plan or higher.", "tags": [ "OAuth" ], "x-required-tier": "professional", "security": [ { "mcpApiKey": [] }, { "oauth2": [ "read", "write", "finance" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "post": { "operationId": "postMcp", "summary": "Canonical MCP Streamable HTTP endpoint (same server as /api/mcp) using an API key or OAuth access token", "description": "Canonical MCP Streamable HTTP endpoint (same server as /api/mcp) using an API key or OAuth access token\n\nRequires the professional plan or higher.", "tags": [ "Agent discovery" ], "x-required-tier": "professional", "security": [ { "mcpApiKey": [] }, { "oauth2": [ "read", "write", "finance" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } }, "delete": { "operationId": "deleteMcp", "summary": "Close an MCP Streamable HTTP session using an API key or OAuth access token", "description": "Close an MCP Streamable HTTP session using an API key or OAuth access token\n\nRequires the professional plan or higher.", "tags": [ "OAuth" ], "x-required-tier": "professional", "security": [ { "mcpApiKey": [] }, { "oauth2": [ "read", "write", "finance" ] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/mcp/server-card": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getMcpServerCard", "summary": "MCP server card (SEP-2127) for pre-connection discovery", "description": "MCP server card (SEP-2127) for pre-connection discovery", "tags": [ "Agent discovery" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-protected-resource/mcp": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getWellKnownOauthProtectedResourceMcp", "summary": "RFC 9728 protected-resource metadata for the /mcp endpoint", "description": "RFC 9728 protected-resource metadata for the /mcp endpoint", "tags": [ "Agent discovery" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/oauth-protected-resource/api/mcp": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getWellKnownOauthProtectedResourceApiMcp", "summary": "RFC 9728 protected-resource metadata for the legacy /api/mcp endpoint", "description": "RFC 9728 protected-resource metadata for the legacy /api/mcp endpoint", "tags": [ "Agent discovery" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/.well-known/ai-catalog.json": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getWellKnownAiCatalogJson", "summary": "AI Catalog listing the MCP servers, OpenAPI contract, docs and llms.txt", "description": "AI Catalog listing the MCP servers, OpenAPI contract, docs and llms.txt", "tags": [ "Agent discovery" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/openapi.json": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getOpenapiJson", "summary": "This OpenAPI 3.1 contract, generated from the API registry", "description": "This OpenAPI 3.1 contract, generated from the API registry", "tags": [ "Agent discovery" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } }, "/server.json": { "servers": [ { "url": "https://my.designgrow.app" } ], "get": { "operationId": "getServerJson", "summary": "MCP Registry server.json for the StageGrow MCP server", "description": "MCP Registry server.json for the StageGrow MCP server", "tags": [ "Agent discovery" ], "x-required-tier": "free", "security": [], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/ServerError" } } } } }, "components": { "securitySchemes": { "mcpApiKey": { "type": "http", "scheme": "bearer", "description": "Organization MCP API key (`mcp_...`), created by an organization owner in Settings > Developers with read, write and/or finance scopes." }, "oauth2": { "type": "oauth2", "description": "OAuth 2.0 authorization code with PKCE (S256). Discovery: /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource/mcp. Clients register dynamically (RFC 7591).", "flows": { "authorizationCode": { "authorizationUrl": "https://my.designgrow.app/oauth/authorize", "tokenUrl": "https://my.designgrow.app/api/oauth/token", "refreshUrl": "https://my.designgrow.app/api/oauth/token", "scopes": { "read": "List, get, search and report tools.", "write": "Create and update operational records.", "finance": "AR, invoices, payments and financial reports." } } } }, "zapierOAuth": { "type": "http", "scheme": "bearer", "description": "Access token from the Zapier OAuth flow (/api/auth/zapier)." }, "session": { "type": "apiKey", "in": "cookie", "name": "sb--auth-token", "description": "Signed-in StageGrow browser session (Supabase auth cookie). Used by the web app; agents should use the MCP server instead." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "description": "Error code or human-readable message." }, "message": { "type": "string" }, "error_description": { "type": "string", "description": "OAuth endpoints (RFC 6749 §5.2)." } }, "required": [ "error" ] } }, "headers": { "RetryAfter": { "description": "Seconds to wait before retrying (RFC 9110 §10.2.3).", "schema": { "type": "integer", "minimum": 1 } } }, "responses": { "BadRequest": { "description": "The request is malformed or fails validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Missing or invalid credentials.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Forbidden": { "description": "Authenticated, but the role, plan or scope does not allow this.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "No such resource in your organization.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "TooManyRequests": { "description": "Rate limited. Wait `Retry-After` seconds.", "headers": { "Retry-After": { "$ref": "#/components/headers/RetryAfter" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "ServerError": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }