{"openapi":"3.0.0","info":{"title":"CrowTerminal API","version":"1.0.0","description":"\nCrowTerminal is an AI-powered influencer management platform with multi-agent intelligence.\n\n## Authentication\nMost endpoints require a JWT token. Include it in the Authorization header:\n```\nAuthorization: Bearer <your_token>\n```\n\n## Rate Limiting\n- Authentication endpoints: 5 requests per 15 minutes\n- General API: 100 requests per 15 minutes\n- Agent runs: 10 requests per minute\n\n## Plans\n| Plan | Clients | Token Limit | Price (BRL) |\n|------|---------|-------------|-------------|\n| FREE | 1 | 100K/month | R$0 |\n| STARTER | 3 | 1M/month | R$97 |\n| GROWTH | 10 | 5M/month | R$297 |\n| AGENCY | 25 | 15M/month | R$697 |\n| ENTERPRISE | Unlimited | Custom | Custom |\n      ","contact":{"name":"CrowTerminal Support","email":"support@crowterminal.app"}},"servers":[{"url":"https://web-production-9a2fa.up.railway.app","description":"Production server"}],"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"JWT","description":"JWT token obtained from /api/auth/login"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","description":"Error message"},"code":{"type":"string","description":"Error code"},"details":{"type":"object","description":"Additional error details"}},"required":["error","code"]},"User":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"email":{"type":"string","format":"email"},"name":{"type":"string"},"plan":{"type":"string","enum":["FREE","STARTER","GROWTH","AGENCY","ENTERPRISE"]},"createdAt":{"type":"string","format":"date-time"}}},"Client":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"name":{"type":"string"},"niche":{"type":"string"},"email":{"type":"string","format":"email"},"phone":{"type":"string"},"notes":{"type":"string"},"status":{"type":"string","enum":["ACTIVE","INACTIVE","ONBOARDING"]},"userId":{"type":"string","format":"uuid"},"createdAt":{"type":"string","format":"date-time"}}},"SocialAccount":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"platform":{"type":"string","enum":["TIKTOK","INSTAGRAM","YOUTUBE","TWITTER"]},"username":{"type":"string"},"displayName":{"type":"string"},"followerCount":{"type":"integer"},"isConnected":{"type":"boolean"},"clientId":{"type":"string","format":"uuid"}}},"Agent":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"type":{"type":"string","enum":["CRAWLER","ANALYZER","INSIGHTS","OPTIMIZER","HOOK","AUTO_SCHEDULER","PROFILE_LEARNER"]},"name":{"type":"string"},"isActive":{"type":"boolean"},"schedule":{"type":"string","description":"Cron expression"},"clientId":{"type":"string","format":"uuid"}}},"AgentTask":{"type":"object","properties":{"id":{"type":"string","format":"uuid"},"status":{"type":"string","enum":["PENDING","RUNNING","COMPLETED","FAILED"]},"result":{"type":"object"},"error":{"type":"string"},"startedAt":{"type":"string","format":"date-time"},"completedAt":{"type":"string","format":"date-time"}}},"UsageQuota":{"type":"object","properties":{"plan":{"type":"string","enum":["FREE","STARTER","GROWTH","AGENCY","ENTERPRISE"]},"tokenLimit":{"type":"integer"},"tokensUsed":{"type":"integer"},"tokensRemaining":{"type":"integer"},"percentUsed":{"type":"number"},"resetDate":{"type":"string","format":"date-time"},"canUseTokens":{"type":"boolean"},"overageAllowed":{"type":"boolean"}}},"Pagination":{"type":"object","properties":{"page":{"type":"integer","minimum":1},"limit":{"type":"integer","minimum":1,"maximum":100},"total":{"type":"integer"},"totalPages":{"type":"integer"}}},"EngagementPrediction":{"type":"object","properties":{"prediction":{"type":"object","properties":{"engagementRate":{"type":"object","properties":{"predicted":{"type":"number","description":"Predicted engagement rate (%)"},"confidence":{"type":"number","minimum":0,"maximum":1},"range":{"type":"object","properties":{"low":{"type":"number"},"high":{"type":"number"}}}}},"viewRange":{"type":"object","properties":{"low":{"type":"integer","description":"Low estimate views"},"mid":{"type":"integer","description":"Mid estimate views"},"high":{"type":"integer","description":"High estimate views"},"confidence":{"type":"number","minimum":0,"maximum":1}}},"overallScore":{"type":"integer","minimum":0,"maximum":100}}},"signals":{"type":"object","properties":{"hashtagScore":{"$ref":"#/components/schemas/SignalScore"},"timingScore":{"$ref":"#/components/schemas/SignalScore"},"durationScore":{"$ref":"#/components/schemas/SignalScore"},"captionScore":{"$ref":"#/components/schemas/SignalScore"},"benchmarkScore":{"$ref":"#/components/schemas/SignalScore"}}},"recommendations":{"type":"array","items":{"$ref":"#/components/schemas/Recommendation"}},"tokensUsed":{"type":"integer"},"processingTimeMs":{"type":"integer"}}},"SignalScore":{"type":"object","properties":{"score":{"type":"integer","minimum":0,"maximum":100},"detail":{"type":"string"},"impact":{"type":"string","enum":["positive","neutral","negative"]}}},"Recommendation":{"type":"object","properties":{"type":{"type":"string","enum":["timing","hashtag","caption","duration","general"]},"priority":{"type":"string","enum":["high","medium","low"]},"suggested":{"type":"string"},"potentialImpact":{"type":"string"}}}},"parameters":{"pageParam":{"name":"page","in":"query","schema":{"type":"integer","minimum":1,"default":1},"description":"Page number"},"limitParam":{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":20},"description":"Items per page"}},"responses":{"Unauthorized":{"description":"Authentication required","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Authentication required","code":"AUTH_REQUIRED"}}}},"Forbidden":{"description":"Access denied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Access denied","code":"FORBIDDEN"}}}},"NotFound":{"description":"Resource not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Resource not found","code":"RESOURCE_NOT_FOUND"}}}},"ValidationError":{"description":"Validation failed","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Validation failed","code":"VALIDATION_FAILED","details":{"fields":{"email":"Invalid email"}}}}}},"RateLimited":{"description":"Too many requests","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"},"example":{"error":"Too many requests","code":"RATE_LIMITED"}}}}}},"security":[{"bearerAuth":[]}],"tags":[{"name":"Authentication","description":"User authentication and session management"},{"name":"Clients","description":"Influencer client management"},{"name":"Social Accounts","description":"Social media account connections"},{"name":"Agents","description":"AI agent management and execution"},{"name":"Predictions","description":"Engagement prediction and forecasting"},{"name":"Benchmarks","description":"Niche benchmarks and comparisons"},{"name":"Usage","description":"Token usage and plan limits"},{"name":"Billing","description":"Subscription and payment management"},{"name":"Profiles","description":"AI-learned client profiles"},{"name":"Knowledge","description":"Agency and platform intelligence"}],"paths":{"/api/auth/register":{"post":{"summary":"Register a new user","tags":["Authentication"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password","name"],"properties":{"email":{"type":"string","format":"email","example":"user@example.com"},"password":{"type":"string","minLength":12,"example":"securePassword123!"},"name":{"type":"string","example":"John Doe"}}}}}},"responses":{"201":{"description":"User registered successfully","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"token":{"type":"string"}}}}}},"400":{"description":"Validation error or email already registered","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/auth/login":{"post":{"summary":"Login to an existing account","tags":["Authentication"],"security":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["email","password"],"properties":{"email":{"type":"string","format":"email"},"password":{"type":"string"}}}}}},"responses":{"200":{"description":"Login successful","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"},"token":{"type":"string"}}}}}},"401":{"description":"Invalid credentials"},"429":{"$ref":"#/components/responses/RateLimited"}}}},"/api/auth/me":{"get":{"summary":"Get current authenticated user","tags":["Authentication"],"responses":{"200":{"description":"Current user information","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}},"patch":{"summary":"Update current user profile","tags":["Authentication"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"name":{"type":"string"},"avatarUrl":{"type":"string","format":"uri"}}}}}},"responses":{"200":{"description":"User updated successfully","content":{"application/json":{"schema":{"type":"object","properties":{"user":{"$ref":"#/components/schemas/User"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/benchmarks/niches":{"get":{"summary":"Get available niches with benchmark data","tags":["Benchmarks"],"responses":{"200":{"description":"List of niches with benchmark data"}}}},"/api/benchmarks/niche/{niche}":{"get":{"summary":"Get benchmark data for a specific niche","tags":["Benchmarks"],"parameters":[{"name":"niche","in":"path","required":true,"schema":{"type":"string"},"description":"The niche to get benchmarks for"}],"responses":{"200":{"description":"Benchmark data for the niche"},"404":{"description":"No benchmark data available for this niche"}}}},"/api/benchmarks/client/{clientId}":{"get":{"summary":"Get benchmark comparison for a specific client","tags":["Benchmarks"],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"},"description":"The client ID to get benchmarks for"}],"responses":{"200":{"description":"Benchmark comparison data for the client"},"404":{"description":"Client not found or no benchmark data available"}}}},"/api/benchmarks/client/{clientId}/history":{"get":{"summary":"Get benchmark history for a client","tags":["Benchmarks"],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":12},"description":"Number of historical snapshots to return"}],"responses":{"200":{"description":"Historical benchmark data for the client"}}}},"/api/benchmarks/summary":{"get":{"summary":"Get benchmark summary across all user's clients","tags":["Benchmarks"],"responses":{"200":{"description":"Summary of benchmark positions for all clients"}}}},"/api/billing/checkout":{"post":{"summary":"Create a Stripe checkout session for subscription","tags":["Billing"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["priceId"],"properties":{"priceId":{"type":"string","description":"Stripe price ID for the plan"},"successUrl":{"type":"string","format":"uri","description":"URL to redirect after successful checkout"},"cancelUrl":{"type":"string","format":"uri","description":"URL to redirect if checkout is canceled"}}}}}},"responses":{"200":{"description":"Checkout session created","content":{"application/json":{"schema":{"type":"object","properties":{"sessionId":{"type":"string"},"url":{"type":"string","format":"uri","description":"Stripe checkout URL"}}}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/billing/portal":{"post":{"summary":"Create a Stripe customer portal session","tags":["Billing"],"description":"Opens Stripe's customer portal for subscription management","requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"returnUrl":{"type":"string","format":"uri","description":"URL to redirect after leaving portal"}}}}}},"responses":{"200":{"description":"Portal session created","content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/clients":{"post":{"summary":"Create a new influencer client","tags":["Clients"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","maxLength":100,"example":"John's Fashion Account"},"email":{"type":"string","format":"email"},"phone":{"type":"string","maxLength":20},"niche":{"type":"string","maxLength":100,"example":"Fashion & Lifestyle"},"notes":{"type":"string","maxLength":1000},"language":{"type":"string","enum":["en","pt-BR","es","fr","de","it","ja","ko","zh"]},"region":{"type":"string","enum":["US","BR","LATAM","EU","ASIA","AFRICA","OCEANIA","GLOBAL"]},"targetAgeMin":{"type":"integer","minimum":13,"maximum":100},"targetAgeMax":{"type":"integer","minimum":13,"maximum":100},"targetGender":{"type":"string","enum":["all","male","female"]},"contentGoals":{"type":"array","items":{"type":"string","enum":["brand_awareness","sales","engagement","education","entertainment","lead_generation"]}},"postingFrequency":{"type":"string","enum":["daily","3x_week","2x_week","weekly","bi_weekly"]},"brandVoice":{"type":"string","enum":["professional","casual","humorous","inspirational","educational","edgy"]}}}}}},"responses":{"201":{"description":"Client created successfully","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Client"}}}},"400":{"$ref":"#/components/responses/ValidationError"},"401":{"$ref":"#/components/responses/Unauthorized"}}},"get":{"summary":"Get all clients (paginated)","tags":["Clients"],"parameters":[{"$ref":"#/components/parameters/pageParam"},{"$ref":"#/components/parameters/limitParam"},{"name":"search","in":"query","schema":{"type":"string"},"description":"Search by client name"},{"name":"isActive","in":"query","schema":{"type":"boolean"},"description":"Filter by active status"}],"responses":{"200":{"description":"Paginated list of clients","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Client"}},"pagination":{"$ref":"#/components/schemas/Pagination"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/clients/{id}":{"get":{"summary":"Get a single client by ID","tags":["Clients"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"},"description":"Client ID"}],"responses":{"200":{"description":"Client details","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Client"}}}},"401":{"$ref":"#/components/responses/Unauthorized"},"404":{"$ref":"#/components/responses/NotFound"}}}},"/api/desktop-sync/transcripts":{"post":{"summary":"Upload a transcript from desktop app","tags":["Desktop Sync"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["fileName","text","language"],"properties":{"fileName":{"type":"string","description":"Original file name"},"text":{"type":"string","description":"Transcription text"},"language":{"type":"string","description":"Detected language"},"duration":{"type":"number","description":"Duration in seconds"},"localId":{"type":"string","description":"Local ID from desktop app"},"createdAt":{"type":"string","format":"date-time"},"clientId":{"type":"string","description":"Optional client to associate with"}}}}}},"responses":{"201":{"description":"Transcript uploaded successfully"},"400":{"description":"Validation error"},"401":{"description":"Unauthorized"}}},"get":{"summary":"Get all transcripts for the user","tags":["Desktop Sync"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"query","name":"limit","schema":{"type":"integer","default":50}},{"in":"query","name":"offset","schema":{"type":"integer","default":0}},{"in":"query","name":"clientId","schema":{"type":"string"}}],"responses":{"200":{"description":"List of transcripts"},"401":{"description":"Unauthorized"}}}},"/api/desktop-sync/count":{"get":{"summary":"Get count of transcripts in cloud","tags":["Desktop Sync"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Transcript count"},"401":{"description":"Unauthorized"}}}},"/api/desktop-sync/transcripts/{id}":{"delete":{"summary":"Delete a transcript (soft delete)","tags":["Desktop Sync"],"security":[{"bearerAuth":[]}],"parameters":[{"in":"path","name":"id","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Transcript deleted"},"401":{"description":"Unauthorized"},"404":{"description":"Transcript not found"}}}},"/api/desktop-sync/sessions":{"post":{"summary":"Register a desktop app session","tags":["Desktop Sync"],"security":[{"bearerAuth":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["deviceId","platform","appVersion"],"properties":{"deviceId":{"type":"string"},"platform":{"type":"string","enum":["darwin","win32","linux"]},"appVersion":{"type":"string"},"hardwareInfo":{"type":"object"}}}}}},"responses":{"201":{"description":"Session registered"},"401":{"description":"Unauthorized"}}},"get":{"summary":"Get all desktop sessions for the user","tags":["Desktop Sync"],"security":[{"bearerAuth":[]}],"responses":{"200":{"description":"List of sessions"},"401":{"description":"Unauthorized"}}}},"/api/predictions/engagement":{"post":{"summary":"Predict engagement rate and view range for planned content","tags":["Predictions"],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["clientId","content"],"properties":{"clientId":{"type":"string","format":"uuid"},"content":{"type":"object","properties":{"caption":{"type":"string"},"hashtags":{"type":"array","items":{"type":"string"}},"videoDuration":{"type":"integer"},"postingTime":{"type":"string","format":"date-time"}}},"options":{"type":"object","properties":{"includeRecommendations":{"type":"boolean","default":false}}}}}}}},"responses":{"200":{"description":"Engagement prediction result"},"400":{"description":"Invalid input"},"404":{"description":"Client not found"}}}},"/api/predictions/{clientId}/history":{"get":{"summary":"Get prediction history for a client","tags":["Predictions"],"parameters":[{"name":"clientId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20,"minimum":1,"maximum":50}},{"name":"offset","in":"query","schema":{"type":"integer","default":0,"minimum":0}}],"responses":{"200":{"description":"Prediction history"},"404":{"description":"Client not found"}}}},"/api/predictions/{id}/actual":{"patch":{"summary":"Record actual engagement results for a prediction","tags":["Predictions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["actualEngagement","actualViews"],"properties":{"actualEngagement":{"type":"number","minimum":0,"maximum":100},"actualViews":{"type":"integer","minimum":0},"linkedPostId":{"type":"string","format":"uuid"}}}}}},"responses":{"200":{"description":"Actual results recorded"},"404":{"description":"Prediction not found"}}}},"/api/predictions/{id}":{"get":{"summary":"Get a specific prediction by ID","tags":["Predictions"],"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Prediction details"},"404":{"description":"Prediction not found"}}}},"/api/predictions/accuracy/summary":{"get":{"summary":"Get prediction accuracy summary across all clients","tags":["Predictions"],"responses":{"200":{"description":"Accuracy summary"}}}},"/api/usage/quota":{"get":{"summary":"Get current usage quota status","tags":["Usage"],"responses":{"200":{"description":"Current usage quota","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/UsageQuota"},{"type":"object","properties":{"warningLevel":{"type":"string","enum":["none","soft","hard"]}}}]}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/usage/summary":{"get":{"summary":"Get detailed usage summary","tags":["Usage"],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"Number of days to include in summary"}],"responses":{"200":{"description":"Usage summary with breakdown by feature and daily usage","content":{"application/json":{"schema":{"type":"object","properties":{"totalTokens":{"type":"integer"},"totalRequests":{"type":"integer"},"successRate":{"type":"number"},"avgLatency":{"type":"number"},"byFeature":{"type":"object","additionalProperties":{"type":"object","properties":{"tokens":{"type":"integer"},"requests":{"type":"integer"}}}},"dailyUsage":{"type":"array","items":{"type":"object","properties":{"date":{"type":"string","format":"date"},"tokens":{"type":"integer"}}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/usage/platform-analytics":{"get":{"summary":"Get platform-wide usage analytics","description":"Returns comprehensive analytics across all users for business intelligence","tags":["Usage"],"parameters":[{"name":"days","in":"query","schema":{"type":"integer","minimum":1,"maximum":365,"default":30},"description":"Number of days to include in analytics"}],"responses":{"200":{"description":"Platform analytics data","content":{"application/json":{"schema":{"type":"object","properties":{"overview":{"type":"object","properties":{"totalUsers":{"type":"integer"},"activeUsers":{"type":"integer"},"totalClients":{"type":"integer"},"totalTokensUsed":{"type":"integer"},"totalCostUsd":{"type":"number"},"avgCostPerUser":{"type":"number"},"avgTokensPerUser":{"type":"integer"}}}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}},"/api/usage/cost-projection":{"get":{"summary":"Get cost projection for current month","tags":["Usage"],"responses":{"200":{"description":"Cost projection data","content":{"application/json":{"schema":{"type":"object","properties":{"currentMonthCost":{"type":"number"},"projectedMonthCost":{"type":"number"},"daysElapsed":{"type":"integer"},"daysInMonth":{"type":"integer"},"dailyAvgCost":{"type":"number"}}}}}},"401":{"$ref":"#/components/responses/Unauthorized"}}}}}}