{
  "openapi": "3.1.0",
  "info": {
    "title": "Autopilot Marketing API",
    "version": "1.0.0",
    "description": "Public REST API for Pro/Agency organizations. Authenticate with a Bearer API key (`apk_…`) created under Dashboard → Developers. The Zapier Partner app wraps the same POST actions."
  },
  "servers": [
    {
      "url": "/",
      "description": "Same origin as your Autopilot deployment"
    }
  ],
  "security": [{ "bearerAuth": [] }],
  "components": {
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "apk_",
        "description": "API key from Dashboard → Developers (Pro/Agency). Prefix is typically `apk_`."
      }
    },
    "schemas": {
      "Error": {
        "type": "object",
        "required": ["error"],
        "properties": {
          "error": { "type": "string" }
        }
      },
      "SocialPlatform": {
        "type": "string",
        "enum": ["INSTAGRAM", "FACEBOOK", "LINKEDIN", "TIKTOK", "X", "YOUTUBE"]
      },
      "EngagementType": {
        "type": "string",
        "enum": ["COMMENT", "DM", "MENTION"]
      },
      "LeadStatus": {
        "type": "string",
        "enum": ["NEW", "CONTACTED", "QUALIFIED", "CONVERTED", "LOST"]
      },
      "OrganizationSummary": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "name": { "type": "string" },
          "slug": { "type": "string" },
          "plan": { "type": "string", "enum": ["FREE", "PRO", "AGENCY"] },
          "creditBalance": { "type": "integer" }
        }
      },
      "Stats": {
        "type": "object",
        "properties": {
          "brands": { "type": "integer" },
          "posts": { "type": "integer" },
          "engagements": { "type": "integer" },
          "leads": { "type": "integer" }
        }
      },
      "PostAsset": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "type": { "type": "string" },
          "url": { "type": "string" },
          "prompt": { "type": ["string", "null"] }
        }
      },
      "Post": {
        "type": "object",
        "description": "Prisma Post row including assets (shape may include additional fields).",
        "properties": {
          "id": { "type": "string" },
          "organizationId": { "type": "string" },
          "brandId": { "type": "string" },
          "status": { "type": "string" },
          "caption": { "type": "string" },
          "scheduledAt": { "type": ["string", "null"], "format": "date-time" },
          "assets": {
            "type": "array",
            "items": { "$ref": "#/components/schemas/PostAsset" }
          }
        }
      },
      "Lead": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "brandId": { "type": "string" },
          "brandName": { "type": "string" },
          "engagementId": { "type": ["string", "null"] },
          "name": { "type": ["string", "null"] },
          "handle": { "type": ["string", "null"] },
          "platform": { "$ref": "#/components/schemas/SocialPlatform" },
          "source": { "type": ["string", "null"] },
          "status": { "$ref": "#/components/schemas/LeadStatus" },
          "notes": { "type": ["string", "null"] },
          "createdAt": { "type": "string", "format": "date-time" },
          "updatedAt": { "type": "string", "format": "date-time" }
        }
      },
      "CreatePostRequest": {
        "type": "object",
        "required": ["action", "brandId"],
        "properties": {
          "action": { "type": "string", "const": "create_post" },
          "brandId": { "type": "string" },
          "topic": { "type": "string" },
          "asVideo": { "type": "boolean", "default": false }
        }
      },
      "GenerateWeekRequest": {
        "type": "object",
        "required": ["action", "brandId"],
        "properties": {
          "action": { "type": "string", "const": "generate_week" },
          "brandId": { "type": "string" },
          "postsPerWeek": { "type": "integer", "minimum": 1 }
        }
      },
      "IngestEngagementRequest": {
        "type": "object",
        "required": ["action", "brandId", "content"],
        "properties": {
          "action": { "type": "string", "const": "ingest_engagement" },
          "brandId": { "type": "string" },
          "content": { "type": "string" },
          "type": { "$ref": "#/components/schemas/EngagementType" },
          "platform": { "$ref": "#/components/schemas/SocialPlatform" },
          "authorName": { "type": "string" },
          "authorHandle": { "type": "string" },
          "externalId": {
            "type": "string",
            "description": "Idempotency key with platform; duplicates return duplicate:true"
          },
          "processNow": {
            "type": "boolean",
            "default": true,
            "description": "When true, classify/reply immediately; when false, leave PENDING"
          }
        }
      },
      "ListLeadsRequest": {
        "type": "object",
        "required": ["action"],
        "properties": {
          "action": { "type": "string", "const": "list_leads" },
          "brandId": { "type": "string" },
          "status": { "$ref": "#/components/schemas/LeadStatus" },
          "limit": {
            "type": "integer",
            "minimum": 1,
            "maximum": 200,
            "default": 50
          },
          "cursor": {
            "type": "string",
            "description": "Lead id cursor from a previous nextCursor"
          }
        }
      },
      "V1ActionRequest": {
        "oneOf": [
          { "$ref": "#/components/schemas/CreatePostRequest" },
          { "$ref": "#/components/schemas/GenerateWeekRequest" },
          { "$ref": "#/components/schemas/IngestEngagementRequest" },
          { "$ref": "#/components/schemas/ListLeadsRequest" }
        ],
        "discriminator": {
          "propertyName": "action",
          "mapping": {
            "create_post": "#/components/schemas/CreatePostRequest",
            "generate_week": "#/components/schemas/GenerateWeekRequest",
            "ingest_engagement": "#/components/schemas/IngestEngagementRequest",
            "list_leads": "#/components/schemas/ListLeadsRequest"
          }
        }
      }
    }
  },
  "paths": {
    "/api/v1": {
      "get": {
        "operationId": "getOrgStats",
        "summary": "Organization summary and counts",
        "tags": ["v1"],
        "responses": {
          "200": {
            "description": "Authenticated org snapshot",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "required": ["organization", "stats"],
                  "properties": {
                    "organization": {
                      "$ref": "#/components/schemas/OrganizationSummary"
                    },
                    "stats": { "$ref": "#/components/schemas/Stats" }
                  }
                }
              }
            }
          },
          "401": {
            "description": "Missing/invalid key or plan without API access",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "v1Action",
        "summary": "Run a v1 action",
        "description": "Dispatch on JSON body `action`. Unknown actions return 400.",
        "tags": ["v1"],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": { "$ref": "#/components/schemas/V1ActionRequest" }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Action result (shape depends on action)",
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "type": "object",
                      "required": ["post"],
                      "properties": {
                        "post": { "$ref": "#/components/schemas/Post" }
                      }
                    },
                    {
                      "type": "object",
                      "required": ["postIds"],
                      "properties": {
                        "postIds": {
                          "type": "array",
                          "items": { "type": "string" }
                        }
                      }
                    },
                    {
                      "type": "object",
                      "required": ["engagementId", "duplicate"],
                      "properties": {
                        "engagementId": { "type": "string" },
                        "duplicate": { "type": "boolean" }
                      }
                    },
                    {
                      "type": "object",
                      "required": ["leads", "nextCursor"],
                      "properties": {
                        "leads": {
                          "type": "array",
                          "items": { "$ref": "#/components/schemas/Lead" }
                        },
                        "nextCursor": { "type": ["string", "null"] }
                      }
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "Unknown action or agent/business error",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          },
          "401": {
            "description": "Unauthorized",
            "content": {
              "application/json": {
                "schema": { "$ref": "#/components/schemas/Error" }
              }
            }
          }
        }
      }
    }
  }
}