API documentation

1. Authentication

Create an API key on the Developer page. Send it on every request:

Authorization: Bearer sh_xxxxxxxx

To act for one of your end-users, add X-Profile-Id: prof_xxx (or your own ref). Without it you act on your own accounts.

2. Profiles & connecting accounts

POST https://social.hubsz.com/v1/profiles            {"ref":"user_123","name":"Kedai Ali"}
GET  https://social.hubsz.com/v1/profiles
DELETE https://social.hubsz.com/v1/profiles/{id}     (deletes all its accounts and data)

GET  https://social.hubsz.com/v1/connect/tiktok?profile_id=user_123&return_to=https://yourapp.com/done
→ {"url":"https://www.tiktok.com/v2/auth/authorize/?..."}   redirect your user there

After authorizing, the user returns to return_to?status=connected&platform=tiktok&profile_id=prof_…&accounts=1 (or status=error&error=…). return_to origins must be allowed on the Developer page.

3. Posting

GET  https://social.hubsz.com/v1/accounts                       (X-Profile-Id: user_123)
POST https://social.hubsz.com/v1/posts
{
  "account_ids": ["acc_..."],
  "text": "Hello!",
  "media": [{"url": "https://.../video.mp4"}],
  "schedule_at": "2026-11-01T21:00:00+08:00",
  "options": {
    "instagram": {"type": "reel"},
    "tiktok": {"mode": "direct", "privacy_level": "PUBLIC_TO_EVERYONE",
               "allow_comment": true, "allow_duet": false, "allow_stitch": false,
               "commercial": false, "is_aigc": false}
  }
}
GET  https://social.hubsz.com/v1/posts/{id}

TikTok compliance (required): before posting to TikTok, your UI must call tiktok_creator_info, show the creator's nickname/avatar, let the user pick privacy from privacy_level_options with no default, keep comment/duet/stitch off by default, offer commercial-content disclosure (Your brand / Branded content), and show TikTok's Music Usage Confirmation. Direct posts without a user-chosen privacy_level are rejected — use "mode":"draft" to send to the user's TikTok inbox instead.

4. Any tool via REST

POST https://social.hubsz.com/api/tools/{tool_name}     body = tool arguments (JSON)
GET  https://social.hubsz.com/api/tools                 list of tools with JSON schemas

5. Webhooks

Set your URL on the Developer page. We send POST JSON {"id","type","created_at","data"} with header X-SocialHub-Signature: sha256=HMAC_SHA256(secret, raw_body).

Events: post.published, post.failed, account.connected, account.reauth_required, message.received, comment.received.

6. MCP (AI agents)

https://social.hubsz.com/mcp                 + Authorization: Bearer sh_…  [+ X-Profile-Id]
https://social.hubsz.com/mcp/{key}           for clients that cannot send headers
https://social.hubsz.com/mcp/{key}/{profile}

Every tool below is exposed. agent_run gives a natural-language task to the AI agent team; each specialist agent can only use the tools of its own permission area.

7. Errors & limits

401 bad key · 402 plan limit reached · 403 missing platform permission or not allowed · 404 not found · 429 rate limit · 502 platform error. Body: {"error":"message"}.

Developer (owner only)

Accounts

Publishing

Comments

Inbox & webhooks

Analytics

Discovery

Ads (Meta and TikTok)

AI agents