{
  "openapi": "3.1.0",
  "info": {
    "title": "PostAll API",
    "description": "Post to 35+ social media platforms from one API. Create, schedule, and publish posts to Instagram, X/Twitter, LinkedIn, TikTok, YouTube, Facebook, and more.",
    "version": "1.0.0"
  },
  "servers": [
    { "url": "https://postall.io" }
  ],
  "paths": {
    "/api/platforms": {
      "get": {
        "operationId": "getConnectedPlatforms",
        "summary": "List connected platforms",
        "description": "Returns all social media platforms connected to the user's PostAll account.",
        "responses": {
          "200": {
            "description": "List of connected platforms",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "platforms": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": { "type": "string" },
                          "platform": { "type": "string", "description": "Platform type e.g. INSTAGRAM, TWITTER, LINKEDIN" },
                          "platformName": { "type": "string", "description": "Account username/name" },
                          "isActive": { "type": "boolean" }
                        }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/posts": {
      "get": {
        "operationId": "listPosts",
        "summary": "List posts",
        "description": "Get user's posts with optional filters.",
        "parameters": [
          { "name": "status", "in": "query", "schema": { "type": "string", "enum": ["DRAFT", "SCHEDULED", "PUBLISHED", "FAILED"] } },
          { "name": "page", "in": "query", "schema": { "type": "integer", "default": 1 } },
          { "name": "limit", "in": "query", "schema": { "type": "integer", "default": 20, "maximum": 50 } }
        ],
        "responses": {
          "200": {
            "description": "Paginated list of posts",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "posts": { "type": "array", "items": { "$ref": "#/components/schemas/Post" } },
                    "pagination": {
                      "type": "object",
                      "properties": {
                        "page": { "type": "integer" },
                        "limit": { "type": "integer" },
                        "total": { "type": "integer" },
                        "pages": { "type": "integer" }
                      }
                    }
                  }
                }
              }
            }
          }
        }
      },
      "post": {
        "operationId": "createPost",
        "summary": "Create a new post",
        "description": "Create a post and optionally schedule it. Use platform names like INSTAGRAM, TWITTER, LINKEDIN, FACEBOOK, TIKTOK, YOUTUBE, PINTEREST, THREADS, REDDIT, WHATSAPP, TELEGRAM, DISCORD, BLUESKY, MASTODON, etc.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["content", "platforms"],
                "properties": {
                  "content": { "type": "string", "description": "Post text content" },
                  "title": { "type": "string", "description": "Optional title (for blog platforms)" },
                  "platforms": {
                    "type": "array",
                    "items": { "type": "string" },
                    "description": "Array of platform names: INSTAGRAM, TWITTER, LINKEDIN, FACEBOOK, TIKTOK, YOUTUBE, PINTEREST, THREADS, REDDIT, WHATSAPP, TELEGRAM, DISCORD, BLUESKY, MASTODON, TUMBLR, VK, SLACK, WORDPRESS, MEDIUM, HASHNODE, DEVTO, BLOGGER, GHOST, VIMEO, DRIBBBLE, TWITCH, WARPCAST, LEMMY, MEWE, NOSTR, LISTMONK, WHOP, SKOOL, KICK"
                  },
                  "mediaUrls": { "type": "array", "items": { "type": "string" }, "description": "Optional media URLs" },
                  "mediaType": { "type": "string", "enum": ["TEXT", "IMAGE", "VIDEO", "CAROUSEL"], "default": "TEXT" },
                  "scheduledAt": { "type": "string", "format": "date-time", "description": "ISO datetime to schedule. Omit for draft." },
                  "status": { "type": "string", "enum": ["DRAFT", "SCHEDULED"], "default": "DRAFT" }
                }
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "Post created",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "post": { "$ref": "#/components/schemas/Post" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/posts/{id}/publish": {
      "post": {
        "operationId": "publishPost",
        "summary": "Publish a post",
        "description": "Immediately publish a draft post to all selected platforms.",
        "parameters": [
          { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } }
        ],
        "responses": {
          "200": {
            "description": "Post publishing started",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "message": { "type": "string" },
                    "platforms": { "type": "array", "items": { "type": "string" } },
                    "dailyUsed": { "type": "integer" },
                    "dailyLimit": { "type": "integer" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/ai/generate": {
      "post": {
        "operationId": "generateContent",
        "summary": "AI generate content",
        "description": "Use PostAll's AI to generate captions, hashtags, or rewrite content.",
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "required": ["prompt"],
                "properties": {
                  "prompt": { "type": "string", "description": "What to generate" },
                  "type": { "type": "string", "enum": ["caption", "hashtags", "rewrite", "translate"], "default": "caption" },
                  "language": { "type": "string", "description": "Target language for translate" }
                }
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Generated content",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "result": { "type": "string" }
                  }
                }
              }
            }
          }
        }
      }
    },
    "/api/insights/all": {
      "get": {
        "operationId": "getAllInsights",
        "summary": "Get analytics for all platforms",
        "description": "Returns combined analytics/insights across all connected platforms.",
        "responses": {
          "200": {
            "description": "Analytics data"
          }
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Post": {
        "type": "object",
        "properties": {
          "id": { "type": "string" },
          "content": { "type": "string" },
          "title": { "type": "string" },
          "platforms": { "type": "array", "items": { "type": "string" } },
          "mediaUrls": { "type": "array", "items": { "type": "string" } },
          "mediaType": { "type": "string" },
          "status": { "type": "string", "enum": ["DRAFT", "SCHEDULED", "PUBLISHING", "PUBLISHED", "FAILED"] },
          "scheduledAt": { "type": "string", "format": "date-time" },
          "createdAt": { "type": "string", "format": "date-time" }
        }
      }
    },
    "securitySchemes": {
      "bearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "description": "PostAll API key (starts with pa_). Get it from Dashboard → Settings → API."
      }
    }
  },
  "security": [{ "bearerAuth": [] }]
}