Skip to main content

​
Scheduling API Reference

Schedule your TikTok content for optimal posting times using our Scheduling API.

​
Base Endpoint

POST /api/v1/schedule

​
Authentication

  • Required: Bearer token (JWT or API key)
  • Feature: Available on Basic and Professional plans only

​
Endpoints

​
Create Scheduled Post

POST /api/v1/schedule/create Schedule a video for future publication.
​
videoId
string
required
Upload ID of the video to schedule
​
tiktokAccountId
string
required
TikTok account ID to publish to
​
scheduledPublishTime
string
required
ISO 8601 datetime string for publish time (e.g., “2025-10-21T14:30:00Z”)
curl -X POST 'https://api.d1g.qzz.io/api/v1/schedule/create' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "videoId": "550e8400-e29b-41d4-a716-446655440000",
    "tiktokAccountId": "123e4567-e89b-12d3-a456-426614174000",
    "scheduledPublishTime": "2025-10-21T14:30:00Z"
  }'

import axios from 'axios';

const scheduleVideo = async () => {
  try {
    const response = await axios.post(
      'https://api.d1g.qzz.io/api/v1/schedule/create',
      {
        videoId: '550e8400-e29b-41d4-a716-446655440000',
        tiktokAccountId: '123e4567-e89b-12d3-a456-426614174000',
        scheduledPublishTime: '2025-10-21T14:30:00Z',
        title: 'Scheduled Amazing Video',
        hashtags: '#trending #viral'
      },
      {
        headers: {
          'Authorization': 'Bearer YOUR_API_KEY',
          'Content-Type': 'application/json'
        }
      }
    );
    console.log('Schedule successful:', response.data);
  } catch (error) {
    console.error('Schedule failed:', error.response?.data || error.message);
  }
};

import requests

def schedule_video():
    url = "https://api.d1g.qzz.io/api/v1/schedule/create"
    headers = {
        "Authorization": "Bearer YOUR_API_KEY",
        "Content-Type": "application/json"
    }
    data = {
        "videoId": "550e8400-e29b-41d4-a716-446655440000",
        "tiktokAccountId": "123e4567-e89b-12d3-a456-426614174000",
        "scheduledPublishTime": "2025-10-21T14:30:00Z",
        "title": "Scheduled Amazing Video",
        "hashtags": "#trending #viral"
    }
    
    response = requests.post(url, json=data, headers=headers)
    
    if response.status_code == 200:
        print("Schedule successful:", response.json())
    else:
        print("Schedule failed:", response.json())

{
  "success": true,
  "data": {
    "scheduleId": "650e8400-e29b-41d4-a716-446655440000",
    "scheduledTime": "2025-10-21T14:30:00.000Z",
    "status": "pending",
    "createdAt": "2025-01-20T10:30:00.000Z"
  }
}

​
Get Scheduled Videos

GET /api/v1/schedule/scheduled-videos Get all scheduled videos for the authenticated user. 
{
  "success": true,
  "data": [
    {
      "id": "650e8400-e29b-41d4-a716-446655440000",
      "scheduledPublishTime": "2025-10-21T14:30:00.000Z",
      "status": "pending",
      "video": {
        "id": "550e8400-e29b-41d4-a716-446655440000",
        "title": "Amazing TikTok Video",
        "description": "Check out this content!"
      },
      "tiktokAccount": {
        "id": "123e4567-e89b-12d3-a456-426614174000",
        "username": "my_tiktok_handle",
        "displayName": "My TikTok Name"
      }
    }
  ]
}

​
Update Scheduled Post

PUT /api/v1/schedule/{scheduleId} Update a scheduled post before it publishes.
​
scheduleId
string
required
Schedule ID to update
​
scheduledPublishTime
string
New publish time (ISO 8601 format)
​
status
string
Update status: “pending”, “executed”, or “cancelled”
curl -X PUT 'https://api.d1g.qzz.io/api/v1/schedule/650e8400-e29b-41d4-a716-446655440000' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  -d '{
    "scheduledPublishTime": "2025-10-22T10:00:00Z",
    "status": "pending"
  }'

​
Delete Scheduled Post

DELETE /api/v1/schedule/{scheduleId} Delete a scheduled post.
​
scheduleId
string
required
Schedule ID to delete

​
Get Upcoming Scheduled Posts

GET /api/v1/schedule/upcoming Get upcoming scheduled posts (public endpoint, no authentication required). 
{
  "success": true,
  "data": {
    "upcomingPosts": [
      {
        "scheduleId": "650e8400-e29b-41d4-a716-446655440000",
        "publishTime": "2025-10-21T14:30:00Z",
        "accountId": "123e4567-e89b-12d3-a456-426614174000"
      }
    ]
  }
}

​
Scheduling Limits

PlanScheduled Posts Limit
Basic10
Professional50
Attempting to schedule beyond your plan limits will result in a 403 FORBIDDEN error with code SCHEDULING_LIMIT_EXCEEDED.

​
Time Zone Considerations

All scheduled times must be provided in UTC (ISO 8601 format). The system automatically handles time zone conversion for publishing.
Best Practice: Always validate your scheduled time is in the future (at least 15 minutes from current time) to avoid scheduling errors.

​
Common Errors

  • 400 VALIDATION_ERROR: Invalid datetime format or missing required fields
  • 403 FORBIDDEN: Scheduling feature not available or limit exceeded
  • 404 NOT_FOUND: Invalid video ID or schedule ID
  • 422 UNPROCESSABLE_ENTITY: Scheduled time too close to current time or in the past
  • 409 CONFLICT: Video already scheduled or published
Scheduled posts are processed automatically at the specified time. Once the publish time is reached, the status changes to “executed” and the video is published to TikTok.