Skip to main content

Public API Overview

Getting started with the Sipstory Public API

tip

For N8N, check out this video: https://www.youtube.com/watch?v=c50u3K3xsCI

SDKs & Integrations​

NodeJS SDK

Official Sipstory NodeJS SDK

n8n Node

Custom n8n node for Sipstory

Authentication​

There are two ways to authenticate with the Sipstory API:

API Key​

Get your API key from Settings > Developers > Public API. Include it in the Authorization header:

curl -H "Authorization: your-api-key" https://api.sipstory.tech/public/v1/integrations

OAuth2 Token​

If you're building an app for other Sipstory users, use OAuth2 Authentication to get tokens that act on behalf of users. OAuth tokens start with pos_ and are used the same way:

curl -H "Authorization: pos_your-oauth-token" https://api.sipstory.tech/public/v1/integrations

Base URL​

EnvironmentBase URL
Sipstory Webhttps://api.sipstory.tech/public/v1

Rate Limits​

info

30 requests per hour limit applies to all endpoints.

This doesn't mean you can only post 30 times per hour—each API call counts as one request. Schedule multiple posts in a single request to maximize throughput.

Terminology​

note

The Sipstory UI uses the term channel, while the API uses integration. They refer to the same thing—a connected social media account.

Generate Output​

The easiest way to generate your post payloads is by using this wizard. It's the same wizard to schedule posts in the Sipstory app, however instead of scheduling posts, it generates the JSON payload for you to use in your API requests.

  • For web, make sure you are logged in.

Open in full screen

Supported Platforms (20 total)​

When creating posts, each social media platform has its own settings schema. The settings object must include a __type field matching the provider.

Platforms with custom settings (20)​

Platform__typeKey settings
X (Twitter)xwho_can_reply_post, community
LinkedInlinkedinpost_as_images_carousel
LinkedIn Pagelinkedin-pagepost_as_images_carousel
Facebookfacebookurl (optional)
Instagram (FB-linked)instagrampost_type, collaborators
Instagram Standaloneinstagram-standalonepost_type, collaborators
Warpcast (Farcaster)warpcastsubreddit[] (channels)

Platforms without custom settings (7)​

These platforms only require { "__type": "platform-name" }:

Platform__type
Threadsthreads
Mastodonmastodon
Blueskybluesky
Telegramtelegram
Nostrnostr
VKvk
Kickkick

codeView Provider Settings Reference

See detailed settings schemas with examples for each platform

Quick Examples​

Schedule a post to X (Twitter)​

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-integration-id" },
      "value": [
        {
          "content": "Hello from the Sipstory API! 🚀",
          "image": []
        }
      ],
      "settings": {
        "__type": "x",
        "who_can_reply_post": "everyone"
      }
    }
  ]
}

Post immediately to LinkedIn​

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-linkedin-id" },
      "value": [
        {
          "content": "Exciting announcement! 🎉",
          "image": []
        }
      ],
      "settings": {
        "__type": "linkedin"
      }
    }
  ]
}

Upload an image and post to Instagram​

Upload Image to Sipstory
# Step 1: Upload the image
curl -X POST "https://api.sipstory.tech/public/v1/upload" \
  -H "Authorization: your-api-key" \
  -F "file=@photo.jpg"

# Response: { "id": "img-123", "path": "https://uploads.sipstory.tech/photo.jpg", ... }

# Step 2: Create the post with the uploaded image
curl -X POST "https://api.sipstory.tech/public/v1/posts" \
  -H "Authorization: your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "schedule",
    "date": "2024-12-14T10:00:00.000Z",
    "shortLink": false,
    "tags": [],
    "posts": [{
      "integration": { "id": "your-instagram-id" },
      "value": [{
        "content": "Beautiful sunset 🌅 #photography",
        "image": [{ "id": "img-123", "path": "https://uploads.sipstory.tech/photo.jpg" }]
      }],
      "settings": {
        "__type": "instagram",
        "post_type": "post"
      }
    }]
  }'

Publish a Medium article​

{
  "type": "now",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-medium-id" },
      "value": [
        {
          "content": "# Introduction\n\nThis is my article in markdown...",
          "image": []
        }
      ],
      "settings": {
        "__type": "medium",
        "title": "My Amazing Article",
        "subtitle": "A deep dive into something interesting",
        "tags": [
          { "value": "programming", "label": "Programming" }
        ]
      }
    }
  ]
}

Create a Google My Business offer​

{
  "type": "schedule",
  "date": "2024-12-14T10:00:00.000Z",
  "shortLink": false,
  "tags": [],
  "posts": [
    {
      "integration": { "id": "your-gmb-id" },
      "value": [
        {
          "content": "🎉 Holiday Sale! 20% off everything!",
          "image": []
        }
      ],
      "settings": {
        "__type": "gmb",
        "topicType": "OFFER",
        "callToActionType": "GET_OFFER",
        "callToActionUrl": "https://example.com/sale",
        "offerCouponCode": "HOLIDAY20"
      }
    }
  ]
}