SocialDock API Documentation

API Documentation

Getting Started

Quick Start

Get your first post published via the SocialDock API in three steps.

Get your API key

Navigate to Dashboard → Settings → API and click Generate new key. Keys are prefixed sd_live_ for production. Copy it immediately — it will not be shown again. Keys expire after 30 days and can be renewed from the same settings page.

FREE plan users: API access requires a BUILD, ACCELERATE, or UNLIMITED plan.

Connect a social account

Initiate an OAuth connection to get a connect URL, then redirect your user to it. After authorization, the account appears under GET /api/v1/accounts.

curl -X POST https://www.socialdock.dev/api/v1/accounts/connect \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "instagram",
    "redirect_url": "https://yourapp.com/oauth/callback"
  }'

{
  "data": {
    "connect_url": "https://oauth.socialdock.com/connect?token=...",
    "token": "tok_01hx...",
    "expires_at": "2026-03-26T13:00:00Z",
    "platform": "instagram"
  }
}

Create a post

Use the account_id from the previous step to publish immediately or schedule for later.

curl -X POST https://www.socialdock.dev/api/v1/posts \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Hello from SocialDock!",
    "targets": [
      {
        "platform": "instagram",
        "account_id": "acc_01hx..."
      }
    ],
    "publish_now": true
  }'

{
  "data": {
    "post_id": "post_01hy...",
    "status": "published",
    "targets": [
      {
        "platform": "instagram",
        "status": "published",
        "platform_post_id": "17854..."
      }
    ]
  }
}

Authentication

All API requests require an Authorization header with a Bearer token.

Property	Value
Header name	Authorization
Format	Bearer sd_live_xxxx...
Key prefix	sd_live_ (production) · sd_test_ (sandbox)
Expiry	30 days — renewable from Dashboard → Settings → API
Generated in	Dashboard → Settings → API

# Include this header with every request
Authorization: Bearer sd_live_xxxx...

Keep your key secret. Never expose it in client-side code or public repositories. Rotate it immediately from Settings → API if compromised.

Rate Limits

Rate limits are enforced per workspace, per minute. Exceeding the limit returns HTTP 429.

Plan	Requests / min	API Access
FREE	—	No API access
BUILD	100	Enabled
ACCELERATE	500	Enabled
UNLIMITED	1,000	Enabled

Rate limit response headers

Every response includes these headers:

Header	Description
X-RateLimit-Limit	Max requests allowed per window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	Unix timestamp when the window resets

API Reference

Base URL: https://www.socialdock.dev

Accounts

Manage social media accounts connected to your workspace. The OAuth connect flow initiates from your server — never expose the API key in client-side code.

POST/api/v1/accounts/connectInitiate OAuth connection for a platform

GET/api/v1/accountsList all connected accounts

GET/api/v1/accounts/statusGet status for a specific platform

DELETE/api/v1/accounts/{id}Disconnect an account

POST /api/v1/accounts/connect

Returns a short-lived OAuth URL. Redirect the user to connect_url to complete authorization.

Request body

platformstring

Target platform slug. One of: facebook, instagram, linkedin, threads, tiktok, reddit, telegram, youtube.

redirect_urlstring

URL to redirect the user to after OAuth completes.

curl -X POST https://www.socialdock.dev/api/v1/accounts/connect \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "platform": "youtube",
    "redirect_url": "https://yourapp.com/oauth/callback"
  }'

{
  "data": {
    "connect_url": "https://oauth.socialdock.com/connect?token=...",
    "token": "tok_01hx...",
    "expires_at": "2026-03-26T13:00:00Z",
    "platform": "youtube"
  }
}

GET /api/v1/accounts

curl -X GET https://www.socialdock.dev/api/v1/accounts \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "accounts": [
      {
        "id": "acc_01hx...",
        "platform": "instagram",
        "username": "@yourbrand",
        "display_name": "Your Brand",
        "connected_at": "2026-01-15T10:30:00Z"
      }
    ]
  }
}

GET /api/v1/accounts/status

Filter by platform using the platform query parameter.

curl -X GET "https://www.socialdock.dev/api/v1/accounts/status?platform=youtube" \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "accounts": [ { "id": "acc_01hx...", "status": "active" } ],
    "connected_platforms": ["youtube", "instagram"]
  }
}

DELETE /api/v1/accounts/{id}

curl -X DELETE https://www.socialdock.dev/api/v1/accounts/acc_01hx... \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": { "success": true }
}

Posts

Publish or schedule content to one or more connected platform accounts simultaneously.

POST/api/v1/postsCreate and publish or schedule a post

GET/api/v1/postsList posts with optional filters

GET/api/v1/posts/{id}Retrieve a single post

PUT/api/v1/posts/{id}Update a scheduled post

DELETE/api/v1/posts/{id}Delete a post

POST /api/v1/posts

Request body

textstringrequired

Post body text.

titlestring

Title (required for YouTube, Reddit).

targetsarrayrequired

Array of target objects. Each target has platform, account_id, and optional metadata.

media_urlsstring[]

Array of public media URLs to attach. For X/Twitter targets, only the first URL is used (appended as a link, which X unfurls into a preview card) — native multi-image and video attachment on X isn't supported yet, unlike Instagram, Facebook, and the other platforms.

tagsstring[]

Hashtags or labels to attach to the post.

scheduled_atstring

ISO 8601 datetime to publish at. Ignored when publish_now is true.

publish_nowboolean

Publish immediately. Defaults to true.

curl -X POST https://www.socialdock.dev/api/v1/posts \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Check out our latest update!",
    "title": "Q1 Product Update",
    "targets": [
      {
        "platform": "instagram",
        "account_id": "acc_01hx...",
        "metadata": { "location": "New York" }
      },
      {
        "platform": "linkedin",
        "account_id": "acc_01hy..."
      }
    ],
    "media_urls": ["https://example.com/image.jpg"],
    "tags": ["update", "product"],
    "publish_now": true
  }'

{
  "data": {
    "post_id": "post_01hz...",
    "status": "published",
    "targets": [
      {
        "platform": "instagram",
        "status": "published",
        "platform_post_id": "17854..."
      },
      {
        "platform": "linkedin",
        "status": "published",
        "platform_post_id": "urn:li:share:..."
      }
    ]
  }
}

Example — Schedule a post

curl -X POST https://www.socialdock.dev/api/v1/posts \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Dropping something big tomorrow!",
    "targets": [
      { "platform": "instagram", "account_id": "acc_01hx..." }
    ],
    "publish_now": false,
    "scheduled_at": "2026-04-01T09:00:00Z"
  }'

{
  "data": {
    "post_id": "post_01ha...",
    "status": "scheduled",
    "targets": [
      { "platform": "instagram", "status": "scheduled" }
    ]
  }
}

GET /api/v1/posts

Supports query parameters: status (published | scheduled | failed), platform, limit (default 20), offset (default 0).

curl -X GET "https://www.socialdock.dev/api/v1/posts?status=published&platform=instagram&limit=20&offset=0" \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "posts": [
      {
        "id": "post_01hz...",
        "status": "published",
        "text": "Check out our latest update!",
        "created_at": "2026-03-26T10:00:00Z"
      }
    ]
  },
  "meta": { "total": 42, "limit": 20, "offset": 0 }
}

GET /api/v1/posts/{id}

curl -X GET https://www.socialdock.dev/api/v1/posts/post_01hz... \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "id": "post_01hz...",
    "body": "Check out our latest update!",
    "status": "published",
    "targets": [
      { "platform": "instagram", "status": "published", "platform_post_id": "17854..." }
    ],
    "media": [
      { "id": "med_01hz...", "url": "https://cdn.socialdock.com/med_01hz.jpg" }
    ]
  }
}

PUT /api/v1/posts/{id}

Only scheduled posts can be updated. Fields are optional — supply only what you want to change.

curl -X PUT https://www.socialdock.dev/api/v1/posts/post_01ha... \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "text": "Updated caption for the drop!",
    "scheduled_at": "2026-04-01T12:00:00Z"
  }'

{
  "data": {
    "post": {
      "id": "post_01ha...",
      "text": "Updated caption for the drop!",
      "scheduled_at": "2026-04-01T12:00:00Z",
      "status": "scheduled"
    }
  }
}

DELETE /api/v1/posts/{id}

curl -X DELETE https://www.socialdock.dev/api/v1/posts/post_01hz... \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": { "success": true }
}

Post Analytics

Retrieve per-platform engagement metrics for a specific post.

GET/api/v1/posts/{id}/analyticsGet engagement metrics for a post

curl -X GET https://www.socialdock.dev/api/v1/posts/post_01hz.../analytics \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "post_id": "post_01hz...",
    "targets": [
      {
        "platform": "instagram",
        "metrics": {
          "views": 4820,
          "likes": 312,
          "comments": 47,
          "shares": 28
        }
      },
      {
        "platform": "linkedin",
        "metrics": {
          "views": 1204,
          "likes": 89,
          "comments": 11,
          "shares": 6
        }
      }
    ]
  }
}

Account Analytics

Retrieve follower and growth metrics for a connected account.

GET/api/v1/accounts/{id}/analyticsGet metrics for a connected account

curl -X GET https://www.socialdock.dev/api/v1/accounts/acc_01hx.../analytics \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "platform": "instagram",
    "metrics": {
      "followers": 12480,
      "following": 310,
      "posts": 184,
      "followers_growth_pct": 3.2,
      "avg_engagement_rate": 4.7
    },
    "fetched_at": "2026-03-26T10:00:00Z"
  }
}

Workspace Analytics

High-level overview of all publishing activity across your workspace.

GET/api/v1/analytics/overviewWorkspace-wide publishing summary

Accepts a period query parameter: 7d, 30d (default), 90d.

curl -X GET "https://www.socialdock.dev/api/v1/analytics/overview?period=30d" \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "summary": {
      "total_posts": 84,
      "success_rate": 98.8
    },
    "platforms": {
      "instagram": { "posts": 32, "total_reach": 94200 },
      "linkedin":  { "posts": 28, "total_reach": 31000 },
      "youtube":   { "posts": 24, "total_reach": 187000 }
    },
    "recent_posts": [
      {
        "post_id": "post_01hz...",
        "status": "published",
        "published_at": "2026-03-25T09:00:00Z"
      }
    ]
  }
}

Media

Upload media assets by providing a publicly accessible URL. SocialDock fetches, validates, and stores the asset. Use the returned url in post requests.

POST/api/v1/mediaUpload media from a public URL

Request body

urlstringrequired

Publicly accessible URL of the media asset.

file_namestring

Optional custom file name to store under.

curl -X POST https://www.socialdock.dev/api/v1/media \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://example.com/product-photo.jpg",
    "file_name": "product-photo.jpg"
  }'

{
  "data": {
    "id": "med_01hz...",
    "url": "https://cdn.socialdock.com/med_01hz.jpg",
    "mime_type": "image/jpeg"
  }
}

Webhooks

Receive real-time event notifications by registering a webhook endpoint. SocialDock sends a signed HTTP POST to your URL for each subscribed event.

POST/api/v1/webhooksRegister a new webhook

GET/api/v1/webhooksList registered webhooks

DELETE/api/v1/webhooks/{id}Delete a webhook

POST /api/v1/webhooks

Request body

urlstringrequired

HTTPS endpoint to receive events.

eventsstring[]required

Array of event names to subscribe to.

secretstring

Secret used to sign payloads with HMAC-SHA256. Recommended.

curl -X POST https://www.socialdock.dev/api/v1/webhooks \
  -H "Authorization: Bearer sd_live_xxxx..." \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://yourapp.com/webhooks/socialdock",
    "events": ["post_published", "post_failed"],
    "secret": "your_signing_secret"
  }'

{
  "data": {
    "id": "wh_01hz...",
    "url": "https://yourapp.com/webhooks/socialdock",
    "events": ["post_published", "post_failed"],
    "active": true
  }
}

GET /api/v1/webhooks

curl -X GET https://www.socialdock.dev/api/v1/webhooks \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": {
    "webhooks": [
      {
        "id": "wh_01hz...",
        "url": "https://yourapp.com/webhooks/socialdock",
        "events": ["post_published", "post_failed"],
        "active": true
      }
    ]
  }
}

DELETE /api/v1/webhooks/{id}

curl -X DELETE https://www.socialdock.dev/api/v1/webhooks/wh_01hz... \
  -H "Authorization: Bearer sd_live_xxxx..."

{
  "data": { "success": true }
}

Supported events

Event	Triggered when
post_published	A post is successfully published to a platform
post_failed	Publishing fails after all retries are exhausted

Signature verification (HMAC-SHA256)

Every webhook request includes an X-SocialDock-Signature header. Verify it to ensure the payload is authentic:

// Node.js / Express
const crypto = require("crypto");

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

app.post("/webhooks/socialdock", (req, res) => {
  const sig = req.headers["x-socialdock-signature"];
  const valid = verifyWebhook(req.rawBody, sig, process.env.WEBHOOK_SECRET);
  if (!valid) return res.status(401).send("Invalid signature");
  // process event ...
  res.sendStatus(200);
});

MCP Server

SocialDock ships a hosted Model Context Protocol server, so AI assistants like Claude, Cursor, and any other MCP client can publish and schedule posts on your behalf. It uses the same API keys, rate limits, and plan rules as the REST API.

Endpoint (Streamable HTTP transport):

https://www.socialdock.dev/api/mcp

Easiest — OAuth (no key needed): paste the endpoint URL into claude.ai custom connectors, ChatGPT developer mode, or Cursor and you'll be prompted to sign in to SocialDock and approve access. Dynamic client registration and PKCE are handled automatically.

Or with an API key — send it as a header on every request:

Authorization: Bearer sd_live_xxxx...

Add it to Claude Code:

claude mcp add socialdock https://www.socialdock.dev/api/mcp \
  --transport http \
  --header "Authorization: Bearer sd_live_xxxx..."

Or configure it in any client that accepts JSON MCP config:

{
  "mcpServers": {
    "socialdock": {
      "type": "http",
      "url": "https://www.socialdock.dev/api/mcp",
      "headers": {
        "Authorization": "Bearer sd_live_xxxx..."
      }
    }
  }
}

Tool	Description
list_accounts	List connected social accounts and their account_id values
create_post	Create a post — publish now, schedule, or save as draft
list_posts	List posts with per-platform delivery status
get_post	Fetch a single post with target statuses and media
update_post	Edit or reschedule a draft/scheduled post
delete_post	Delete a non-published post

Example prompt once connected: "Post 'Big launch on Friday!' to my Facebook page and LinkedIn now, and schedule the same text for my X account tomorrow at 9am."

Errors

All errors follow the same envelope. The data field will be null and error will be populated.

{
  "data": null,
  "error": {
    "message": "Account not found",
    "details": "No account with id acc_01hx... exists in this workspace."
  },
  "meta": {}
}

Status	Meaning	Common cause
400	Bad Request	Invalid or missing request body fields
401	Unauthorized	Missing or invalid API key
403	Forbidden	Valid key but insufficient plan or permissions
404	Not Found	Resource does not exist in this workspace
429	Too Many Requests	Rate limit exceeded — check X-RateLimit-Reset
500	Internal Server Error	Unexpected server error — contact support

Example — 401 Unauthorized

{
  "data": null,
  "error": {
    "message": "Unauthorized",
    "details": "The provided API key is invalid or has been revoked."
  },
  "meta": {}
}

Example — 429 Rate Limited

{
  "data": null,
  "error": {
    "message": "Too Many Requests",
    "details": "Rate limit of 100 requests/min exceeded. Retry after 2026-03-26T12:01:00Z."
  },
  "meta": {
    "retry_after": "2026-03-26T12:01:00Z"
  }
}

Platform Notes

Platform-specific requirements and capabilities. Pass additional fields via targets[].metadata.

Platform	Text	Images	Video	Carousel	Scheduling	Analytics
Facebook	✓	✓	✓	✓	✓	✓
Instagram	✓	✓	✓	✓	✓	✓
LinkedIn	✓	✓	✓	✗	✓	✓
Threads	✓	✓	✗	✗	✓	✗
TikTok	✗	✗	✓	✗	✓	✓
Reddit	✓	✓	✗	✗	✓	✗
Telegram	✓	✓	✓	✗	✓	✗
YouTube	✓	✗	✓	✗	✓	✓

YouTube

Requires a video attachment and a title. Pass video privacy via metadata.privacy (public | unlisted | private).

Requires a title and a metadata.subreddit value (e.g. r/programming).

TikTok

Video-only. Pass metadata.privacy_level (PUBLIC_TO_EVERYONE | MUTUAL_FOLLOW_FRIENDS | FOLLOWER_OF_CREATOR | SELF_ONLY).

Pass metadata.chat_id to target a specific channel or group. Supports Markdown in text.

Platform capabilities may change as upstream APIs evolve. Check the changelog below for updates.

Changelog

A history of API changes. Backwards-incompatible changes will be announced with a deprecation period.

v1.0.0March 2026Initial release

First public release of the SocialDock REST API.

POST /api/v1/accounts/connect — initiate OAuth
GET /api/v1/accounts — list connected accounts
GET /api/v1/accounts/status — platform connection status
DELETE /api/v1/accounts/{id} — disconnect account
POST /api/v1/posts — create / publish / schedule
GET/PUT/DELETE /api/v1/posts, /api/v1/posts/{id}
GET /api/v1/posts/{id}/analytics — post engagement metrics
GET /api/v1/accounts/{id}/analytics — account-level metrics
GET /api/v1/analytics/overview — workspace summary
POST /api/v1/media — media upload via URL
POST/GET/DELETE /api/v1/webhooks

Need help?

If you run into any issues or have questions about the API, reach out to our team.

Contact Support

Quick Start

Get your API key

Connect a social account

Create a post

Authentication

Rate Limits

Rate limit response headers

API Reference

Accounts

POST /api/v1/accounts/connect

GET /api/v1/accounts

GET /api/v1/accounts/status

DELETE /api/v1/accounts/{id}

Posts

POST /api/v1/posts

Example — Schedule a post

GET /api/v1/posts

GET /api/v1/posts/{id}

PUT /api/v1/posts/{id}

DELETE /api/v1/posts/{id}

Post Analytics

Account Analytics

Workspace Analytics

Media

Webhooks

POST /api/v1/webhooks

GET /api/v1/webhooks

DELETE /api/v1/webhooks/{id}

Supported events

Signature verification (HMAC-SHA256)

MCP Server

Errors

Example — 401 Unauthorized

Example — 429 Rate Limited

Platform Notes

YouTube

Reddit

TikTok

Telegram

Changelog

Need help?