Sociopilots

Open-Source AI Documentation

Technical guides for developers integrating open-source AI into Sociopilots. Learn the API, self-hosted deployment, AI features, and architecture.

Quick Start

Self-Hosted Deployment

Deploy Sociopilots on your own server using Docker. Takes 10 minutes.

# Clone the repository
git clone https://github.com/CodeWithSakthivel/sociopilots.git
cd sociopilots

# Copy environment config
cp .env.example .env

# Start with Docker
docker compose up -d

Managed Hosting

Use our managed hosting at sociopilots.com for zero infrastructure management.

GraphQL API

Sociopilots exposes a GraphQL API for programmatic access to posts, accounts, and scheduling.

Create a Post

Schedule a post to one or more connected accounts.

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    content
    scheduledAt
    channels {
      id
      platform
      status
    }
  }
}

# Variables
{
  "input": {
    "content": "Check out our new scheduler!",
    "scheduledAt": "2024-01-15T09:00:00Z",
    "channels": ["channel-x-123", "channel-linkedin-456"],
    "autoComment": {
      "content": "Learn more: https://sociopilots.com"
    }
  }
}

List Connected Accounts

Retrieve all connected social media accounts.

query ListAccounts {
  accounts {
    id
    platform
    username
    connected_at
    status
  }
}

Webhook Events

Subscribe to events when posts publish or fail.

POST /webhooks/subscribe

{
  "event": "post.published",
  "url": "https://yourapp.com/webhooks/events",
  "secret": "your-secret-key"
}

# Webhook payload
{
  "event": "post.published",
  "timestamp": "2024-01-15T09:00:00Z",
  "post": {
    "id": "post-123",
    "channels": ["channel-x-123"],
    "status": "published"
  }
}

OAuth Integration

Connect social media accounts securely using OAuth 2.0. Sociopilots never requests or stores user passwords.

Step 1: Initiate OAuth Flow

Redirect users to the OAuth authorization URL.

GET https://sociopilots.com/oauth/authorize?
  client_id=YOUR_CLIENT_ID&
  redirect_uri=https://yourapp.com/callback&
  scope=post:create post:read account:read&
  state=random_state_string

Step 2: Exchange Code for Token

After user authorizes, exchange the code for an access token.

POST https://sociopilots.com/oauth/token

{
  "grant_type": "authorization_code",
  "code": "AUTH_CODE_FROM_CALLBACK",
  "client_id": "YOUR_CLIENT_ID",
  "client_secret": "YOUR_CLIENT_SECRET",
  "redirect_uri": "https://yourapp.com/callback"
}

# Response
{
  "access_token": "eyJhbGc...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "refresh_eyJhbGc..."
}

Step 3: Use Token for API Calls

Include the access token in API requests.

curl -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"query": "{ accounts { id username } }"}' \
  https://sociopilots.com/graphql

Architecture

Sociopilots is built with modern, scalable technology.

Backend

Node.js + GraphQL API. Background job queue for post scheduling. PostgreSQL database for durability.

Frontend

React + Next.js. Dark mode support. Mobile-responsive design. Real-time post status updates via WebSocket.

Deployment

Docker containers. Self-hosted (any server) or managed (sociopilots.com). Scales horizontally via job queue.

Security

OAuth 2.0 for account connections. Encrypted tokens at rest. HTTPS only. Regular security audits. Open-source code auditable by anyone.

Documentation Topics

API Reference

Complete GraphQL API documentation with queries, mutations, and examples.

Deployment

Deploy Sociopilots with Docker, Kubernetes, or cloud platforms.

Need Help?

Full API documentation, deployment guides, and code examples are on GitHub. Questions? Contact us anytime.

View on GitHubContact Support