{
  "openapi": "3.1.0",
  "info": {
    "title": "Crutan Public API",
    "version": "1.0.0",
    "description": "Workspace-scoped REST API for prospects, page generation, analytics, leads, and webhook connectors."
  },
  "servers": [{ "url": "https://app.crutan.com" }],
  "components": {
    "securitySchemes": {
      "ApiKey": { "type": "http", "scheme": "bearer", "description": "Workspace API key prefixed with crt_" }
    },
    "schemas": {
      "Prospect": {
        "type": "object",
        "properties": {
          "id": { "type": "string", "format": "uuid" },
          "email": { "type": "string", "format": "email" },
          "first_name": { "type": ["string", "null"] },
          "last_name": { "type": ["string", "null"] },
          "company_name": { "type": ["string", "null"] },
          "company_domain": { "type": ["string", "null"] },
          "role_title": { "type": ["string", "null"] },
          "linkedin_url": { "type": ["string", "null"] },
          "tags": { "type": "array", "items": { "type": "string" } },
          "custom_fields": { "type": "object", "additionalProperties": true },
          "external_ids": { "type": "object", "additionalProperties": { "type": "string" } },
          "status": { "type": "string" }
        },
        "required": ["email"]
      },
      "BatchCreate": {
        "type": "object",
        "properties": {
          "templateId": { "type": "string", "format": "uuid" },
          "prospectIds": { "type": "array", "items": { "type": "string", "format": "uuid" } },
          "batchName": { "type": "string" }
        },
        "required": ["templateId"]
      },
      "WebhookEvent": {
        "type": "object",
        "properties": {
          "event": { "type": "string" },
          "workspace_id": { "type": "string", "format": "uuid" },
          "crutan_lead_id": { "type": "string", "format": "uuid" },
          "url": { "type": ["string", "null"] },
          "timestamp": { "type": "string", "format": "date-time" },
          "form_data": { "type": ["object", "null"], "additionalProperties": true },
          "booking": { "type": ["object", "null"], "additionalProperties": true }
        }
      }
    }
  },
  "security": [{ "ApiKey": [] }],
  "paths": {
    "/api/v1/prospects": {
      "get": {
        "summary": "List prospects",
        "responses": { "200": { "description": "Prospects" }, "401": { "description": "Unauthorized" }, "402": { "description": "Plan limit" }, "403": { "description": "Missing scope" } }
      },
      "post": {
        "summary": "Create or upsert prospects",
        "parameters": [{ "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } }],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  { "$ref": "#/components/schemas/Prospect" },
                  { "type": "array", "items": { "$ref": "#/components/schemas/Prospect" } },
                  { "type": "object", "properties": { "prospects": { "type": "array", "items": { "$ref": "#/components/schemas/Prospect" } } } }
                ]
              }
            }
          }
        },
        "responses": { "200": { "description": "Upserted prospects" } }
      }
    },
    "/api/v1/prospects/{id}": {
      "get": {
        "summary": "Get a prospect with page status",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Prospect" }, "404": { "description": "Not found" } }
      }
    },
    "/api/v1/batches": {
      "post": {
        "summary": "Create a page generation batch",
        "requestBody": {
          "required": true,
          "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCreate" } } }
        },
        "responses": { "200": { "description": "Batch created" } }
      }
    },
    "/api/v1/batches/{id}/generate": {
      "post": {
        "summary": "Queue or run page generation for a batch",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "acknowledgedEstimateCents": { "type": "integer", "description": "Required for API-key calls; pass estimate_cost result." },
                  "forceSync": { "type": "boolean" },
                  "prospectIds": { "type": "array", "items": { "type": "string", "format": "uuid" } }
                }
              }
            }
          }
        },
        "responses": { "200": { "description": "Generation queued or completed" }, "402": { "description": "Insufficient credits or spend cap" } }
      }
    },
    "/api/v1/analytics": {
      "get": {
        "summary": "Core conversion and high-intent analytics",
        "responses": { "200": { "description": "Analytics metrics" } }
      }
    },
    "/api/v1/leads": {
      "get": {
        "summary": "List lead submissions",
        "responses": { "200": { "description": "Lead submissions" } }
      }
    },
    "/api/v1/events": {
      "get": {
        "summary": "Cursor-paginated conversion events",
        "parameters": [
          { "name": "cursor", "in": "query", "schema": { "type": "string" } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "maximum": 250 } }
        ],
        "responses": { "200": { "description": "Events page" } }
      }
    },
    "/api/v1/pages/{id}": {
      "get": {
        "summary": "Get rendered page status and URL",
        "parameters": [{ "name": "id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid" } }],
        "responses": { "200": { "description": "Page" }, "404": { "description": "Not found" } }
      }
    },
    "/api/v1/connectors": {
      "post": {
        "summary": "Register an outbound webhook connector",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "outboundUrl": { "type": "string", "format": "uri" },
                  "events": { "type": "array", "items": { "type": "string" } },
                  "provider": { "type": "string" }
                },
                "required": ["outboundUrl"]
              }
            }
          }
        },
        "responses": { "200": { "description": "Connector and reveal-once secret" } }
      }
    }
  },
  "webhooks": {
    "form.submitted": {
      "post": {
        "summary": "Lead form submission",
        "parameters": [{ "name": "X-Crutan-Signature", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Your endpoint acknowledges delivery" } }
      }
    },
    "meeting.booked": {
      "post": {
        "summary": "Confirmed meeting booking",
        "parameters": [{ "name": "X-Crutan-Signature", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Acknowledged" } }
      }
    },
    "page.rendered": {
      "post": {
        "summary": "Personalized page rendered",
        "parameters": [{ "name": "X-Crutan-Signature", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Acknowledged" } }
      }
    },
    "lead.intent": {
      "post": {
        "summary": "High-intent CTA or engagement signal",
        "parameters": [{ "name": "X-Crutan-Signature", "in": "header", "required": true, "schema": { "type": "string" } }],
        "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WebhookEvent" } } } },
        "responses": { "200": { "description": "Acknowledged" } }
      }
    }
  }
}