API Documentation

Integrate QPost directly into your applications, scripts, and workflows.

1 Authentication

All API requests must be authenticated using an API Key. You can pass the key in the request headers.

Header Name	Value	Description
x-api-key	YOUR_API_KEY	Preferred method.
Authorization	Bearer YOUR_API_KEY	Alternative standard bearer token method.

2 Create Post

POST/api/post

Request Body (FormData)

Field	Type	Description
caption	string	RequiredThe main text content of your post.
platforms	JSON string	RequiredArray of target platforms. See structure below.
video	File	Video file to upload. (Required if no images)
images	File[]	One or more image files. (Required if no video)
title	string	Optional title (used for YouTube).
scheduledFor	ISO Date	Optional. If provided, post will be scheduled.
timezone	string	Timezone for scheduling (default: "UTC").

Platforms Object Structure

The platforms field expects a JSON stringified array of objects with the following shape:

[
  {
    "platform": "YOUTUBE" | "TIKTOK" | "INSTAGRAM",
    "metadata": { ... } // Platform specific options
  }
]

Platform Metadata Details

YouTube Metadata ▼

All fields are optional.

Field	Type	Description	Default
description	string	Override video description	-
tags	string[] \| string	Array of strings or comma-separated string	-
categoryId	string	YouTube Category ID	"22"
embeddable	boolean	Allow video to be embedded on other sites	true
privacyStatus	"private" \| "unlisted" \| "public"	Video privacy setting	"private"
publishAt	string	ISO datetime for YouTube's own scheduled publishing	-
selfDeclaredMadeForKids	boolean	Mark video as made for kids	false

TikTok Metadata ▼

All fields are optional.

Field	Type	Description	Default
privacyLevel	"PUBLIC_TO_EVERYONE" \| "MUTUAL_FOLLOW_FRIENDS" \| "SELF_ONLY"	Video privacy level	"SELF_ONLY"
allowComment	boolean	Allow comments on the post	-
allowDuet	boolean	Allow other users to create duets	-
allowStitch	boolean	Allow other users to stitch with this video	-
autoAddMusic	boolean	Automatically add background music	true
videoCoverTimestampMs	number	Timestamp in milliseconds for video cover image	1000
commercialContentEnabled	boolean	Mark content as promotional/commercial	false
commercialContentSelections	string[] ("YOUR_BRAND" \| "BRANDED_CONTENT")	Commercial content disclosure options	-

Instagram Metadata ▼

All fields are optional. instagramBusinessAccountId is usually auto-detected from your linked Instagram account.

Field	Type	Description	Default
instagramBusinessAccountId	string	Instagram Business Account ID	auto-detected
mediaType	"IMAGE" \| "CAROUSEL" \| "REELS" \| "STORIES"	Type of Instagram media	auto-detected
mediaProductType	"FEED" \| "STORIES" \| "REELS"	Where the content will be posted	-
disableComments	boolean	Disable comments on the post	-
locationId	string	Instagram Location ID to tag a location	-
thumbOffset	number	Thumbnail offset for video posts (in milliseconds)	-
userTags	object[]	Array of user tags: `[{ username: string, x?: number, y?: number }]`. Max 20 tags	-
altText	string	Custom alt text for accessibility (max 1000 characters)	-

Example Requests

curl -X POST https://yourdomain.com/api/post \
  -H "x-api-key: YOUR_API_KEY" \
  -F "caption=Check out this amazing content! #video" \
  -F 'platforms=[{"platform":"YOUTUBE","metadata":{"categoryId":"22","embeddable":true,"privacyStatus":"public","selfDeclaredMadeForKids":false}},{"platform":"TIKTOK","metadata":{"allowDuet":false,"allowStitch":false,"allowComment":false,"autoAddMusic":true,"privacyLevel":"PUBLIC_TO_EVERYONE","videoCoverTimestampMs":1000,"commercialContentEnabled":false,"commercialContentSelections":[]}}]' \
  -F "video=@/path/to/video.mp4" \
  -F "title=My Awesome Video"

const formData = new FormData();
formData.append('caption', 'Check out this amazing content! #video');
formData.append('title', 'My Awesome Video');
formData.append('platforms', JSON.stringify([
  {
    platform: 'YOUTUBE',
    metadata: {
      categoryId: '22',
      embeddable: true,
      privacyStatus: 'public',
      selfDeclaredMadeForKids: false
    }
  },
  {
    platform: 'TIKTOK',
    metadata: {
      allowDuet: false,
      allowStitch: false,
      allowComment: false,
      autoAddMusic: true,
      privacyLevel: 'PUBLIC_TO_EVERYONE',
      videoCoverTimestampMs: 1000,
      commercialContentEnabled: false,
      commercialContentSelections: []
    }
  }
]));

// Add video file from input element
const videoFile = document.querySelector('#videoInput').files[0];
formData.append('video', videoFile);

const response = await fetch('https://yourdomain.com/api/post', {
  method: 'POST',
  headers: {
    'x-api-key': 'YOUR_API_KEY'
  },
  body: formData
});

const result = await response.json();
console.log(result);

import requests
import json

url = 'https://yourdomain.com/api/post'
headers = {
    'x-api-key': 'YOUR_API_KEY'
}

platforms = [
    {
        'platform': 'YOUTUBE',
        'metadata': {
            'categoryId': '22',
            'embeddable': True,
            'privacyStatus': 'public',
            'selfDeclaredMadeForKids': False
        }
    },
    {
        'platform': 'TIKTOK',
        'metadata': {
            'allowDuet': False,
            'allowStitch': False,
            'allowComment': False,
            'autoAddMusic': True,
            'privacyLevel': 'PUBLIC_TO_EVERYONE',
            'videoCoverTimestampMs': 1000,
            'commercialContentEnabled': False,
            'commercialContentSelections': []
        }
    }
]

data = {
    'caption': 'Check out this amazing content! #video',
    'title': 'My Awesome Video',
    'platforms': json.dumps(platforms)
}

files = {
    'video': open('/path/to/video.mp4', 'rb')
}

response = requests.post(url, headers=headers, data=data, files=files)
print(response.json())

3 Get Posts

GET/api/post

Query Parameters

Parameter	Type	Description
status	string	Filter by status: "DRAFT", "SCHEDULED", "POSTED", "FAILED".
platform	string	Filter by platform: "YOUTUBE", "TIKTOK", "INSTAGRAM".