{
  "openapi": "3.1.0",
  "info": {
    "title": "HeyCMO API",
    "version": "1.0.0",
    "summary": "REST API for HeyCMO — your AI marketing team.",
    "description": "HeyCMO is a managed AI marketing team. This OpenAPI spec covers the public REST surface (workflows, content, analytics, social, scans, webhooks, settings). Real-time agent invocation is also exposed via the MCP server at https://heycmo.ai/mcp/sse — see https://heycmo.ai/.well-known/mcp/server-card.json.\n\nAuthentication: bearer API key (format `hcmo_live_*`) in the `Authorization` header. Obtain via https://heycmo.ai/signin (self-serve, no sales call).\n\nRate limits: 60 req/min per customer for REST, 30 req/min per customer for MCP. 429 responses include `Retry-After` (seconds) and a structured JSON error body.\n\nAll responses include an `X-Request-ID` header — quote this when contacting support.",
    "termsOfService": "https://heycmo.ai/terms",
    "contact": {
      "name": "HeyCMO support",
      "email": "hello@heycmo.ai",
      "url": "https://heycmo.ai/contact"
    },
    "license": { "name": "Proprietary", "identifier": "LicenseRef-Proprietary" }
  },
  "externalDocs": {
    "description": "Full documentation",
    "url": "https://docs.heycmo.ai/"
  },
  "servers": [
    { "url": "https://heycmo.ai", "description": "Production" }
  ],
  "security": [{ "bearerApiKey": [] }],
  "tags": [
    { "name": "Health", "description": "Liveness + readiness probes." },
    { "name": "Customer", "description": "Customer account operations." },
    { "name": "Content", "description": "Approval queue, drafts, published content." },
    { "name": "Workflows", "description": "Workflow runs and configuration." },
    { "name": "Social", "description": "Social-platform connections + publishing." },
    { "name": "Analytics", "description": "Revenue attribution and platform analytics." },
    { "name": "Settings", "description": "Autonomy + budget configuration." },
    { "name": "Scan", "description": "SEO + GEO scanner for any URL." },
    { "name": "Chat", "description": "Conversational interface to the CMO agent." },
    { "name": "Webhooks", "description": "Webhook subscription management." },
    { "name": "Onboarding", "description": "Brand onboarding flows." },
    { "name": "Billing", "description": "Stripe checkout + session resolution." },
    { "name": "Public", "description": "Unauthenticated public surfaces (status, agent card)." }
  ],
  "paths": {
    "/api/health": {
      "get": {
        "tags": ["Health"],
        "operationId": "getHealth",
        "summary": "Liveness probe",
        "description": "Returns 200 if the server process is running. No authentication required. Used by uptime monitors and Fly health checks.",
        "security": [],
        "responses": {
          "200": {
            "description": "OK",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Health" }
              }
            }
          }
        }
      }
    },
    "/api/health/ready": {
      "get": {
        "tags": ["Health"],
        "operationId": "getHealthReady",
        "summary": "Readiness probe",
        "description": "Checks DB connectivity. Returns 503 if the database is unreachable. Detailed component status only exposed with `X-Admin-Secret`.",
        "security": [],
        "responses": {
          "200": { "description": "Ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthReady" } } } },
          "503": { "description": "Not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthReady" } } } }
        }
      }
    },
    "/api/customer/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Customer"],
        "operationId": "getCustomer",
        "summary": "Get customer account",
        "description": "Returns the authenticated customer's account info: id, email, plan, status, brandName, MCP endpoint URL.",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Customer" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/customer/{customerId}/rotate-key": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Customer"],
        "operationId": "rotateApiKey",
        "summary": "Rotate the customer API key",
        "description": "Generates a new API key, revokes the old one, returns the new key once (cannot be retrieved again).",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } }
        },
        "responses": {
          "200": { "description": "Key rotated", "content": { "application/json": { "schema": { "type": "object", "properties": { "apiKey": { "type": "string", "example": "hcmo_live_..." } }, "required": ["apiKey"] } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/events/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Customer"],
        "operationId": "listEvents",
        "summary": "Customer event log",
        "description": "Returns the customer's recent event log (workflow runs, publishes, approvals, settings changes).",
        "parameters": [
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 200, "default": 50 } },
          { "name": "since", "in": "query", "schema": { "type": "string", "format": "date-time" } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/Event" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/content/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Content"],
        "operationId": "listContent",
        "summary": "List content pieces",
        "description": "List drafts, approved, and published content for the customer. Filter by status, type, platform.",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["draft", "pending_approval", "approved", "published", "rejected"] } },
          { "name": "type", "in": "query", "schema": { "type": "string", "enum": ["blog", "social", "email", "ad", "outreach"] } },
          { "name": "platform", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } },
          { "name": "cursor", "in": "query", "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "content": { "type": "array", "items": { "$ref": "#/components/schemas/ContentPiece" } }, "nextCursor": { "type": "string", "nullable": true } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/content/{customerId}/{contentId}": {
      "parameters": [
        { "$ref": "#/components/parameters/customerId" },
        { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "get": {
        "tags": ["Content"],
        "operationId": "getContent",
        "summary": "Get a content piece",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPiece" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      },
      "put": {
        "tags": ["Content"],
        "operationId": "updateContent",
        "summary": "Edit a content piece",
        "description": "Editor-role required.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "properties": { "title": { "type": "string" }, "body": { "type": "string" }, "metadata": { "type": "object" } }, "additionalProperties": false } } }
        },
        "responses": {
          "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPiece" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/content/{customerId}/{contentId}/review": {
      "parameters": [
        { "$ref": "#/components/parameters/customerId" },
        { "name": "contentId", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "post": {
        "tags": ["Content"],
        "operationId": "reviewContent",
        "summary": "Approve or reject a content piece",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["action"], "properties": { "action": { "type": "string", "enum": ["approve", "reject"] }, "note": { "type": "string", "maxLength": 1000 } } } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPiece" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/workflows/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Workflows"],
        "operationId": "listWorkflows",
        "summary": "List workflow configurations",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "workflows": { "type": "array", "items": { "$ref": "#/components/schemas/Workflow" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/workflows/{customerId}/{workflowId}": {
      "parameters": [
        { "$ref": "#/components/parameters/customerId" },
        { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "put": {
        "tags": ["Workflows"],
        "operationId": "updateWorkflow",
        "summary": "Update a workflow configuration",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/workflows/{customerId}/{workflowId}/toggle": {
      "parameters": [
        { "$ref": "#/components/parameters/customerId" },
        { "name": "workflowId", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "post": {
        "tags": ["Workflows"],
        "operationId": "toggleWorkflow",
        "summary": "Enable or disable a workflow",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["enabled"], "properties": { "enabled": { "type": "boolean" } } } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Workflow" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/runs/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Workflows"],
        "operationId": "listRuns",
        "summary": "List recent workflow runs",
        "parameters": [
          { "name": "workflow", "in": "query", "schema": { "type": "string" } },
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["pending", "running", "suspended", "succeeded", "failed"] } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "minimum": 1, "maximum": 100, "default": 25 } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "runs": { "type": "array", "items": { "$ref": "#/components/schemas/WorkflowRun" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/social/connections/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Social"],
        "operationId": "listSocialConnections",
        "summary": "List connected social platforms",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "connections": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/SocialConnection" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/social/publish/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Social"],
        "operationId": "publishToSocial",
        "summary": "Publish or schedule a social post",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["platform", "body"], "properties": { "platform": { "type": "string", "enum": ["x", "linkedin", "instagram", "facebook", "tiktok", "pinterest"] }, "body": { "type": "string" }, "media": { "type": "array", "items": { "type": "string", "format": "uri" } }, "scheduledAt": { "type": "string", "format": "date-time" } } } } }
        },
        "responses": {
          "200": { "description": "Queued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ContentPiece" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "403": { "$ref": "#/components/responses/Forbidden" }
        }
      }
    },
    "/api/analytics/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Analytics"],
        "operationId": "getAnalytics",
        "summary": "Get analytics overview",
        "parameters": [
          { "name": "period", "in": "query", "schema": { "type": "string", "enum": ["last_7_days", "last_30_days", "last_90_days"], "default": "last_7_days" } }
        ],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AnalyticsReport" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/scan/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Scan"],
        "operationId": "createScan",
        "summary": "Run an SEO + GEO scan on a URL",
        "description": "Inline scan typically completes in 5–15 seconds. Returns the full report on success.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri", "maxLength": 2048 } } } } }
        },
        "responses": {
          "200": { "description": "Scan complete", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "429": { "$ref": "#/components/responses/RateLimited" },
          "500": { "$ref": "#/components/responses/ServerError" }
        }
      },
      "get": {
        "tags": ["Scan"],
        "operationId": "listScans",
        "summary": "List recent scans",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "scans": { "type": "array", "items": { "$ref": "#/components/schemas/ScanResult" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/scan/{customerId}/{scanId}": {
      "parameters": [
        { "$ref": "#/components/parameters/customerId" },
        { "name": "scanId", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "get": {
        "tags": ["Scan"],
        "operationId": "getScan",
        "summary": "Get a scan report",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ScanResult" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" },
          "404": { "$ref": "#/components/responses/NotFound" }
        }
      }
    },
    "/api/chat/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Chat"],
        "operationId": "sendChatMessage",
        "summary": "Send a message to the CMO agent",
        "description": "Streams a response. Connect a thread by passing `threadId` from a previous response.",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["message"], "properties": { "message": { "type": "string", "minLength": 1, "maxLength": 10000 }, "threadId": { "type": "string", "maxLength": 200 } } } } }
        },
        "responses": {
          "200": {
            "description": "Stream of chat events (SSE)",
            "content": {
              "text/event-stream": { "schema": { "type": "string" } }
            }
          },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/chat/{customerId}/threads": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Chat"],
        "operationId": "listChatThreads",
        "summary": "List chat threads",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "threads": { "type": "array", "items": { "type": "object" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/hooks/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Webhooks"],
        "operationId": "listWebhooks",
        "summary": "List webhook subscriptions",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "hooks": { "type": "array", "items": { "$ref": "#/components/schemas/Webhook" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      },
      "post": {
        "tags": ["Webhooks"],
        "operationId": "createWebhook",
        "summary": "Create a webhook subscription",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookCreate" } } }
        },
        "responses": {
          "200": { "description": "Created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Webhook" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/hooks/{customerId}/{webhookId}": {
      "parameters": [
        { "$ref": "#/components/parameters/customerId" },
        { "name": "webhookId", "in": "path", "required": true, "schema": { "type": "string" } }
      ],
      "delete": {
        "tags": ["Webhooks"],
        "operationId": "deleteWebhook",
        "summary": "Delete a webhook subscription",
        "responses": {
          "200": { "description": "Deleted", "content": { "application/json": { "schema": { "type": "object", "properties": { "deleted": { "type": "boolean" } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/settings/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Settings"],
        "operationId": "getSettings",
        "summary": "Get customer settings",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Settings" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/settings/{customerId}/autonomy": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "put": {
        "tags": ["Settings"],
        "operationId": "updateAutonomy",
        "summary": "Update per-skill autonomy levels (L1–L5)",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AutonomyUpdate" } } }
        },
        "responses": {
          "200": { "description": "OK" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/settings/{customerId}/budget": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "put": {
        "tags": ["Settings"],
        "operationId": "updateBudget",
        "summary": "Update budget caps",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BudgetUpdate" } } }
        },
        "responses": {
          "200": { "description": "OK" },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/onboard/{customerId}/auto-extract": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Onboarding"],
        "operationId": "onboardAutoExtract",
        "summary": "Extract brand profile from a URL",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["url"], "properties": { "url": { "type": "string", "format": "uri" } } } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/onboard/{customerId}/confirm-profile": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Onboarding"],
        "operationId": "onboardConfirmProfile",
        "summary": "Confirm an extracted brand profile",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/connections/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "get": {
        "tags": ["Onboarding"],
        "operationId": "getConnections",
        "summary": "List Composio platform connections",
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string" }, "connections": { "type": "object", "additionalProperties": { "type": "object" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/connect/{customerId}": {
      "parameters": [{ "$ref": "#/components/parameters/customerId" }],
      "post": {
        "tags": ["Onboarding"],
        "operationId": "generateConnectLinks",
        "summary": "Generate Composio OAuth connection links",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "connectLinks": { "type": "object", "additionalProperties": { "type": "string", "format": "uri" } } } } } } },
          "401": { "$ref": "#/components/responses/Unauthorized" }
        }
      }
    },
    "/api/checkout": {
      "post": {
        "tags": ["Billing"],
        "operationId": "createCheckoutSession",
        "summary": "Create a Stripe checkout session",
        "description": "No authentication required (uses email from body). Returns a Stripe-hosted checkout URL.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "type": "object", "required": ["email"], "properties": { "email": { "type": "string", "format": "email" } } } } }
        },
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "url": { "type": "string", "format": "uri" } } } } } },
          "429": { "$ref": "#/components/responses/RateLimited" }
        }
      }
    },
    "/api/session/{sessionId}": {
      "parameters": [{ "name": "sessionId", "in": "path", "required": true, "schema": { "type": "string" } }],
      "get": {
        "tags": ["Billing"],
        "operationId": "getCheckoutSession",
        "summary": "Resolve a Stripe checkout session",
        "description": "After successful checkout, exchange the Stripe session ID for the customer's API key + MCP endpoint.",
        "security": [],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "customerId": { "type": "string" }, "email": { "type": "string", "format": "email" }, "apiKey": { "type": "string" }, "mcpEndpoint": { "type": "string", "format": "uri" } } } } } }
        }
      }
    },
    "/api/public/status": {
      "get": {
        "tags": ["Public"],
        "operationId": "getPublicStatus",
        "summary": "Public status snapshot",
        "description": "Live readiness + recent uptime. No authentication required.",
        "security": [],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicStatus" } } } }
        }
      }
    },
    "/api/public/agent-card": {
      "get": {
        "tags": ["Public"],
        "operationId": "getPublicAgentCard",
        "summary": "Live MCP agent card",
        "description": "Always reflects the current MCP tool registry. Mirror of /.well-known/mcp/server-card.json.",
        "security": [],
        "responses": {
          "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object" } } } }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerApiKey": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "hcmo_live_*",
        "description": "API key as bearer token. Format: `hcmo_live_<64 hex chars>`. Obtain via https://heycmo.ai/signin (self-serve)."
      }
    },
    "parameters": {
      "customerId": {
        "name": "customerId",
        "in": "path",
        "required": true,
        "schema": { "type": "string", "format": "uuid" },
        "description": "The customer (tenant) UUID."
      }
    },
    "responses": {
      "Unauthorized": {
        "description": "Authentication required or invalid.",
        "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "Forbidden": {
        "description": "Authenticated but not allowed (suspended account, missing role).",
        "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "NotFound": {
        "description": "Resource not found.",
        "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "RateLimited": {
        "description": "Rate limit exceeded. Includes `Retry-After` (seconds).",
        "headers": {
          "Retry-After": { "schema": { "type": "integer", "minimum": 1 }, "description": "Seconds to wait before retrying." },
          "X-Request-ID": { "$ref": "#/components/headers/RequestId" }
        },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      },
      "ServerError": {
        "description": "Internal server error. Quote `requestId` when contacting support.",
        "headers": { "X-Request-ID": { "$ref": "#/components/headers/RequestId" } },
        "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }
      }
    },
    "headers": {
      "RequestId": { "schema": { "type": "string" }, "description": "Unique per-request identifier; quote in support requests." }
    },
    "schemas": {
      "Health": {
        "type": "object",
        "required": ["service", "status", "timestamp"],
        "properties": {
          "service": { "type": "string", "example": "heycmo-infra" },
          "status": { "type": "string", "enum": ["ok"] },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "HealthReady": {
        "type": "object",
        "required": ["service", "status", "timestamp"],
        "properties": {
          "service": { "type": "string" },
          "status": { "type": "string", "enum": ["ok", "degraded"] },
          "timestamp": { "type": "string", "format": "date-time" }
        }
      },
      "Customer": {
        "type": "object",
        "required": ["id", "email", "plan", "status"],
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "plan": { "type": "string", "enum": ["pro"] },
          "status": { "type": "string", "enum": ["onboarding", "active", "suspended", "cancelled"] },
          "brandName": { "type": "string", "nullable": true },
          "mcpEndpoint": { "type": "string", "format": "uri" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Event": {
        "type": "object",
        "required": ["type", "timestamp"],
        "properties": {
          "type": { "type": "string" },
          "timestamp": { "type": "string", "format": "date-time" },
          "data": { "type": "object", "additionalProperties": true }
        }
      },
      "ContentPiece": {
        "type": "object",
        "required": ["id", "type", "status"],
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string", "enum": ["blog", "social", "email", "ad", "outreach"] },
          "status": { "type": "string", "enum": ["draft", "pending_approval", "approved", "published", "rejected"] },
          "platform": { "type": "string", "nullable": true },
          "title": { "type": "string", "nullable": true },
          "body": { "type": "string", "nullable": true },
          "publishedUrl": { "type": "string", "format": "uri", "nullable": true },
          "publishedAt": { "type": "string", "format": "date-time", "nullable": true },
          "agentId": { "type": "string", "nullable": true },
          "runId": { "type": "string", "nullable": true },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "Workflow": {
        "type": "object",
        "required": ["id", "name", "enabled"],
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "description": { "type": "string" },
          "enabled": { "type": "boolean" },
          "schedule": { "type": "string", "nullable": true, "description": "Cron expression, if scheduled." }
        }
      },
      "WorkflowRun": {
        "type": "object",
        "required": ["runId", "workflow", "status"],
        "properties": {
          "runId": { "type": "string" },
          "workflow": { "type": "string" },
          "status": { "type": "string", "enum": ["pending", "running", "suspended", "succeeded", "failed"] },
          "startedAt": { "type": "string", "format": "date-time" },
          "completedAt": { "type": "string", "format": "date-time", "nullable": true },
          "error": { "type": "string", "nullable": true }
        }
      },
      "SocialConnection": {
        "type": "object",
        "properties": {
          "connected": { "type": "boolean" },
          "accountName": { "type": "string", "nullable": true },
          "connectedAt": { "type": "string", "format": "date-time", "nullable": true }
        }
      },
      "AnalyticsReport": {
        "type": "object",
        "properties": {
          "period": { "type": "string" },
          "channels": { "type": "object", "additionalProperties": { "type": "object" } },
          "totals": { "type": "object", "additionalProperties": { "type": "number" } }
        }
      },
      "ScanResult": {
        "type": "object",
        "required": ["scanId", "status"],
        "properties": {
          "scanId": { "type": "string" },
          "status": { "type": "string", "enum": ["running", "done", "failed"] },
          "url": { "type": "string", "format": "uri" },
          "seoScore": { "type": "number", "nullable": true },
          "geoScore": { "type": "number", "nullable": true },
          "croScore": { "type": "number", "nullable": true },
          "citabilityGrade": { "type": "string", "nullable": true },
          "checklist": { "type": "array", "items": { "type": "object" } },
          "llmsTxt": { "type": "string", "nullable": true },
          "screenshotUrl": { "type": "string", "format": "uri", "nullable": true }
        }
      },
      "Webhook": {
        "type": "object",
        "required": ["id", "url", "events"],
        "properties": {
          "id": { "type": "string" },
          "url": { "type": "string", "format": "uri" },
          "events": { "type": "array", "items": { "type": "string" } },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      },
      "WebhookCreate": {
        "type": "object",
        "required": ["url", "events"],
        "properties": {
          "url": { "type": "string", "format": "uri", "maxLength": 2048 },
          "events": {
            "type": "array",
            "minItems": 1,
            "maxItems": 20,
            "items": {
              "type": "string",
              "enum": [
                "content.created",
                "content.approved",
                "content.published",
                "content.rejected",
                "workflow.completed",
                "team.invited"
              ]
            }
          }
        }
      },
      "Settings": {
        "type": "object",
        "properties": {
          "autonomy": { "$ref": "#/components/schemas/AutonomyUpdate" },
          "budget": { "$ref": "#/components/schemas/BudgetUpdate" }
        }
      },
      "AutonomyUpdate": {
        "type": "object",
        "properties": {
          "globalDefault": { "type": "integer", "minimum": 1, "maximum": 5 },
          "categories": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 5 } },
          "skills": { "type": "object", "additionalProperties": { "type": "integer", "minimum": 1, "maximum": 5 } }
        }
      },
      "BudgetUpdate": {
        "type": "object",
        "properties": {
          "daily": { "type": "number", "minimum": 0 },
          "weekly": { "type": "number", "minimum": 0 },
          "monthly": { "type": "number", "minimum": 0 },
          "channels": { "type": "object", "additionalProperties": { "type": "number", "minimum": 0 } }
        }
      },
      "PublicStatus": {
        "type": "object",
        "required": ["status", "timestamp"],
        "properties": {
          "status": { "type": "string", "enum": ["ok", "degraded", "down"] },
          "timestamp": { "type": "string", "format": "date-time" },
          "uptime24h": { "type": "number", "minimum": 0, "maximum": 1, "description": "Fraction of successful readiness probes in the past 24 hours." },
          "uptime7d": { "type": "number", "minimum": 0, "maximum": 1, "nullable": true },
          "incidents": { "type": "array", "items": { "type": "object" } }
        }
      },
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" },
          "code": { "type": "string", "nullable": true, "description": "Machine-readable error code, e.g. `E_RATE_LIMITED`." },
          "requestId": { "type": "string", "nullable": true }
        }
      }
    }
  }
}