{
  "openapi": "3.1.0",
  "info": {
    "title": "ChiefLab API",
    "version": "0.3.0",
    "description": "ChiefLab is the business execution layer for agent-built companies, starting with GTM. The primary entry point is `POST /api/mcp` (JSON-RPC 2.0, MCP 2024-11-05). REST endpoints below are the human-control surface: runs, assets, actions, approval, audit. For the live tool catalog, call `tools/list` against the MCP endpoint.",
    "contact": {
      "name": "ChiefLab",
      "url": "https://chieflab.io",
      "email": "hi@chieflab.io"
    }
  },
  "servers": [
    {
      "url": "https://api.chieflab.io",
      "description": "Vercel-direct primary endpoint"
    },
    {
      "url": "https://chieflab.io",
      "description": "Brand-domain fallback through Cloudflare Pages"
    }
  ],
  "security": [
    {
      "bearerAuth": []
    }
  ],
  "tags": [
    { "name": "MCP", "description": "Primary AI-agent entry point. JSON-RPC 2.0 over HTTP." },
    { "name": "Public", "description": "No-auth endpoints — sandbox launch, agent-first signup, health." },
    { "name": "Runs", "description": "Marketing runs and approval surface." },
    { "name": "GTM", "description": "P10 multi-agent GTM runs (eight specialized agents)." },
    { "name": "Connectors", "description": "Connector OAuth + snapshot read." },
    { "name": "Workspace", "description": "Workspace metadata, usage, audit." }
  ],
  "paths": {
    "/api/mcp": {
      "get": {
        "tags": ["MCP"],
        "summary": "Endpoint metadata (no auth)",
        "description": "Returns ChiefLab MCP endpoint metadata as JSON. Agent runtimes that probe for MCP servers see this and learn the JSON-RPC POST URL, primary tools, and trigger phrases. Mirrors the static manifest at /.well-known/mcp.json.",
        "security": [],
        "responses": {
          "200": {
            "description": "Endpoint metadata",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      },
      "post": {
        "tags": ["MCP"],
        "summary": "JSON-RPC 2.0 entry point — initialize, tools/list, tools/call",
        "description": "The primary surface AI agents call. Supports MCP `initialize`, `tools/list`, and `tools/call` methods. Bearer auth required for `tools/call` of authenticated tools; `tools/list` and the public-tool subset (e.g. `chieflab_signup_workspace`) work without a key.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["jsonrpc", "method"],
                "properties": {
                  "jsonrpc": { "type": "string", "enum": ["2.0"] },
                  "id": { "oneOf": [{ "type": "string" }, { "type": "number" }, { "type": "null" }] },
                  "method": {
                    "type": "string",
                    "enum": ["initialize", "tools/list", "tools/call"]
                  },
                  "params": { "type": "object" }
                }
              },
              "examples": {
                "tools_list": {
                  "summary": "List available tools",
                  "value": { "jsonrpc": "2.0", "id": 1, "method": "tools/list" }
                },
                "get_users_after_build": {
                  "summary": "Fire chieflab_get_users_after_build after an agent finishes building",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {
                      "name": "chieflab_get_users_after_build",
                      "arguments": {
                        "productUrl": "yoursite.com",
                        "goal": "Get our first 100 users",
                        "channels": ["x", "linkedin", "email"],
                        "repoContext": {
                          "whatChanged": "Just shipped scheduled posts",
                          "targetCustomer": "Solo creators batching content"
                        }
                      }
                    }
                  }
                },
                "gtm_run_start": {
                  "summary": "Fire P10 multi-agent GTM run",
                  "value": {
                    "jsonrpc": "2.0",
                    "id": 1,
                    "method": "tools/call",
                    "params": {
                      "name": "chiefmo_gtm_run_start",
                      "arguments": {
                        "goal": "Launch this product and get our first 100 users",
                        "productUrl": "yoursite.com"
                      }
                    }
                  }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "JSON-RPC response",
            "content": {
              "application/json": {
                "schema": { "type": "object" }
              }
            }
          }
        }
      }
    },
    "/api/sandbox/launch": {
      "post": {
        "tags": ["Public"],
        "summary": "Public no-auth try-it for chiefmo_launch_product",
        "description": "Same shape as calling chiefmo_launch_product via MCP, but auth-free for the Demo Console / homepage curl. Rate-limited per IP.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["productUrl"],
                "properties": {
                  "productUrl": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "launchPack + signed reviewUrl + postBuildChecklist"
          },
          "429": {
            "description": "Rate-limit exceeded"
          }
        }
      }
    },
    "/api/signup/initiate": {
      "post": {
        "tags": ["Public"],
        "summary": "Mint a workspace + delivery URL (agent-first signup)",
        "description": "Public, no-auth. Returns a deliveryUrl the agent surfaces to the user; the user clicks once to claim the workspace and reveal the API key. Rate-limited per IP.",
        "security": [],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "contactEmail": { "type": "string", "format": "email" },
                  "agentName": { "type": "string" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "deliveryUrl + workspaceId + mcpConfigSnippet"
          }
        }
      }
    },
    "/api/signup/deliver": {
      "get": {
        "tags": ["Public"],
        "summary": "Reveal the minted API key (one-time, signed token)",
        "security": [],
        "parameters": [
          { "name": "token", "in": "query", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "API key reveal page (HTML)" }
        }
      }
    },
    "/api/health": {
      "get": {
        "tags": ["Public"],
        "summary": "API health probe",
        "security": [],
        "responses": {
          "200": {
            "description": "API health status"
          }
        }
      }
    },
    "/api/me": {
      "get": {
        "tags": ["Workspace"],
        "summary": "Read current user and workspace context",
        "responses": {
          "200": {
            "description": "Authenticated user and workspace"
          }
        }
      }
    },
    "/api/runs": {
      "get": {
        "tags": ["Runs"],
        "summary": "List recent runs (workspace-scoped)",
        "responses": {
          "200": { "description": "Recent runs" }
        }
      }
    },
    "/api/runs/{id}": {
      "get": {
        "tags": ["Runs"],
        "summary": "Get a run with assets + actions",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Run details" }
        }
      }
    },
    "/api/runs/{id}/approve": {
      "post": {
        "tags": ["Runs"],
        "summary": "Approve a run (or a specific action via /api/actions/{id}/approve)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Approved" }
        }
      }
    },
    "/api/runs/{id}/reject": {
      "post": {
        "tags": ["Runs"],
        "summary": "Reject a run with optional feedback (feedback persists as per-tenant voice signal)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Rejected" }
        }
      }
    },
    "/api/actions": {
      "get": {
        "tags": ["Runs"],
        "summary": "List proposed actions across runs",
        "parameters": [
          { "name": "runId", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Proposed actions" }
        }
      }
    },
    "/api/actions/{id}/approve": {
      "post": {
        "tags": ["Runs"],
        "summary": "Approve a single action (transitions awaiting_approval → approved)",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Approved action" }
        }
      }
    },
    "/api/actions/{id}/reject": {
      "post": {
        "tags": ["Runs"],
        "summary": "Reject a single action with optional feedback",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Rejected action" }
        }
      }
    },
    "/api/actions/{id}/execute": {
      "post": {
        "tags": ["Runs"],
        "summary": "Execute an approved action (e.g. fire Zernio publish, Resend send)",
        "description": "Action must be in `approved` status. Returns the third-party platform artifact ID (Zernio postId, Resend messageId, etc.).",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Executed — returns platform artifact ID" }
        }
      }
    },
    "/api/assets": {
      "get": {
        "tags": ["Runs"],
        "summary": "List generated assets (creatives, briefs, images)",
        "parameters": [
          { "name": "runId", "in": "query", "required": false, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "Generated assets" }
        }
      }
    },
    "/api/workspace/gtm/runs": {
      "get": {
        "tags": ["GTM"],
        "summary": "List P10 multi-agent GTM runs (workspace-scoped, paginated)",
        "responses": {
          "200": { "description": "Recent GTM runs" }
        }
      }
    },
    "/api/workspace/gtm/runs/{id}": {
      "get": {
        "tags": ["GTM"],
        "summary": "Get a GTM run with full agent_runs + handoffs timeline",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": { "description": "GTM run + agentRuns + handoffs" }
        }
      }
    },
    "/api/connectors": {
      "get": {
        "tags": ["Connectors"],
        "summary": "List connector catalog with connection status",
        "description": "Live truth: GA4 + Search Console (real reads), Zernio + Resend (real approval-gated writes). Half-wired: HubSpot, Stripe billing portal. Mock-only catalog hidden from response.",
        "responses": {
          "200": { "description": "Connector catalog and connection status" }
        }
      }
    },
    "/api/connectors/{provider}/oauth/start": {
      "post": {
        "tags": ["Connectors"],
        "summary": "Start connector OAuth flow",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["google_search_console", "google_analytics", "hubspot", "zernio", "resend"]
            }
          }
        ],
        "responses": {
          "200": { "description": "OAuth authorization URL" }
        }
      }
    },
    "/api/connectors/{provider}/snapshot": {
      "post": {
        "tags": ["Connectors"],
        "summary": "Read a connector snapshot",
        "description": "Returns live evidence when the connector is connected. Write-capable connectors still require approval before external action.",
        "parameters": [
          {
            "name": "provider",
            "in": "path",
            "required": true,
            "schema": {
              "type": "string",
              "enum": ["google_search_console", "google_analytics", "hubspot"]
            }
          }
        ],
        "responses": {
          "200": { "description": "Connector snapshot or setup guidance" }
        }
      }
    },
    "/api/usage": {
      "get": {
        "tags": ["Workspace"],
        "summary": "Read usage and cost data (per-workspace meter ledger)",
        "responses": {
          "200": { "description": "Usage data" }
        }
      }
    },
    "/api/audit-logs": {
      "get": {
        "tags": ["Workspace"],
        "summary": "Read workspace audit logs",
        "responses": {
          "200": { "description": "Workspace audit logs" }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "ChiefLab API key in the form `clp_dev_<key>` or `clp_live_<key>`. Mint one at https://chieflab.io/get-key (no email required for sandbox keys) or via the public `chieflab_signup_workspace` MCP tool."
      }
    }
  },
  "externalDocs": {
    "description": "ChiefLab manifest for AI agents (.well-known/mcp.json + llms.txt)",
    "url": "https://chieflab.io/.well-known/mcp.json"
  }
}