API Reference

Build on top of SwarmPost

Integrate SwarmPost into your workflow with our REST API. Schedule posts, manage agents, pull analytics, and receive real-time webhook events programmatically.

Authentication

All API requests require a Bearer token in the Authorization header. Generate your API key from Dashboard → Settings → API Keys.

Authorization Header

Authorization: Bearer sk_live_your_api_key_here

Important: Keep your API key secret. Never expose it in client-side code or public repositories. Requests without a valid key receive 401 Unauthorized.

Base URL

All endpoints are relative to the base URL:

https://swarmpost.io/api/v1

Rate Limits

API rate limits depend on your plan. Rate limit headers are included in every response.

Plan	Requests / month
Creator (Free)	No API access
Pro	1,000 / month
Business	50,000 / month
Agency	500,000 / month

Headers returned: X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset.

Endpoints

Overview of all available endpoints:

GET    /api/v1/posts          List posts
POST   /api/v1/posts          Create a post
GET    /api/v1/accounts       List connected accounts
GET    /api/v1/analytics      Get analytics data
GET    /api/v1/agents         List agents
POST   /api/v1/agents         Create an agent

Posts

GET/api/v1/posts

List all posts for your workspace. Supports pagination via limit and offset query parameters.

Example Request

curl -X GET "https://swarmpost.io/api/v1/posts?workspaceId=123&limit=50&offset=0" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example Response

{
  "posts": [
    {
      "id": 1,
      "workspaceId": 123,
      "status": "scheduled",
      "scheduledAt": "2026-04-10T14:00:00.000Z",
      "createdAt": "2026-04-06T10:00:00.000Z"
    }
  ],
  "total": 42,
  "limit": 50,
  "offset": 0
}

POST/api/v1/posts

Create a new post with one or more platform variants. Set status to 'scheduled' with a scheduledAt timestamp to publish later.

Example Request

curl -X POST "https://swarmpost.io/api/v1/posts" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": 123,
    "status": "scheduled",
    "scheduledAt": "2026-04-10T14:00:00.000Z",
    "variants": [
      {
        "socialAccountId": 1,
        "content": "Exciting update coming soon!",
        "mediaUrls": ["https://example.com/image.jpg"]
      }
    ]
  }'

Example Response

{
  "post": {
    "id": 42,
    "workspaceId": 123,
    "status": "scheduled",
    "scheduledAt": "2026-04-10T14:00:00.000Z",
    "createdAt": "2026-04-06T10:00:00.000Z"
  }
}

Social Accounts

GET/api/v1/accounts

List all connected social accounts for a workspace. Tokens and secrets are never included in the response.

Example Request

curl -X GET "https://swarmpost.io/api/v1/accounts?workspaceId=123" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example Response

{
  "accounts": [
    {
      "id": 1,
      "platform": "twitter",
      "platformUsername": "@swarmpost",
      "displayName": "SwarmPost",
      "isActive": true
    },
    {
      "id": 2,
      "platform": "instagram",
      "platformUsername": "swarmpost",
      "displayName": "SwarmPost",
      "isActive": true
    }
  ]
}

Analytics

GET/api/v1/analytics

Get dashboard analytics including post counts, engagement metrics, and platform breakdowns for a workspace.

Example Request

curl -X GET "https://swarmpost.io/api/v1/analytics?workspaceId=123&period=30d" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example Response

{
  "analytics": {
    "totalPosts": 150,
    "publishedThisWeek": 12,
    "totalImpressions": 45000,
    "totalEngagements": 3200,
    "engagementRate": 7.1,
    "topPlatform": "twitter",
    "platformBreakdown": {
      "twitter": { "posts": 45, "impressions": 18000 },
      "instagram": { "posts": 38, "impressions": 12000 },
      "linkedin": { "posts": 22, "impressions": 8500 }
    }
  }
}

Agents

GET/api/v1/agents

List all AI agents configured for a workspace, including their type, schedule, and last run time.

Example Request

curl -X GET "https://swarmpost.io/api/v1/agents?workspaceId=123" \
  -H "Authorization: Bearer sk_live_your_api_key_here"

Example Response

{
  "agents": [
    {
      "id": 1,
      "name": "Content Creator",
      "type": "content",
      "isActive": true,
      "schedule": "0 9 * * 1-5",
      "lastRunAt": "2026-04-06T09:00:00.000Z"
    },
    {
      "id": 2,
      "name": "Engagement Bot",
      "type": "engagement",
      "isActive": true,
      "schedule": "*/30 * * * *",
      "lastRunAt": "2026-04-06T11:30:00.000Z"
    }
  ]
}

POST/api/v1/agents

Create a new AI agent or update an existing agent's configuration and active state.

Example Request

curl -X POST "https://swarmpost.io/api/v1/agents" \
  -H "Authorization: Bearer sk_live_your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "workspaceId": 123,
    "name": "SEO Optimizer",
    "type": "seo",
    "schedule": "0 8 * * *",
    "isActive": true,
    "config": {
      "targetPlatforms": ["twitter", "linkedin"],
      "aiProvider": "claude"
    }
  }'

Example Response

{
  "agent": {
    "id": 3,
    "name": "SEO Optimizer",
    "type": "seo",
    "isActive": true,
    "schedule": "0 8 * * *",
    "nextRunAt": "2026-04-07T08:00:00.000Z"
  }
}

Webhooks

Receive real-time notifications when events occur in your workspace. Configure webhook endpoints in Dashboard → Settings → Webhooks. All webhook payloads are signed with HMAC-SHA256 for verification.

Available Events

Event	Description
`post.published`	A scheduled post was successfully published to a platform.
`post.failed`	A scheduled post failed to publish (includes error details).
`agent.action`	An AI agent completed a task (content creation, engagement, SEO).
`agent.error`	An AI agent encountered an error during execution.
`inbox.new`	A new comment, mention, DM, or reply was received.
`account.disconnected`	A social account was disconnected or its token expired.

Signature Verification

Every webhook includes an X-SwarmPost-Signature header with an HMAC-SHA256 signature of the raw request body, computed with your webhook secret. Always verify this signature before processing payloads.

Verify Signature (Node.js)

const crypto = require("crypto");

function verifyWebhook(body, signature, secret) {
  const expected = "sha256=" + crypto
    .createHmac("sha256", secret)
    .update(body)
    .digest("hex");
  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expected)
  );
}

Example Payload

post.published event

{
  "event": "post.published",
  "data": {
    "postId": 42,
    "variantId": 101,
    "platform": "twitter",
    "content": "Check out our latest update!",
    "platformUrl": "https://twitter.com/swarmpost/status/123456",
    "platformPostId": "123456"
  },
  "timestamp": "2026-04-06T14:00:00.000Z"
}

Ready to build?

Create an account, generate your API key, and start integrating in minutes.

Get Started Free View Integrations