{"openapi":"3.0.0","info":{"title":"NexPost API","version":"1.0.0","description":"API for generating social media content using artificial intelligence","contact":{"name":"NexPost Support","email":"support@nexpost.io"}},"servers":[{"url":"https://nexpost.io","description":"Production server"}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"apiKey","in":"header","name":"x-api-key","description":"API Key for authorization. You can find it in Settings → API Key section in your application."}},"schemas":{"GeneratePostRequest":{"type":"object","required":["contentType","topic"],"properties":{"contentType":{"type":"string","enum":["linkedin","twitter","instagram","facebook"],"description":"Social media platform type"},"topic":{"type":"string","description":"Post topic","example":"Artificial intelligence in marketing"},"description":{"type":"string","description":"Additional description or context for the post","example":"Write about the benefits of AI in marketing campaign automation"},"streaming":{"type":"boolean","default":false,"description":"Whether the response should be streamed (Server-Sent Events)"}}},"GenerateCustomPostRequest":{"type":"object","required":["contentType","imageBase64","imageMimeType"],"properties":{"contentType":{"type":"string","enum":["linkedin","twitter","instagram","facebook"],"description":"Social media platform type"},"imageBase64":{"type":"string","description":"Image in base64 format (complete data URI with prefix)","example":"data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg=="},"imageMimeType":{"type":"string","description":"Image MIME type","example":"image/jpeg"},"imageDescription":{"type":"string","description":"Optional image description","example":"Team photo during a meeting"},"streaming":{"type":"boolean","default":false,"description":"Whether the response should be streamed (Server-Sent Events)"}}},"GenerateTopicsRequest":{"type":"object","properties":{"limit":{"type":"integer","minimum":1,"maximum":30,"default":10,"description":"Number of topics to generate (1-30)","example":15},"description":{"type":"string","description":"Optional description of the topic area or niche","example":"remote work productivity tips"}}},"GenerateTopicsResponse":{"type":"array","items":{"type":"string"},"description":"Array of generated engaging topics","example":["The 5-minute rule that doubled my productivity","Why successful people wake up at 5 AM (it's not what you think)","I quit my 6-figure job to become a freelancer - here's what happened","The email template that gets 90% response rate","3 LinkedIn mistakes that are killing your personal brand"]},"GeneratePostResponse":{"type":"object","properties":{"success":{"type":"boolean","example":true},"content":{"type":"string","description":"Generated post content","example":"🚀 Artificial intelligence is revolutionizing marketing!\n\nToday AI helps us:\n✅ Personalize communication\n✅ Analyze customer behavior\n✅ Optimize campaigns in real-time\n\nHow do you use AI in your business? 💭\n\n#AI #Marketing #Innovation"},"contentType":{"type":"string","example":"linkedin"},"topic":{"type":"string","example":"Artificial intelligence in marketing"}}},"StreamingChunk":{"type":"object","properties":{"content":{"type":"string","description":"Part of the generated content"},"isComplete":{"type":"boolean","description":"Whether this is the last part of the response"},"error":{"type":"string","description":"Error message (if occurred)"}}},"ErrorResponse":{"type":"object","properties":{"statusCode":{"type":"integer","example":400},"statusMessage":{"type":"string","example":"Content type and topic are required"}}},"StatusResponse":{"type":"object","required":["status","message","timestamp","version","uptime"],"properties":{"status":{"type":"string","enum":["healthy","unhealthy","error"],"description":"Overall service health status"},"message":{"type":"string","description":"Human-readable status message"},"timestamp":{"type":"string","format":"date-time","description":"ISO timestamp when status was checked"},"version":{"type":"string","description":"API version"},"uptime":{"type":"integer","description":"Service uptime in seconds"},"responseTime":{"type":"integer","description":"Response time in milliseconds"},"services":{"type":"object","description":"Status of individual service components","properties":{"database":{"type":"string","enum":["connected","error"],"description":"Database connection status"},"ai_service":{"type":"string","enum":["operational","error","configuration_error"],"description":"AI service status"}}},"error":{"type":"string","description":"Error details (only present when status is error)"}}}}},"security":[{"ApiKeyAuth":[]}],"paths":{"/api/content/generate-custom-post":{"post":{"summary":"Generate post content based on image","description":"Generates post content for selected social media platform based on uploaded image analysis.\nAI analyzes the image and creates engaging content tailored to platform and user profile.\n\nEndpoint supports both standard responses and real-time streaming.\n","tags":["Content Generation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateCustomPostRequest"},"examples":{"instagram_image_post":{"summary":"Instagram Post with Image","value":{"contentType":"instagram","imageBase64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==","imageMimeType":"image/png","imageDescription":"Team photo during a meeting","streaming":false}},"linkedin_photo_post":{"summary":"LinkedIn Post with Photo","value":{"contentType":"linkedin","imageBase64":"iVBORw0KGgoAAAANSUhEUgAAAAEAAAABCAYAAAAfFcSJAAAADUlEQVR42mNk+M9QDwADhgGAWjR9awAAAABJRU5ErkJggg==","imageMimeType":"image/png","imageDescription":"Infographic showing sales results","streaming":true}}}}}},"responses":{"200":{"description":"Content generated successfully based on image","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePostResponse"}},"text/event-stream":{"schema":{"type":"string"},"description":"Streaming response (when streaming=true).\nEach line is JSON with StreamingChunk object.\nLast line contains '[DONE]' indicating end of stream.\n","example":"data: {\"content\": \"📸 Amazing moment\", \"isComplete\": false}\ndata: {\"content\": \" with our team!\", \"isComplete\": false}\ndata: {\"content\": \"\\n\\nIn the photo you can see...\", \"isComplete\": true}\ndata: [DONE]\n"}}},"400":{"description":"Invalid input data - missing required fields","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"statusCode":400,"statusMessage":"Content type, image base64 and image mime type are required"}}}},"401":{"description":"Missing authorization or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"statusCode":401,"statusMessage":"API key is required"}}}},"500":{"description":"Server error or image analysis issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"statusCode":500,"statusMessage":"Failed to generate custom post"}}}}}}},"/api/content/generate-post":{"post":{"summary":"Generate social media post content","description":"Generates post content for selected social media platform based on topic and description.\nUses user profile (role, industry, goals) to personalize content.\n\nEndpoint supports both standard responses and real-time streaming.\n","tags":["Content Generation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePostRequest"},"examples":{"linkedin_post":{"summary":"LinkedIn Post","value":{"contentType":"linkedin","topic":"Artificial intelligence in marketing","description":"Write about the benefits of AI in marketing campaign automation","streaming":false}},"twitter_post":{"summary":"Tweet","value":{"contentType":"twitter","topic":"Remote work productivity","description":"Share tips for effective work from home","streaming":false}}}}}},"responses":{"200":{"description":"Content generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GeneratePostResponse"}},"text/event-stream":{"schema":{"type":"string"},"description":"Streaming response (when streaming=true).\nEach line is JSON with StreamingChunk object.\nLast line contains '[DONE]' indicating end of stream.\n","example":"data: {\"content\": \"🚀 Artificial intelligence\", \"isComplete\": false}\ndata: {\"content\": \" is revolutionizing marketing!\", \"isComplete\": false}\ndata: {\"content\": \"\\n\\nToday AI helps us...\", \"isComplete\": true}\ndata: [DONE]\n"}}},"400":{"description":"Invalid input data","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"statusCode":400,"statusMessage":"Content type and topic are required"}}}},"401":{"description":"Missing authorization or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"statusCode":401,"statusMessage":"API key is required"}}}},"500":{"description":"Server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"},"example":{"statusCode":500,"statusMessage":"Failed to generate content"}}}}}}},"/api/content/generate-topics":{"post":{"summary":"Generate engaging content topics","description":"Generates highly engaging and clickable topics for social media posts and articles using AI.\nPerfect for content creators who need inspiration for their next post.\n\nReturns an array of topic ideas designed to maximize engagement and clicks.\n","tags":["Content Generation"],"security":[{"ApiKeyAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTopicsRequest"},"examples":{"general_topics":{"summary":"Generate general topics","value":{"limit":10}},"niche_topics":{"summary":"Generate niche-specific topics","value":{"limit":15,"description":"productivity and time management for entrepreneurs"}},"minimal_request":{"summary":"Minimal request (default limit)","value":{}}}}}},"responses":{"200":{"description":"Topics generated successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/GenerateTopicsResponse"},"examples":{"productivity_topics":{"summary":"Productivity-focused topics","value":["The 5-minute rule that doubled my productivity","Why successful people wake up at 5 AM (it's not what you think)","I tried the Pomodoro Technique for 30 days - here's what happened","The productivity app that replaced my entire workflow","3 simple habits that transformed my morning routine"]},"business_topics":{"summary":"Business-focused topics","value":["I quit my 6-figure job to start a business - here's the truth","The LinkedIn strategy that got me 50k followers","Why most startups fail (and how to avoid it)","The email template that converts 47% of cold leads","3 networking mistakes that are costing you opportunities"]}}}}},"400":{"description":"Invalid request parameters","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"500":{"description":"Internal server error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}}}},"/api/status":{"get":{"summary":"Check service health status","description":"Returns the current health status of the NexPost API service.\nThis endpoint can be used for monitoring and health checks.\n","tags":["System"],"responses":{"200":{"description":"Service is healthy and operational","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"},"example":{"status":"healthy","message":"NexPost API is operational","timestamp":"2025-01-29T10:30:00.000Z","version":"1.0.0","uptime":86400,"services":{"database":"connected","ai_service":"operational"}}}}},"503":{"description":"Service is unhealthy or experiencing issues","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusResponse"},"example":{"status":"unhealthy","message":"Service temporarily unavailable","timestamp":"2025-01-29T10:30:00.000Z","version":"1.0.0","uptime":86400,"services":{"database":"connected","ai_service":"error"}}}}}}}}},"tags":[]}