{"openapi":"3.1.0","info":{"title":"flowxapi Public API","version":"1.0.0","description":"Production-grade REST API for X/Twitter automation and data extraction with transparent micro-dollar metering and per-key rate limiting.","contact":{"name":"flowxapi Support","url":"https://github.com/azeezalhajj570-ai/flowxapi"},"license":{"name":"Apache 2.0","url":"https://www.apache.org/licenses/LICENSE-2.0.html"}},"servers":[{"url":"https://api.flowxapi.dev/v1","description":"Production API Server"},{"url":"http://localhost:3001/v1","description":"Local Development Server"}],"security":[{"ApiKeyAuth":[]}],"components":{"securitySchemes":{"ApiKeyAuth":{"type":"http","scheme":"bearer","bearerFormat":"fxa_*","description":"Bearer token using your flowxapi API key (e.g. `Bearer fxa_...`)."}},"schemas":{"StandardSuccess":{"type":"object","required":["ok","data"],"properties":{"ok":{"type":"boolean","example":true},"data":{"type":"object"}}},"StandardError":{"type":"object","required":["ok","error"],"properties":{"ok":{"type":"boolean","example":false},"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","example":"RATE_LIMITED"},"message":{"type":"string","example":"Rate limit exceeded."}}}}},"User":{"type":"object","properties":{"id":{"type":"string","example":"44196397"},"username":{"type":"string","example":"elonmusk"},"name":{"type":"string","example":"Elon Musk"},"bio":{"type":"string","nullable":true},"followers":{"type":"integer","example":190000000},"following":{"type":"integer","example":700},"verified":{"type":"boolean","example":true}}},"Tweet":{"type":"object","properties":{"id":{"type":"string","example":"1800000000000000000"},"text":{"type":"string","example":"Hello world"},"authorId":{"type":"string","example":"44196397"},"authorUsername":{"type":"string","example":"elonmusk"},"createdAt":{"type":"string","format":"date-time"},"likes":{"type":"integer","example":15000},"retweets":{"type":"integer","example":2500}}}}},"paths":{"/health":{"get":{"summary":"Service health check","description":"Liveness probe and deployment timestamp.","security":[],"x-price-micros":0,"responses":{"200":{"description":"Service is healthy","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/pricing":{"get":{"summary":"Route pricing directory","description":"Returns the micro-dollar price table for all flowxapi routes.","security":[],"x-price-micros":0,"responses":{"200":{"description":"Price list in micro-dollars ($0.000001 USD)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/keys":{"get":{"summary":"List API keys","description":"Lists all active API keys for the authenticated dashboard user.","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}},"post":{"summary":"Issue a new API key","description":"Issues a new secret API key (`fxa_...`). The raw key is returned exactly once.","x-price-micros":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["name"],"properties":{"name":{"type":"string","example":"Production Scraper"}}}}}},"responses":{"201":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/user/info":{"get":{"summary":"Get user profile by screen name","description":"Fetches public user profile information with normalized fields.","x-price-micros":1000,"parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string","example":"elonmusk"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}},"/twitter/user/tweets":{"get":{"summary":"Get user tweets","description":"Fetches recent timeline tweets for a user.","x-price-micros":2000,"parameters":[{"name":"username","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/tweet/detail":{"get":{"summary":"Get single tweet detail","description":"Fetches a tweet by numeric ID with engagement stats.","x-price-micros":1000,"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/tweet/advanced_search":{"get":{"summary":"Advanced tweet search","description":"Search tweets with filters (from, to, since, until, min_likes, etc.).","x-price-micros":5000,"parameters":[{"name":"q","in":"query","schema":{"type":"string"}},{"name":"from","in":"query","schema":{"type":"string"}},{"name":"min_likes","in":"query","schema":{"type":"integer"}},{"name":"limit","in":"query","schema":{"type":"integer","default":20}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/list/members":{"get":{"summary":"Get list members","description":"Returns members of a Twitter list.","x-price-micros":1000,"parameters":[{"name":"id","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/trends":{"get":{"summary":"Get trending topics","description":"Fetches trending topics by Yahoo Where On Earth ID (WOEID). 1 = worldwide.","x-price-micros":1000,"parameters":[{"name":"woeid","in":"query","schema":{"type":"integer","default":1}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/trends/locations":{"get":{"summary":"Get available trend locations","description":"Returns the list of locations and WOEIDs that have trending topics available.","x-price-micros":1000,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/tweet/create":{"post":{"summary":"Create a tweet","description":"Post a new tweet, reply, or quote tweet with optional media attachments using in-flight credentials.","x-price-micros":10000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"text":{"type":"string","example":"Hello from flowxapi!"},"replyTo":{"type":"string","description":"Tweet ID to reply to"},"quoteTweetId":{"type":"string","description":"Tweet ID to quote"},"media":{"type":"array","items":{"type":"string"}}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}},"409":{"description":"Duplicate tweet conflict"}}}},"/twitter/tweet/delete":{"post":{"summary":"Delete a tweet","description":"Delete an existing tweet using in-flight credentials.","x-price-micros":2000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"1800000000000000000"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/tweet/favorite":{"post":{"summary":"Like a tweet","description":"Like a tweet using in-flight credentials.","x-price-micros":3000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"1800000000000000000"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/tweet/retweet":{"post":{"summary":"Retweet a tweet","description":"Retweet a tweet using in-flight credentials.","x-price-micros":5000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string","example":"1800000000000000000"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/user/follow":{"post":{"summary":"Follow a user","description":"Follow a user by username or userId using in-flight credentials.","x-price-micros":5000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"elonmusk"},"userId":{"type":"string","example":"44196397"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/user/unfollow":{"post":{"summary":"Unfollow a user","description":"Unfollow a user by username or userId using in-flight credentials.","x-price-micros":5000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"username":{"type":"string","example":"elonmusk"},"userId":{"type":"string","example":"44196397"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/dm/list":{"post":{"summary":"List direct message conversations","description":"Fetch account direct message inbox and conversation threads using in-flight credentials.","x-price-micros":2000,"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"limit":{"type":"integer","default":50},"cursor":{"type":"string","description":"Pagination cursor or max_id"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}},"get":{"summary":"List direct message conversations","description":"Fetch account direct message inbox and conversation threads using in-flight credentials.","x-price-micros":2000,"parameters":[{"name":"limit","in":"query","schema":{"type":"integer","default":50}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/dm/conversation":{"post":{"summary":"Get messages for a DM conversation","description":"Fetch message history for a specific DM conversation using in-flight credentials.","x-price-micros":2000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["conversationId"],"properties":{"conversationId":{"type":"string","example":"12345-67890"},"limit":{"type":"integer","default":100},"cursor":{"type":"string"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}},"get":{"summary":"Get messages for a DM conversation","description":"Fetch message history for a specific DM conversation using in-flight credentials.","x-price-micros":2000,"parameters":[{"name":"conversationId","in":"query","required":true,"schema":{"type":"string"}},{"name":"limit","in":"query","schema":{"type":"integer","default":100}},{"name":"cursor","in":"query","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/dm/send":{"post":{"summary":"Send a direct message","description":"Send a direct message by recipientId or username using in-flight credentials.","x-price-micros":5000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["text"],"properties":{"username":{"type":"string","example":"elonmusk"},"recipientId":{"type":"string","example":"44196397"},"text":{"type":"string","example":"Hello from flowxapi"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/media/upload":{"post":{"summary":"Upload media","description":"Upload chunked media (image, video, or GIF) via base64 or URL using in-flight credentials.","x-price-micros":5000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"media_data":{"type":"string","description":"Base64 encoded data"},"media_type":{"type":"string","example":"image/jpeg"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/tweet/edit":{"post":{"summary":"Edit a tweet","description":"Publishes an edit revision for a tweet using in-flight credentials.","x-price-micros":2000,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id","text"],"properties":{"id":{"type":"string","example":"20"},"text":{"type":"string","example":"Updated tweet text"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/user/likes":{"post":{"summary":"Get user likes","description":"Fetches tweets liked by a specified user.","x-price-micros":1000,"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"userName":{"type":"string","example":"NASA"},"limit":{"type":"integer","default":20}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/user/home_timeline":{"post":{"summary":"Get authenticated user home timeline","description":"Fetches home timeline posts for the authenticated account.","x-price-micros":1000,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/user/bookmark_search":{"post":{"summary":"Search authenticated user bookmarks","description":"Fetches or searches bookmarks for the authenticated account.","x-price-micros":1000,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/account/me":{"get":{"summary":"Get account info","description":"Returns profile, balance and subscription info for authenticated user (Free).","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/account/payments":{"get":{"summary":"Get payment history","description":"Returns transaction and ledger history for authenticated user (Free).","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/webhook/create":{"post":{"summary":"Register webhook delivery URL","description":"Register a delivery URL and receive an HMAC-SHA256 signing secret (Free with Monitoring Plan).","x-price-micros":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["url"],"properties":{"url":{"type":"string","example":"https://example.com/webhook"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/webhook/list":{"get":{"summary":"List customer webhooks","description":"Lists all registered delivery webhooks for the customer (Free with Monitoring Plan).","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/webhook/test":{"post":{"summary":"Send test webhook delivery","description":"Sends a signed test event payload to verify endpoint connectivity (Free with Monitoring Plan).","x-price-micros":0,"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"webhook_id":{"type":"string"},"url":{"type":"string"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/webhook/delete":{"post":{"summary":"Remove webhook","description":"Deletes a webhook if no active monitors are attached (Free with Monitoring Plan).","x-price-micros":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}},"delete":{"summary":"Remove webhook","description":"Deletes a webhook if no active monitors are attached (Free with Monitoring Plan).","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/add":{"post":{"summary":"Add account monitor","description":"Starts watching an X account with forward-only baseline detection (Free with Monitoring Plan).","x-price-micros":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["target"],"properties":{"target":{"type":"string","example":"NASA"},"webhook_id":{"type":"string"},"webhook_url":{"type":"string"},"tier":{"type":"string","enum":["standard","fast"],"default":"standard"},"include_replies":{"type":"boolean","default":false}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/list":{"get":{"summary":"List account monitors","description":"Returns active and paused monitors with requested and dynamic effective tier (Free with Monitoring Plan).","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/update":{"post":{"summary":"Update monitor","description":"Pause, resume (re-baselines), or change tier/webhook on a monitor (Free with Monitoring Plan).","x-price-micros":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"},"action":{"type":"string","enum":["pause","resume"]},"tier":{"type":"string","enum":["standard","fast"]},"webhook_id":{"type":"string"},"include_replies":{"type":"boolean"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/remove":{"post":{"summary":"Remove account monitor","description":"Stops watching an account and frees plan monitor slot (Free with Monitoring Plan).","x-price-micros":0,"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["id"],"properties":{"id":{"type":"string"}}}}}},"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/twitter/monitor/health":{"get":{"summary":"Monitoring queue and delivery status","description":"Queue health, 24h delivery stats, and average latency (Free with Monitoring Plan).","x-price-micros":0,"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/jobs/{type}":{"post":{"summary":"Enqueue automation job","description":"Enqueues an asynchronous automation job (unfollow-non-followers, follow-engagers, auto-like, workflow-run). Returns 202 Accepted on success.","x-price-micros":10000,"parameters":[{"name":"type","in":"path","required":true,"schema":{"type":"string","enum":["unfollow-non-followers","follow-engagers","auto-like","workflow-run"]},"description":"The job type to enqueue"}],"requestBody":{"required":false,"content":{"application/json":{"schema":{"type":"object","properties":{"config":{"type":"object","description":"Job configuration options"},"callback_url":{"type":"string","format":"uri","description":"Webhook URL for completion/failure notification"},"priority":{"type":"integer","default":10},"delay":{"type":"integer","default":0}}}}}},"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}},"/jobs":{"get":{"summary":"List jobs history","description":"Returns recent automation jobs for the authenticated user.","x-price-micros":0,"parameters":[{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":50,"minimum":1,"maximum":100},"description":"Maximum number of jobs to return"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}}}}},"/jobs/{id}":{"get":{"summary":"Get job status and results","description":"Returns status, live progress, results, logs and errors for an automation job.","x-price-micros":0,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Job operation ID"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}},"/jobs/{id}/cancel":{"post":{"summary":"Cancel job","description":"Cancels a queued or active automation job.","x-price-micros":0,"parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"},"description":"Job operation ID"}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardSuccess"}}}},"404":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StandardError"}}}}}}}}}