Get started

Quickstart

Connect an account, create an API key and publish your first post.

Five steps from a new account to a published post. You’ll need a terminal with curl, or any HTTP client.

1. Create an account

2. Connect a social account

Open Accounts in the dashboard and pick a platform. Most sign in with the platform’s own screen; a few ask for an app password, bot token or webhook URL and show you where to find it. See Connecting accounts.

3. Create an API key

Open Developers and create a key. It starts with sh_ and is shown once, so store it now, for example as an environment variable:

export SOCIALHELPER_API_KEY="sh_…"

4. Find the account ID

List your connected accounts. Use the id of each account you want to post to.

curl https://socialhelper.app/api/v1/accounts \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY"

{
    "data": [
        {
            "id": "01JA8Z…",
            "object": "account",
            "platform": "bluesky",
            "name": "Jane Doe",
            "username": "jane.bsky.social",
            "avatar_url": "https://…",
            "profile_url": "https://bsky.app/profile/jane.bsky.social",
            "status": "active",
            "status_reason": null,
            "can_publish": true,
            "tools": [],
            "connected_at": "2026-10-10T18:00:00Z",
            "last_published_at": null
        }
    ]
}

Only accounts with status active and can_publish true can receive posts.

5. Publish

Send the text and the account IDs. The Idempotency-Key header makes a retried request return the same post instead of creating another.

curl https://socialhelper.app/api/v1/posts \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID_1",
          "ACCOUNT_ID_2"
      ]
  }'

const response = await fetch("https://socialhelper.app/api/v1/posts", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.SOCIALHELPER_API_KEY}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({
      "text": "We just shipped dark mode. Try it tonight 🌙",
      "accounts": [
          "ACCOUNT_ID_1",
          "ACCOUNT_ID_2"
      ]
  }),
});

const { data: post } = await response.json();
console.log(post.status, post.targets);

import os, uuid, requests

response = requests.post(
    "https://socialhelper.app/api/v1/posts",
    headers={
        "Authorization": f"Bearer {os.environ['SOCIALHELPER_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),
    },
    json={
        "text": "We just shipped dark mode. Try it tonight 🌙",
        "accounts": ["ACCOUNT_ID_1", "ACCOUNT_ID_2"],
    },
)

post = response.json()["data"]
print(post["status"], post["targets"])

You get the post back with a 201 status and one target per account. Each target moves through queued, publishing and published, or failed with an error. When it’s live, the target’s url links to the post.

curl https://socialhelper.app/api/v1/posts/POST_ID \
  -H "Authorization: Bearer $SOCIALHELPER_API_KEY"