{
  "openapi": "3.1.0",
  "info": {
    "title": "Honkpost Agent & Publishing API",
    "version": "1.0.0",
    "description": "API specification for Honkpost social media scheduling, programmatic publishing, and Model Context Protocol (MCP) server. Live publishing: X (Twitter), Bluesky, Threads. Limited: Instagram (registered Meta app testers). Roadmap: TikTok, LinkedIn, YouTube, Facebook, and 20+ additional channels."
  },
  "servers": [
    {
      "url": "https://honkpost.com",
      "description": "Production Server"
    }
  ],
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "Provide Honkpost API key (e.g. Bearer honk_live_...)"
      },
      "ApiKeyAuth": {
        "type": "apiKey",
        "in": "header",
        "name": "x-api-key",
        "description": "Provide Honkpost API key via x-api-key header"
      }
    }
  },
  "security": [
    { "BearerAuth": [] },
    { "ApiKeyAuth": [] }
  ],
  "paths": {
    "/api/mcp": {
      "get": {
        "summary": "MCP Server Discovery",
        "description": "Get MCP server metadata and tool definitions.",
        "responses": {
          "200": { "description": "MCP server info and tool schemas" }
        }
      },
      "post": {
        "summary": "MCP Tool Invocation",
        "description": "Invoke MCP tools via JSON-RPC 2.0 (tools/call) or direct REST format ({ tool, args }). Tools: list_channels, upload_media, create_post, publish_now, list_scheduled, cancel_post.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tool": { "type": "string", "enum": ["list_channels", "upload_media", "create_post", "publish_now", "list_scheduled", "cancel_post"] },
                  "args": { "type": "object" },
                  "jsonrpc": { "type": "string", "example": "2.0" },
                  "method": { "type": "string", "example": "tools/call" },
                  "params": { "type": "object" }
                }
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Tool execution result" },
          "401": { "description": "Unauthorized - Missing or invalid API key" },
          "429": { "description": "Too Many Requests - Rate limit exceeded" }
        }
      }
    },
    "/api/upload": {
      "post": {
        "summary": "Upload Media Asset",
        "description": "Upload an image or video asset for social post distribution. Supports both session cookies and API keys (Bearer / x-api-key). Accepts multipart/form-data or Vercel Blob client token handshake.",
        "requestBody": {
          "required": true,
          "content": {
            "multipart/form-data": {
              "schema": {
                "type": "object",
                "properties": {
                  "file": { "type": "string", "format": "binary" }
                },
                "required": ["file"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Upload result with public URL and metadata" },
          "400": { "description": "No file provided or empty file" },
          "401": { "description": "Unauthorized - Valid session cookie or API key required" }
        }
      }
    },
    "/api/posts": {
      "get": {
        "summary": "Get Scheduled Posts",
        "description": "Retrieve user's scheduled posts.",
        "responses": {
          "200": { "description": "List of user posts" },
          "401": { "description": "Unauthorized" }
        }
      },
      "post": {
        "summary": "Create Scheduled Post",
        "description": "Create a new scheduled post for the authenticated user.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "content": { "type": "string" },
                  "targetPlatforms": { "type": "array", "items": { "type": "string", "enum": ["x", "bluesky", "tiktok", "threads", "instagram"] } },
                  "scheduledFor": { "type": "string" },
                  "mediaUrls": { "type": "array", "items": { "type": "string" } },
                  "firstCommentPlug": { "type": "string" }
                },
                "required": ["content", "targetPlatforms", "scheduledFor"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Post scheduled successfully" },
          "401": { "description": "Unauthorized" }
        }
      }
    },
    "/api/posts/publish": {
      "post": {
        "summary": "Publish Scheduled Post Now",
        "description": "Publish a specific scheduled post immediately. Strict multi-tenant verification enforces that the caller owns the post.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "postId": { "type": "string" }
                },
                "required": ["postId"]
              }
            }
          }
        },
        "responses": {
          "200": { "description": "Publish execution result" },
          "401": { "description": "Unauthorized" },
          "403": { "description": "Access denied - caller does not own this post" },
          "404": { "description": "Post not found" }
        }
      }
    }
  }
}