GraphQL API Reference

Complete reference for Sociopilots GraphQL API. Queries, mutations, and real-world examples.

Authentication

All API requests require a Bearer token. Get one via OAuth or generate an API token from your dashboard.

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

Queries

accounts

List all connected social media accounts.

query {
  accounts {
    id
    platform
    username
    connected_at
    status
  }
}

posts

List scheduled or published posts with optional filters.

query {
  posts(
    status: "scheduled"
    limit: 10
    offset: 0
  ) {
    id
    content
    scheduled_at
    channels {
      id
      platform
      status
    }
  }
}

post

Get details for a specific post.

query {
  post(id: "post-123") {
    id
    content
    scheduled_at
    status
    auto_comment {
      id
      content
      status
    }
    channels {
      id
      platform
      status
      error_message
    }
  }
}

Mutations

createPost

Create and schedule a new post.

mutation {
  createPost(input: {
    content: "Check out Sociopilots!"
    scheduled_at: "2024-02-01T10:00:00Z"
    channels: ["channel-x-123", "channel-linkedin-456"]
    auto_comment: {
      content: "Learn more: https://sociopilots.com"
    }
  }) {
    id
    content
    scheduled_at
    channels {
      id
      platform
      status
    }
  }
}

updatePost

Update an existing post before it publishes.

mutation {
  updatePost(id: "post-123", input: {
    content: "Updated content"
    scheduled_at: "2024-02-01T11:00:00Z"
  }) {
    id
    content
    scheduled_at
    status
  }
}

deletePost

Delete a scheduled post before it publishes.

mutation {
  deletePost(id: "post-123") {
    id
    deleted_at
  }
}

disconnectAccount

Disconnect a social media account.

mutation {
  disconnectAccount(id: "channel-x-123") {
    id
    platform
    disconnected_at
  }
}

Error Handling

GraphQL errors include a code and message. Handle them gracefully in your client.

Authentication Error

{
  "errors": [
    {
      "message": "Unauthorized",
      "extensions": {
        "code": "UNAUTHENTICATED"
      }
    }
  ]
}

Validation Error

{
  "errors": [
    {
      "message": "Invalid input",
      "extensions": {
        "code": "BAD_USER_INPUT",
        "field": "scheduled_at",
        "reason": "Must be in the future"
      }
    }
  ]
}

Rate Limit Error

{
  "errors": [
    {
      "message": "Too many requests",
      "extensions": {
        "code": "RATE_LIMITED",
        "retry_after": 60
      }
    }
  ]
}

Rate Limits

API rate limits prevent abuse. Plan your integrations accordingly.

Free Tier

100 requests/hour

Pro Tier

1,000 requests/hour

Enterprise

Custom limits available

API Integration Support

Have questions about the API? Need help with integration? Our team is here to assist.

Contact Support Back to Docs