⚡ XActions
📖 Guides & Reference

XActions REST API Reference

Complete reference for the XActions Express.js API server. 175+ endpoints for Twitter automation, scraping, analytics, AI agents, and more.

Base URL: http://localhost:3001 (development) | https://api.xactions.app (production)

Table of Contents

Authentication

All authenticated endpoints require a JWT token in the Authorization header:

Authorization: Bearer <jwt_token>

Register

POST /api/auth/register
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password",
  "username": "myusername"
}

Login

POST /api/auth/login
Content-Type: application/json

{
  "email": "user@example.com",
  "password": "secure_password"
}

Response:

{
  "token": "eyJ...",
  "user": { "id": 1, "email": "user@example.com", "username": "myusername" }
}

Refresh Token

POST /api/auth/refresh
Authorization: Bearer <jwt_token>

For dashboard users, session authentication is also supported via /api/session.

Health Checks

GET /health
GET /api/health

Response:

{ "status": "ok", "service": "xactions-api", "timestamp": "2026-02-25T..." }

Profile Management

Get Profile

GET /api/profile/:username

Response:

{
  "username": "nichxbt",
  "name": "nich",
  "bio": "Building XActions",
  "followers": 25000,
  "following": 1200,
  "verified": true,
  "location": "Internet",
  "website": "https://xactions.app"
}

Update Profile

PUT /api/profile/update
Content-Type: application/json

{
  "name": "New Name",
  "bio": "Updated bio",
  "location": "New York",
  "website": "https://example.com"
}

Content Posting

Post a Tweet

POST /api/posting/tweet
Content-Type: application/json

{ "text": "Hello from XActions! ⚡" }

Post a Thread

POST /api/posting/thread
Content-Type: application/json

{
  "tweets": [
    "Thread about XActions 🧵",
    "1/ It's free and open source",
    "2/ Works with Claude, Cursor, GPT",
    "3/ No Twitter API fees"
  ]
}

Create a Poll

POST /api/posting/poll
Content-Type: application/json

{
  "question": "Best automation tool?",
  "options": ["XActions", "Manual", "Twitter API"],
  "duration": { "days": 1 }
}

Schedule a Tweet

POST /api/posting/schedule
Content-Type: application/json

{
  "text": "Scheduled tweet!",
  "scheduledAt": "2026-03-01T10:00:00Z"
}

Delete a Tweet

DELETE /api/posting/tweet/:tweetId

Engagement

Like / Unlike

POST   /api/engagement/like/:tweetId
DELETE /api/engagement/like/:tweetId

Reply to a Tweet

POST /api/engagement/reply/:tweetId
Content-Type: application/json

{ "text": "Great point! 🔥" }

Bookmark a Tweet

POST /api/engagement/bookmark/:tweetId

Auto-Like

POST /api/engagement/auto-like
Content-Type: application/json

{
  "keywords": ["AI", "automation"],
  "maxLikes": 50,
  "dryRun": false
}

Get Engagement Analytics

GET /api/engagement/analytics

Search Tweets

GET /api/discovery/search?q=xactions&limit=50&filter=latest

GET /api/discovery/trends

Get Explore Feed

GET /api/discovery/explore

Direct Messages

Send DM

POST /api/messages/send
Content-Type: application/json

{
  "username": "targetuser",
  "message": "Hey! Checking out XActions?"
}

Get Conversations

GET /api/messages/conversations

Export DMs

GET /api/messages/export

Bookmarks

Get Bookmarks

GET /api/bookmarks/

Create Bookmark Folder

POST /api/bookmarks/folders
Content-Type: application/json

{ "name": "Research" }

Clear All Bookmarks

DELETE /api/bookmarks/clear

Thread Reader

Unroll a Thread

POST /api/thread/unroll
Content-Type: application/json

{ "url": "https://x.com/user/status/123456789" }

Response:

{
  "author": "username",
  "tweets": [
    { "text": "1/ Thread starts...", "timestamp": "2026-02-25T...", "likes": 142 }
  ],
  "tweetCount": 12
}

AI Thread Summary

POST /api/thread/summarize
Content-Type: application/json

{ "url": "https://x.com/user/status/123456789" }

Get as Text/Markdown

GET /api/thread/:tweetId/text
GET /api/thread/:tweetId/markdown

Video Download

Extract Video URLs

POST /api/video/extract
Content-Type: application/json

{ "url": "https://x.com/user/status/123456789" }

Response:

{
  "videos": [
    { "url": "https://video.twimg.com/...", "quality": "720p", "width": 1280, "height": 720 }
  ],
  "thumbnail": "https://pbs.twimg.com/...",
  "author": "username"
}

Proxy Download

GET /api/video/download?url=<video_url>&author=user&tweetId=123

Unfollower Tracking

Trigger a Scan

POST /api/unfollowers/scan

Get History

GET /api/unfollowers/history

Get Stats

GET /api/unfollowers/stats

Get Changes (Gained/Lost)

GET /api/unfollowers/changes

Get Chart Data

GET /api/unfollowers/chart

Manage Auto-Scan Schedule

GET    /api/unfollowers/schedule
POST   /api/unfollowers/schedule    { "interval": "6h" }
DELETE /api/unfollowers/schedule

Core Operations

Long-running operations (unfollow, detect) run as background jobs.

Unfollow Non-Followers

POST /api/operations/unfollow-non-followers
Content-Type: application/json

{
  "username": "myhandle",
  "maxUnfollows": 100,
  "dryRun": true
}

Unfollow Everyone

POST /api/operations/unfollow-everyone
Content-Type: application/json

{
  "username": "myhandle",
  "maxUnfollows": 500
}

Detect Unfollowers

POST /api/operations/detect-unfollowers
Content-Type: application/json

{ "username": "myhandle" }

Check Operation Status

GET /api/operations/status/:operationId

Cancel Operation

POST /api/operations/cancel/:operationId

List All Operations

GET /api/operations/

Social Graph

Build a Graph

POST /api/graph/build
Content-Type: application/json

{
  "username": "nichxbt",
  "depth": 2,
  "maxFollowers": 500,
  "maxNodes": 500,
  "authToken": "your_auth_token"
}

List Graphs

GET /api/graph/

Get Graph Data

GET /api/graph/:id

Get Analysis

GET /api/graph/:id/analysis

Response:

{
  "totalNodes": 450,
  "totalEdges": 3200,
  "mutualConnections": [{ "a": "alice", "b": "bob" }],
  "bridgeAccounts": [{ "username": "carol", "betweenness": 0.42 }],
  "clusters": [{ "id": 0, "members": ["..."], "size": 45 }],
  "influenceRanking": [{ "username": "nichxbt", "score": 0.87 }],
  "ghostFollowers": [{ "username": "bot123", "reasons": ["no_bio"] }]
}

Get Recommendations

GET /api/graph/:id/recommendations

Export Visualization

GET /api/graph/:id/visualization
GET /api/graph/:id/visualization?format=gexf
GET /api/graph/:id/visualization?format=html

Delete Graph

DELETE /api/graph/:id

Real-Time Streams

Create a Stream

POST /api/streams/
Content-Type: application/json

{
  "type": "tweet",
  "username": "elonmusk",
  "interval": 60
}

Types: tweet, follower, mention

List Streams

GET /api/streams/

Get Stream Status

GET /api/streams/:id

Update Stream

PATCH /api/streams/:id
Content-Type: application/json

{ "interval": 120 }

Pause / Resume

POST /api/streams/:id/pause
POST /api/streams/:id/resume

Get Event History

GET /api/streams/:id/history?limit=50&type=tweet

Stop Stream / Stop All

DELETE /api/streams/:id
DELETE /api/streams/

Get Stats

GET /api/streams/stats

Workflows

Create a Workflow

POST /api/workflows/
Content-Type: application/json

{
  "name": "Daily Growth",
  "trigger": { "type": "cron", "schedule": "0 9 * * *" },
  "steps": [
    { "action": "scrapeProfile", "params": { "username": "myhandle" } },
    { "action": "autoLike", "params": { "keywords": ["AI"], "maxLikes": 20 } }
  ]
}

List / Get / Update / Delete

GET    /api/workflows/
GET    /api/workflows/:id
PUT    /api/workflows/:id
DELETE /api/workflows/:id

Run a Workflow

POST /api/workflows/:id/run

Get Execution History

GET /api/workflows/:id/runs
GET /api/workflows/:id/runs/:runId

List Available Actions

GET /api/workflows/actions

Webhook Trigger

POST /api/workflows/webhook/:webhookId

Automations

Get All Automation Status

GET /api/automations/status

Start / Stop an Automation

POST /api/automations/:name/start
POST /api/automations/:name/stop

Update Settings

POST /api/automations/:name/settings
Content-Type: application/json

{ "maxLikes": 100, "keywords": ["AI", "crypto"] }

Emergency Stop

POST /api/automations/stop-all

Analytics & Sentiment

Analyze Sentiment

POST /api/analytics/sentiment
Content-Type: application/json

{ "text": "XActions is amazing! Best tool ever 🔥" }

Response:

{
  "score": 0.85,
  "label": "positive",
  "breakdown": { "positive": 0.85, "neutral": 0.12, "negative": 0.03 }
}

Monitor a Target

POST /api/analytics/monitor
Content-Type: application/json

{ "target": "nichxbt", "interval": 300 }

Get Monitoring Results

GET /api/analytics/monitor
GET /api/analytics/monitor/:id
DELETE /api/analytics/monitor/:id

Reputation Report

GET /api/analytics/reports/:username

Alerts

GET /api/analytics/alerts

Tweet-Price Correlation

POST /api/analytics/price-correlation
Content-Type: application/json

{
  "username": "elonmusk",
  "coinId": "bitcoin",
  "days": 30
}

Account History & Growth

GET /api/analytics/history/:username
GET /api/analytics/growth/:username
POST /api/analytics/compare     { "usernames": ["alice", "bob"] }
GET /api/analytics/export/:username
GET /api/analytics/overlap?users=alice,bob,carol

Creator Tools

GET /api/creator/analytics
GET /api/creator/revenue
GET /api/creator/subscribers

Spaces

GET /api/spaces/live
GET /api/spaces/scheduled
GET /api/spaces/scrape?url=<space_url>

Settings & Privacy

GET  /api/settings/
PUT  /api/settings/protected     { "enabled": true }
GET  /api/settings/blocked
GET  /api/settings/muted
POST /api/settings/download-data

Data Portability

Export Account

POST /api/portability/export
Content-Type: application/json

{ "username": "myhandle", "sections": ["profile", "tweets", "followers"] }

Check Export Progress

GET /api/portability/export/:id

Download Export

GET /api/portability/export/:id/download

Migrate to Another Platform

POST /api/portability/migrate
Content-Type: application/json

{
  "username": "myhandle",
  "platform": "bluesky",
  "targetHandle": "myhandle.bsky.social"
}

Compare Exports (Diff)

POST /api/portability/diff
Content-Type: application/json

{ "exportA": "export-id-1", "exportB": "export-id-2" }

List Exports

GET /api/portability/exports

Follower CRM

Sync Followers

POST /api/crm/sync/:username

Tag a Contact

POST /api/crm/tag
Content-Type: application/json

{ "username": "alice", "tag": "VIP" }

Search Contacts

GET /api/crm/search?q=alice&tag=VIP

Get Segment

GET /api/crm/segment/:name

Auto-Score Contacts

POST /api/crm/score

Job Scheduler

GET    /api/schedule/                    # List jobs
POST   /api/schedule/                    # Add a job { name, cron, action, params }
DELETE /api/schedule/:name               # Remove a job
POST   /api/schedule/:name/run           # Run now

Datasets

Apify-style dataset storage for scraping results.

GET    /api/datasets/                    # List datasets
GET    /api/datasets/:name               # Get items
GET    /api/datasets/:name/export?format=json  # Export (json, csv, jsonl)
DELETE /api/datasets/:name               # Delete

Notifications

Multi-channel notification hub (Email, Slack, Discord, Telegram).

POST /api/notifications/send    { "message": "Alert!", "title": "XActions", "severity": "info" }
POST /api/notifications/test/:channel   # channel: email, slack, discord, telegram
POST /api/notifications/configure       # Interactive config

Team Management

POST   /api/teams/                       # Create team { name, owner }
GET    /api/teams/:id/members            # List members
POST   /api/teams/:id/invite             # Invite { email, role }
DELETE /api/teams/:id/members/:username   # Remove member
PUT    /api/teams/:id/members/:username/role  # Update role
GET    /api/teams/:id/activity           # Activity log

AI Content Optimizer

AI-powered tweet optimization (requires OpenRouter API key).

Optimize Tweet

POST /api/optimizer/optimize
Content-Type: application/json

{ "text": "Check out this new tool" }

Response:

{
  "original": "Check out this new tool",
  "optimized": "🔥 Just found the tool that changed how I do Twitter automation.\n\nFree. Open source. No API fees.\n\nThread 🧵",
  "improvements": ["Added hook", "Added emoji", "Created curiosity gap"]
}

Suggest Hashtags

POST /api/optimizer/hashtags
{ "text": "Building open source automation tools" }

Predict Performance

POST /api/optimizer/predict
{ "text": "Your tweet text here" }

Generate Variations

POST /api/optimizer/variations
{ "text": "Original tweet", "count": 5 }

AI Agent API

Dedicated endpoints optimized for AI agent consumption. All under /api/ai/.

Scraping

POST /api/ai/scrape/profile      { "username": "nichxbt" }
POST /api/ai/scrape/followers    { "username": "nichxbt", "limit": 100 }
POST /api/ai/scrape/following    { "username": "nichxbt", "limit": 100 }
POST /api/ai/scrape/tweets       { "username": "nichxbt", "limit": 50 }
POST /api/ai/scrape/thread       { "url": "https://x.com/..." }
POST /api/ai/scrape/search       { "query": "AI agents", "limit": 50 }
POST /api/ai/scrape/hashtag      { "hashtag": "xactions" }
POST /api/ai/scrape/media        { "username": "nichxbt" }

Actions

POST /api/ai/action/unfollow-non-followers  { "username": "myhandle" }
POST /api/ai/action/unfollow-everyone       { "username": "myhandle" }
POST /api/ai/action/detect-unfollowers      { "username": "myhandle" }
POST /api/ai/action/auto-like               { "keywords": ["AI"] }
POST /api/ai/action/follow-engagers         { "tweetUrl": "https://..." }
POST /api/ai/action/keyword-follow          { "keywords": ["web3"], "limit": 20 }
GET  /api/ai/action/status/:operationId

Monitoring

POST /api/ai/monitor/account     { "username": "nichxbt" }
POST /api/ai/monitor/followers   { "username": "nichxbt" }
POST /api/ai/monitor/following   { "username": "nichxbt" }
GET  /api/ai/monitor/snapshot/:username
POST /api/ai/alert/new-followers { "username": "nichxbt" }

Utilities

POST /api/ai/download/video      { "url": "https://x.com/..." }
POST /api/ai/export/bookmarks
POST /api/ai/unroll/thread       { "url": "https://x.com/..." }
POST /api/ai/analyze/profile     { "username": "nichxbt" }

AI Writer

AI-powered content generation using voice analysis.

POST /api/ai/writer/analyze-voice    { "username": "nichxbt" }
POST /api/ai/writer/generate         { "username": "nichxbt", "topic": "AI tools" }
POST /api/ai/writer/rewrite          { "text": "Original tweet", "style": "engaging" }
POST /api/ai/writer/calendar         { "username": "nichxbt", "topics": ["AI", "automation"] }
POST /api/ai/writer/reply            { "tweetUrl": "https://...", "tone": "friendly" }
GET  /api/ai/writer/voice-profiles
GET  /api/ai/writer/voice-profiles/:username

Agent Control

Control the 24/7 LLM-powered thought leadership agent.

GET  /api/agent/status          # Running status & uptime
GET  /api/agent/metrics         # Daily metrics
GET  /api/agent/actions         # Recent action log (paginated)
GET  /api/agent/llm-usage       # LLM cost & token breakdown
GET  /api/agent/config          # Current config
POST /api/agent/config          # Update config
POST /api/agent/start           # Start the agent
POST /api/agent/stop            # Stop the agent
POST /api/agent/feed-score      # Score a tweet for relevance
GET  /api/agent/report          # Growth report (7/30 day)
GET  /api/agent/schedule        # Today's scheduled activities
GET  /api/agent/content         # Content created by agent

Rate Limits

Endpoint Group Limit
General API 100 requests / 15 min
Auth (login/register) 10 attempts / 15 min
Video extraction 30 requests / min

Rate limit headers are included in responses:

X-RateLimit-Limit: 100
X-RateLimit-Remaining: 95
X-RateLimit-Reset: 1708902000

Error Handling

All errors follow a consistent format:

{
  "error": {
    "message": "Descriptive error message",
    "status": 400
  }
}
Status Code Meaning
200 Success
201 Created
400 Bad request / validation error
401 Unauthorized (missing/invalid token)
403 Forbidden (insufficient permissions)
404 Not found
429 Rate limited
500 Server error

WebSocket Events

Connect via Socket.IO for real-time updates:

const socket = io('http://localhost:3001');

// Stream events
socket.on('stream:tweet:new', (data) => { /* new tweet */ });
socket.on('stream:follower:new', (data) => { /* new follower */ });
socket.on('stream:follower:lost', (data) => { /* lost follower */ });
socket.on('stream:mention:new', (data) => { /* new mention */ });
socket.on('stream:error', (data) => { /* stream error */ });

// Operation events
socket.on('operation:progress', (data) => { /* operation progress */ });
socket.on('operation:complete', (data) => { /* operation done */ });

// Analytics alerts
socket.on('alert:follower-spike', (data) => { /* unusual follower activity */ });
socket.on('alert:sentiment-shift', (data) => { /* sentiment change */ });

Environment Variables

Variable Required Default Description
PORT No 3001 Server port
NODE_ENV No development Environment
DATABASE_URL Production — Prisma database URL
JWT_SECRET Production — JWT signing secret
SESSION_SECRET No — Session cookie secret
REDIS_HOST No localhost Redis for streaming/queues
REDIS_PORT No 6379 Redis port
XACTIONS_SESSION_COOKIE No — Default X auth token
OPENROUTER_API_KEY No — For AI writer/optimizer
X402_PAY_TO_ADDRESS No — Wallet for micropayments
FRONTEND_URL No — CORS allowed origin
4 min read Edit this page Report a problem

⚡ Free and open source

No API keys, no monthly fees, no signup. Star the repo if it saved you a subscription.

View on GitHub
↑↓ navigate ↵ open esc close