{ "openapi": "3.1.0", "info": { "title": "ClientPad Muse Connector API", "version": "1.0.0", "description": "Create no-login client intakes, collect structured answers, publish proposals, and read client decisions. ClientPad stores workflow state; it does not generate or summarize content with AI." }, "servers": [ { "url": "https://cp.site-ai-gateway.com" } ], "paths": { "/api/muse/intakes": { "post": { "operationId": "createIntake", "summary": "Create a client intake", "description": "Create a shareable no-login ClientPad intake page for collecting structured requirements from a client.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "questions" ], "properties": { "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "client_name": { "type": "string", "maxLength": 120 }, "questions": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "id", "label", "type" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "example": "goal" }, "label": { "type": "string", "maxLength": 160, "example": "What is the main goal?" }, "type": { "type": "string", "enum": [ "short_text", "long_text", "single_choice", "multi_choice", "yes_no" ] }, "required": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } } }, "language": { "type": "string", "enum": [ "en", "ja", "zh" ], "default": "en" } } }, "example": { "title": "Website redesign discovery", "description": "Please answer a few questions so we can prepare the proposal.", "client_name": "Acme Inc.", "questions": [ { "id": "goal", "label": "What is the main goal?", "type": "long_text", "required": true }, { "id": "budget", "label": "What budget range do you have in mind?", "type": "single_choice", "options": [ "Under $1,000", "$1,000–$3,000", "$3,000–$10,000", "Not decided" ] } ], "language": "en" } } } }, "responses": { "201": { "description": "Intake created. The manage token is returned only in this response.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "intake_id", "public_url", "manage_token", "status" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "intake_id": { "type": "string", "format": "uuid" }, "public_url": { "type": "string", "format": "uri" }, "manage_token": { "type": "string", "description": "Secret returned once. Store it securely and never share it with the client." }, "status": { "type": "string", "enum": [ "open" ] } } } } } }, "400": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "429": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/muse/intakes/{projectId}": { "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } } ], "get": { "operationId": "getIntake", "summary": "Get intake configuration", "description": "Get the current configuration, public URL, and response status of a ClientPad intake. This operation does not return the manage token or client answers.", "responses": { "200": { "description": "Current intake.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "intake_id", "title", "description", "client_name", "questions", "language", "status", "response_status", "public_url", "created_at", "updated_at" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "intake_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "client_name": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "example": "goal" }, "label": { "type": "string", "maxLength": 160, "example": "What is the main goal?" }, "type": { "type": "string", "enum": [ "short_text", "long_text", "single_choice", "multi_choice", "yes_no" ] }, "required": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } } }, "language": { "type": "string", "enum": [ "en", "ja", "zh" ] }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "response_status": { "type": "string", "enum": [ "not_submitted", "submitted" ] }, "public_url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "404": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } }, "patch": { "operationId": "updateIntake", "summary": "Update an intake", "description": "Update intake content or close it while protecting questions and selected options that already have client responses.", "parameters": [ { "name": "X-ClientPad-Manage-Token", "in": "header", "required": true, "description": "The per-project manage token returned only when the intake is created.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "minProperties": 1, "properties": { "title": { "type": "string", "maxLength": 120 }, "description": { "type": "string", "maxLength": 1000 }, "client_name": { "type": "string", "maxLength": 120 }, "questions": { "type": "array", "minItems": 1, "maxItems": 20, "items": { "type": "object", "required": [ "id", "label", "type" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "example": "goal" }, "label": { "type": "string", "maxLength": 160, "example": "What is the main goal?" }, "type": { "type": "string", "enum": [ "short_text", "long_text", "single_choice", "multi_choice", "yes_no" ] }, "required": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } } }, "language": { "type": "string", "enum": [ "en", "ja", "zh" ] }, "status": { "type": "string", "enum": [ "open", "closed" ] } } } } } }, "responses": { "200": { "description": "Updated intake.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "intake_id", "title", "description", "client_name", "questions", "language", "status", "response_status", "public_url", "created_at", "updated_at" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "intake_id": { "type": "string", "format": "uuid" }, "title": { "type": "string" }, "description": { "type": "string" }, "client_name": { "type": "string" }, "questions": { "type": "array", "items": { "type": "object", "required": [ "id", "label", "type" ], "properties": { "id": { "type": "string", "pattern": "^[A-Za-z0-9_-]{1,40}$", "example": "goal" }, "label": { "type": "string", "maxLength": 160, "example": "What is the main goal?" }, "type": { "type": "string", "enum": [ "short_text", "long_text", "single_choice", "multi_choice", "yes_no" ] }, "required": { "type": "boolean", "default": false }, "options": { "type": "array", "items": { "type": "string" }, "maxItems": 20 } } } }, "language": { "type": "string", "enum": [ "en", "ja", "zh" ] }, "status": { "type": "string", "enum": [ "open", "closed" ] }, "response_status": { "type": "string", "enum": [ "not_submitted", "submitted" ] }, "public_url": { "type": "string", "format": "uri" }, "created_at": { "type": "string", "format": "date-time" }, "updated_at": { "type": "string", "format": "date-time" } } } } } }, "400": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "409": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/muse/intakes/{projectId}/responses": { "get": { "operationId": "getIntakeResponses", "summary": "Get client answers", "description": "Get structured answers submitted by the client through a ClientPad intake page.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-ClientPad-Manage-Token", "in": "header", "required": true, "description": "The per-project manage token returned only when the intake is created.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Submission state and structured answers.", "content": { "application/json": { "schema": { "type": "object", "required": [ "project_id", "status", "submitted_at", "responses" ], "properties": { "project_id": { "type": "string", "format": "uuid" }, "status": { "type": "string", "enum": [ "not_submitted", "submitted" ] }, "submitted_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "responses": { "type": "object", "additionalProperties": { "oneOf": [ { "type": "string" }, { "type": "boolean" }, { "type": "array", "items": { "type": "string" } } ] } } } } } } }, "401": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/muse/projects/{projectId}/proposals": { "post": { "operationId": "publishProposal", "summary": "Publish a proposal", "description": "Publish a client-facing proposal page with scope, timeline, pricing and approval controls.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-ClientPad-Manage-Token", "in": "header", "required": true, "description": "The per-project manage token returned only when the intake is created.", "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "title", "summary", "scope", "timeline", "price" ], "properties": { "title": { "type": "string", "maxLength": 160 }, "summary": { "type": "string", "maxLength": 2000 }, "scope": { "type": "array", "minItems": 1, "maxItems": 50, "items": { "type": "string", "maxLength": 300 } }, "timeline": { "type": "string", "maxLength": 300 }, "price": { "type": "object", "required": [ "amount", "currency" ], "properties": { "amount": { "type": "number", "minimum": 0 }, "currency": { "type": "string", "pattern": "^[A-Za-z]{3}$" } } }, "notes": { "type": "string", "maxLength": 2000 } } }, "example": { "title": "Website Redesign Proposal", "summary": "Redesign and rebuild the company website.", "scope": [ "Homepage redesign", "Responsive implementation", "Contact form" ], "timeline": "4 weeks", "price": { "amount": 4500, "currency": "USD" }, "notes": "Hosting is not included." } } } }, "responses": { "201": { "description": "Proposal published.", "content": { "application/json": { "schema": { "type": "object", "required": [ "proposal_id", "project_id", "version", "public_url", "status" ], "properties": { "proposal_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "public_url": { "type": "string", "format": "uri" }, "status": { "type": "string", "enum": [ "published" ] } } } } } }, "400": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "401": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } }, "/api/muse/projects/{projectId}/proposal-status": { "get": { "operationId": "getProposalStatus", "summary": "Get proposal status", "description": "Check whether the client viewed, approved, rejected or requested changes to a published proposal.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }, { "name": "X-ClientPad-Manage-Token", "in": "header", "required": true, "description": "The per-project manage token returned only when the intake is created.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "Latest proposal status, view timestamps, decision timestamp, and client comment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "proposal_id", "project_id", "version", "status", "viewed", "first_viewed_at", "last_viewed_at", "decision_at", "client_comment" ], "properties": { "proposal_id": { "type": "string", "format": "uuid" }, "project_id": { "type": "string", "format": "uuid" }, "version": { "type": "integer", "minimum": 1 }, "status": { "type": "string", "enum": [ "published", "viewed", "approved", "changes_requested", "rejected" ] }, "viewed": { "type": "boolean" }, "first_viewed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "last_viewed_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "decision_at": { "oneOf": [ { "type": "string", "format": "date-time" }, { "type": "null" } ] }, "client_comment": { "type": "string" } } } } } }, "401": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } }, "404": { "description": "Request failed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } } } } } } } } } } } }