openapi: 3.1.0
info:
title: Sipstory Public API
description: >-
API for managing social media posts, integrations, and media uploads in
Sipstory.
All endpoints require an API key passed in the `Authorization` header:
```
Authorization: your-api-key
```
Get your API key from Sipstory Settings.
There is a limit of **30 requests per hour**.
The UI uses `channel`, but the API uses `integration`. They refer to the
same thing.
**Social Platforms:** X (Twitter), LinkedIn, LinkedIn Page, Facebook,
Instagram, Instagram Standalone, Threads, Bluesky, Mastodon, Warpcast
(Farcaster), Nostr, VK
**Video Platforms:** YouTube, TikTok
**Community Platforms:** Reddit, Lemmy, Discord, Slack, Telegram
**Design Platforms:** Pinterest, Dribbble
**Blogging Platforms:** Medium, Dev.to, Hashnode, WordPress
**Business:** Google My Business (GMB), Listmonk (newsletters)
license:
name: MIT
version: 1.0.0
servers:
- url: https://api.sipstory.tech/public/v1
description: Sipstory Cloud
- url: https://{your-domain}/api/public/v1
description: Self-hosted
variables:
your-domain:
default: localhost:5000
description: Your Sipstory instance domain
security:
- ApiKeyAuth: []
tags:
- name: Integrations
description: Manage connected social media channels
- name: Posts
description: Create, list, and delete posts
- name: Uploads
description: Upload media files
- name: Notifications
description: View organization notifications
- name: Analytics
description: View analytics for integrations and posts
- name: Video Generation
description: Generate videos with AI
paths:
/posts:
post:
tags:
- Posts
summary: Create a post
description: >-
Create or schedule a new post. Each social media platform has its own
settings schema.
operationId: createPost
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/CreatePostRequest'
examples:
general:
summary: >-
General (Threads, Mastodon, Bluesky, Telegram, Nostr, VK,
Kick)
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-integration-id
value:
- content: Hello world!
image: []
settings:
__type: bluesky
x:
summary: X (Twitter)
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-x-integration-id
value:
- content: Hello from the Sipstory API!
image: []
settings:
__type: x
who_can_reply_post: everyone
community: ''
linkedin:
summary: LinkedIn
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-linkedin-integration-id
value:
- content: Check out our latest product showcase!
image: []
settings:
__type: linkedin
post_as_images_carousel: false
linkedin-page:
summary: LinkedIn Page
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-linkedin-page-integration-id
value:
- content: 'Company update: We just launched a new feature!'
image:
- id: img1
path: https://uploads.sipstory.tech/1.png
- id: img2
path: https://uploads.sipstory.tech/2.png
settings:
__type: linkedin-page
post_as_images_carousel: true
carousel_name: Product Showcase
instagram:
summary: Instagram
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-instagram-integration-id
value:
- content: Beautiful sunset today!
image:
- id: img1
path: https://uploads.sipstory.tech/photo.jpg
settings:
__type: instagram
post_type: post
is_trial_reel: false
collaborators: []
instagram-standalone:
summary: Instagram Standalone
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-instagram-standalone-integration-id
value:
- content: ''
image:
- id: story-img
path: https://uploads.sipstory.tech/story.jpg
settings:
__type: instagram-standalone
post_type: story
is_trial_reel: false
collaborators: []
youtube:
summary: YouTube
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-youtube-integration-id
value:
- content: Video description here...
image:
- id: video-id
path: https://uploads.sipstory.tech/video.mp4
settings:
__type: youtube
title: My Awesome Video
type: public
selfDeclaredMadeForKids: 'no'
tags:
- value: tutorial
label: tutorial
tiktok:
summary: TikTok
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-tiktok-integration-id
value:
- content: 'Check this out! #viral #fyp'
image:
- id: video-id
path: https://uploads.sipstory.tech/tiktok.mp4
settings:
__type: tiktok
privacy_level: PUBLIC_TO_EVERYONE
duet: true
stitch: true
comment: true
autoAddMusic: 'no'
brand_content_toggle: false
brand_organic_toggle: false
video_made_with_ai: false
content_posting_method: DIRECT_POST
reddit:
summary: Reddit
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-reddit-integration-id
value:
- content: Post content here...
image: []
settings:
__type: reddit
subreddit:
- value:
subreddit: programming
title: My Post Title
type: self
url: ''
is_flair_required: false
flair: null
lemmy:
summary: Lemmy
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-lemmy-integration-id
value:
- content: Post content here...
image: []
settings:
__type: lemmy
subreddit:
- value:
subreddit: technology
id: community-id
title: My Post Title
url: ''
pinterest:
summary: Pinterest
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-pinterest-integration-id
value:
- content: Pin description here...
image:
- id: pin-img
path: https://uploads.sipstory.tech/pin.jpg
settings:
__type: pinterest
board: board-id
title: My Pin
link: https://example.com
dribbble:
summary: Dribbble
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-dribbble-integration-id
value:
- content: Shot description here...
image:
- id: shot-img
path: https://uploads.sipstory.tech/shot.png
settings:
__type: dribbble
title: My Design Shot
discord:
summary: Discord
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-discord-integration-id
value:
- content: Hello Discord!
image: []
settings:
__type: discord
channel: channel-id
slack:
summary: Slack
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-slack-integration-id
value:
- content: Hello Slack!
image: []
settings:
__type: slack
channel: channel-id
twitch:
summary: Twitch
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-twitch-integration-id
value:
- content: Stream announcement!
image: []
settings:
__type: twitch
messageType: announcement
announcementColor: primary
medium:
summary: Medium
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-medium-integration-id
value:
- content: |-
This is my article content in markdown...
image: []
settings:
__type: medium
title: My Amazing Article
subtitle: A deep dive into...
tags:
- value: programming
label: Programming
devto:
summary: Dev.to
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-devto-integration-id
value:
- content: |-
Step-by-step guide...
image: []
settings:
__type: devto
title: Building APIs with Node.js
tags:
- value: javascript
label: javascript
- value: nodejs
label: nodejs
hashnode:
summary: Hashnode
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-hashnode-integration-id
value:
- content: |-
Article content here...
image: []
settings:
__type: hashnode
title: Getting Started with Sipstory
subtitle: A beginner's guide
publication: publication-id
tags:
- value: webdev
label: Web Development
wordpress:
summary: WordPress
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-wordpress-integration-id
value:
- content: Blog post content here...
image: []
settings:
__type: wordpress
title: My Blog Post
type: post
listmonk:
summary: Listmonk
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-listmonk-integration-id
value:
- content: Newsletter content here...
image: []
settings:
__type: listmonk
subject: Weekly Newsletter
preview: This week's highlights...
list: list-id
gmb:
summary: Google My Business
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-gmb-integration-id
value:
- content: Check out our latest offers!
image: []
settings:
__type: gmb
topicType: OFFER
callToActionType: GET_OFFER
callToActionUrl: https://example.com/offer
offerCouponCode: SAVE20
facebook:
summary: Facebook
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-facebook-integration-id
value:
- content: Hello Facebook!
image: []
settings:
__type: facebook
url: https://example.com
warpcast:
summary: Warpcast (Farcaster)
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-warpcast-integration-id
value:
- content: Hello Farcaster!
image: []
settings:
__type: warpcast
subreddit:
- value:
id: channel-id
moltbook:
summary: Moltbook
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-moltbook-integration-id
value:
- content: Hello Moltbook!
image: []
settings:
__type: moltbook
submolt: submolt-id
skool:
summary: Skool
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-skool-integration-id
value:
- content: Post content here...
image: []
settings:
__type: skool
group: group-id
label: label-id
title: My Skool Post
whop:
summary: Whop
value:
type: schedule
date: '2024-12-14T10:00:00.000Z'
shortLink: false
tags: []
posts:
- integration:
id: your-whop-integration-id
value:
- content: Post content here...
image: []
settings:
__type: whop
company: company-id
experience: experience-id
title: My Whop Post
responses:
'200':
description: Post created successfully
content:
application/json:
schema:
type: array
items:
type: object
properties:
postId:
type: string
integration:
type: string
example:
- postId: post-123
integration: integration-456
components:
schemas:
CreatePostRequest:
type: object
required:
- type
- date
- shortLink
- tags
properties:
type:
type: string
enum:
- draft
- schedule
- now
description: Post type
date:
type: string
format: date-time
description: Publish date in UTC ISO format
shortLink:
type: boolean
description: Whether to use short links
order:
type: string
description: Order of posts
inter:
type: number
description: Interval between posts
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
posts:
type: array
items:
$ref: '#/components/schemas/PostItem'
description: Required if type is not 'draft'
Tag:
type: object
required:
- value
- label
properties:
value:
type: string
label:
type: string
PostItem:
type: object
required:
- integration
- value
properties:
integration:
type: object
required:
- id
properties:
id:
type: string
description: Integration ID
value:
type: array
items:
$ref: '#/components/schemas/PostContent'
group:
type: string
description: Group ID for related posts
settings:
oneOf:
- $ref: '#/components/schemas/XSettings'
- $ref: '#/components/schemas/LinkedInSettings'
- $ref: '#/components/schemas/InstagramSettings'
- $ref: '#/components/schemas/FacebookSettings'
- $ref: '#/components/schemas/YouTubeSettings'
- $ref: '#/components/schemas/TikTokSettings'
- $ref: '#/components/schemas/RedditSettings'
- $ref: '#/components/schemas/LemmySettings'
- $ref: '#/components/schemas/PinterestSettings'
- $ref: '#/components/schemas/DiscordSettings'
- $ref: '#/components/schemas/SlackSettings'
- $ref: '#/components/schemas/TwitchSettings'
- $ref: '#/components/schemas/DribbbleSettings'
- $ref: '#/components/schemas/MediumSettings'
- $ref: '#/components/schemas/DevToSettings'
- $ref: '#/components/schemas/HashnodeSettings'
- $ref: '#/components/schemas/WordpressSettings'
- $ref: '#/components/schemas/ListmonkSettings'
- $ref: '#/components/schemas/GmbSettings'
- $ref: '#/components/schemas/WarpcastSettings'
- $ref: '#/components/schemas/MoltbookSettings'
- $ref: '#/components/schemas/SkoolSettings'
- $ref: '#/components/schemas/WhopSettings'
- $ref: '#/components/schemas/EmptySettings'
description: Provider-specific settings
PostContent:
type: object
required:
- content
properties:
content:
type: string
description: Post text content
id:
type: string
description: Post ID (for updates)
image:
type: array
items:
$ref: '#/components/schemas/Media'
XSettings:
title: X (Twitter)
type: object
required:
- __type
- who_can_reply_post
properties:
__type:
type: string
enum:
- x
description: Must be 'x'
who_can_reply_post:
type: string
enum:
- everyone
- following
- mentionedUsers
- subscribers
- verified
description: Who can reply to the post
community:
type: string
description: 'X Community URL (format: https://x.com/i/communities/123)'
LinkedInSettings:
title: LinkedIn
type: object
required:
- __type
properties:
__type:
type: string
enum:
- linkedin
- linkedin-page
description: Use 'linkedin' for profiles, 'linkedin-page' for company pages
post_as_images_carousel:
type: boolean
description: Display multiple images as a carousel
carousel_name:
type: string
description: Name for the carousel document
InstagramSettings:
title: Instagram
type: object
required:
- __type
- post_type
properties:
__type:
type: string
enum:
- instagram
- instagram-standalone
description: Use 'instagram' for FB-linked, 'instagram-standalone' for standalone
post_type:
type: string
enum:
- post
- story
description: Type of Instagram post
is_trial_reel:
type: boolean
description: Whether to post as a trial reel
graduation_strategy:
type: string
enum:
- MANUAL
- SS_PERFORMANCE
description: Graduation strategy for trial reels
collaborators:
type: array
items:
type: object
properties:
label:
type: string
description: Collaborator username
FacebookSettings:
title: Facebook
type: object
required:
- __type
description: Facebook post settings
properties:
__type:
type: string
enum:
- facebook
url:
type: string
format: uri
description: Optional link URL to include in the post
YouTubeSettings:
title: YouTube
type: object
required:
- __type
- title
- type
properties:
__type:
type: string
enum:
- youtube
title:
type: string
minLength: 2
maxLength: 100
description: Video title
type:
type: string
enum:
- public
- private
- unlisted
description: Video visibility
selfDeclaredMadeForKids:
type: string
enum:
- 'yes'
- 'no'
description: Made for kids declaration
thumbnail:
$ref: '#/components/schemas/Media'
description: Custom thumbnail
tags:
type: array
items:
$ref: '#/components/schemas/Tag'
TikTokSettings:
title: TikTok
type: object
required:
- __type
- privacy_level
- duet
- stitch
- comment
- autoAddMusic
- brand_content_toggle
- brand_organic_toggle
- content_posting_method
properties:
__type:
type: string
enum:
- tiktok
title:
type: string
maxLength: 90
privacy_level:
type: string
enum:
- PUBLIC_TO_EVERYONE
- MUTUAL_FOLLOW_FRIENDS
- FOLLOWER_OF_CREATOR
- SELF_ONLY
duet:
type: boolean
stitch:
type: boolean
comment:
type: boolean
autoAddMusic:
type: string
enum:
- 'yes'
- 'no'
brand_content_toggle:
type: boolean
brand_organic_toggle:
type: boolean
video_made_with_ai:
type: boolean
content_posting_method:
type: string
enum:
- DIRECT_POST
- UPLOAD
RedditSettings:
title: Reddit
type: object
required:
- __type
- subreddit
properties:
__type:
type: string
enum:
- reddit
subreddit:
type: array
minItems: 1
items:
type: object
properties:
value:
type: object
required:
- subreddit
- title
- type
- is_flair_required
properties:
subreddit:
type: string
minLength: 2
description: Subreddit name without r/
title:
type: string
minLength: 2
description: Post title
type:
type: string
enum:
- self
- link
- image
- video
description: Post type
url:
type: string
description: URL for link posts
is_flair_required:
type: boolean
flair:
type: object
properties:
id:
type: string
name:
type: string
LemmySettings:
title: Lemmy
type: object
required:
- __type
- subreddit
description: Lemmy uses 'subreddit' for communities (historical naming)
properties:
__type:
type: string
enum:
- lemmy
subreddit:
type: array
minItems: 1
items:
type: object
properties:
value:
type: object
required:
- subreddit
- id
- title
properties:
subreddit:
type: string
minLength: 2
description: Community name
id:
type: string
description: Community ID
title:
type: string
minLength: 2
description: Post title
url:
type: string
format: uri
description: Optional URL
PinterestSettings:
title: Pinterest
type: object
required:
- __type
- board
properties:
__type:
type: string
enum:
- pinterest
board:
type: string
minLength: 1
description: Board ID
title:
type: string
maxLength: 100
link:
type: string
format: uri
dominant_color:
type: string
DiscordSettings:
title: Discord
type: object
required:
- __type
- channel
properties:
__type:
type: string
enum:
- discord
channel:
type: string
minLength: 1
description: Discord channel ID
SlackSettings:
title: Slack
type: object
required:
- __type
- channel
properties:
__type:
type: string
enum:
- slack
channel:
type: string
minLength: 1
description: Slack channel ID
TwitchSettings:
title: Twitch
type: object
required:
- __type
description: Twitch post settings
properties:
__type:
type: string
enum:
- twitch
messageType:
type: string
enum:
- message
- announcement
description: Message type
announcementColor:
type: string
enum:
- primary
- blue
- green
- orange
- purple
description: Announcement color (only for announcement type)
DribbbleSettings:
title: Dribbble
type: object
required:
- __type
- title
properties:
__type:
type: string
enum:
- dribbble
title:
type: string
minLength: 1
description: Shot title
team:
type: string
format: uri
description: Team URL
MediumSettings:
title: Medium
type: object
required:
- __type
- title
- subtitle
properties:
__type:
type: string
enum:
- medium
title:
type: string
minLength: 2
description: Article title
subtitle:
type: string
minLength: 2
description: Article subtitle
canonical:
type: string
format: uri
description: Original URL for SEO
publication:
type: string
description: Publication ID to post to
tags:
type: array
maxItems: 4
items:
$ref: '#/components/schemas/Tag'
DevToSettings:
title: Dev.to
type: object
required:
- __type
- title
properties:
__type:
type: string
enum:
- devto
title:
type: string
minLength: 2
description: Article title
main_image:
$ref: '#/components/schemas/Media'
description: Cover image
canonical:
type: string
format: uri
description: Original URL for SEO
organization:
type: string
description: Organization ID
tags:
type: array
maxItems: 4
items:
$ref: '#/components/schemas/Tag'
HashnodeSettings:
title: Hashnode
type: object
required:
- __type
- title
- tags
properties:
__type:
type: string
enum:
- hashnode
title:
type: string
minLength: 6
description: Article title
subtitle:
type: string
minLength: 2
description: Article subtitle
main_image:
$ref: '#/components/schemas/Media'
description: Cover image
canonical:
type: string
format: uri
description: Original URL for SEO
publication:
type: string
description: Publication ID (required)
tags:
type: array
minItems: 1
items:
$ref: '#/components/schemas/Tag'
WordpressSettings:
title: WordPress
type: object
required:
- __type
- title
- type
properties:
__type:
type: string
enum:
- wordpress
title:
type: string
minLength: 2
description: Post title
main_image:
$ref: '#/components/schemas/Media'
description: Featured image
type:
type: string
description: Post type (depends on WordPress setup)
ListmonkSettings:
title: Listmonk
type: object
required:
- __type
- subject
- preview
- list
properties:
__type:
type: string
enum:
- listmonk
subject:
type: string
minLength: 1
description: Email subject line
preview:
type: string
description: Email preview text
list:
type: string
description: List ID to send to
template:
type: string
description: Template ID (optional)
GmbSettings:
title: Google My Business
type: object
required:
- __type
description: Google My Business post settings
properties:
__type:
type: string
enum:
- gmb
topicType:
type: string
enum:
- STANDARD
- EVENT
- OFFER
description: Post type
callToActionType:
type: string
enum:
- NONE
- BOOK
- ORDER
- SHOP
- LEARN_MORE
- SIGN_UP
- GET_OFFER
- CALL
description: Call-to-action button
callToActionUrl:
type: string
format: uri
description: URL for CTA (required if callToActionType is set)
eventTitle:
type: string
description: Event title (required for EVENT type)
eventStartDate:
type: string
description: Event start date
eventEndDate:
type: string
description: Event end date
eventStartTime:
type: string
description: Event start time
eventEndTime:
type: string
description: Event end time
offerCouponCode:
type: string
description: Coupon code (for OFFER type)
offerRedeemUrl:
type: string
format: uri
description: Redemption URL
offerTerms:
type: string
description: Offer terms and conditions
WarpcastSettings:
title: Warpcast
type: object
required:
- __type
description: Warpcast (Farcaster) post settings
properties:
__type:
type: string
enum:
- warpcast
subreddit:
type: array
description: Farcaster channels to post to
items:
type: object
properties:
value:
type: object
required:
- id
properties:
id:
type: string
description: Channel ID
MoltbookSettings:
title: Moltbook
type: object
required:
- __type
- submolt
description: Moltbook post settings
properties:
__type:
type: string
enum:
- moltbook
submolt:
type: string
minLength: 1
description: Submolt (community) ID
SkoolSettings:
title: Skool
type: object
required:
- __type
- group
- label
- title
description: Skool post settings
properties:
__type:
type: string
enum:
- skool
group:
type: string
minLength: 1
description: Group ID
label:
type: string
minLength: 1
description: Label/category ID
title:
type: string
minLength: 1
description: Post title
WhopSettings:
title: Whop
type: object
required:
- __type
- company
- experience
description: Whop post settings
properties:
__type:
type: string
enum:
- whop
company:
type: string
minLength: 1
description: Company ID
experience:
type: string
minLength: 1
description: Experience/forum ID
title:
type: string
description: Post title
EmptySettings:
title: Other Platforms (Threads, Mastodon, Bluesky, etc.)
type: object
required:
- __type
description: For platforms that don't require additional settings
properties:
__type:
type: string
enum:
- threads
- mastodon
- bluesky
- telegram
- nostr
- vk
- kick
description: Platform identifier
Media:
type: object
required:
- id
- path
properties:
id:
type: string
path:
type: string
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: Authorization
description: Your Sipstory API key