Scheduling Posts

Schedule posts with flexible timing strategies including global scheduling, per-type offsets, and platform-specific absolute times.

Global Scheduling

The simplest way to schedule a post is using the scheduled_for parameter. This schedules the post for all platforms at the same time:

Schedule for All Platformsbash

curl -X POST https://your-domain.com/api/agents/v1/content/publish \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "Scheduled post for all platforms",
    "platforms": ["instagram", "facebook", "twitter"],
    "scheduled_for": "2024-12-25T10:00:00Z"
  }'

Per-Type Scheduling with Offsets

For more sophisticated campaigns, you can schedule different content types at different times using relative offsets from the base scheduled_for time:

Staggered Release Strategybash

curl -X POST https://your-domain.com/api/agents/v1/content/publish \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "caption": "New product launch! 🚀",
    "platforms": ["instagram"],
    "platform_types": {
      "instagram": ["story", "feed"]
    },
    "scheduled_for": "2024-12-25T10:00:00Z",
    "type_schedule": {
      "story": "+0h",
      "feed": "+1h"
    }
  }'

How Offsets Work

In this example, the story publishes at 10:00 AM, and the feed post publishes at 11:00 AM. The offset +1h means "1 hour after the base scheduled_for time".

Scheduling Options

Parameter	Type	Description	Example
`publish_now`	boolean	Publish immediately	`true`
`scheduled_for`	string	ISO 8601 datetime	`2024-12-25T10:00:00Z`
`type_schedule`	object	Per-type offsets or absolute times	`{"story": "+1h"}`

Offset Format

Offsets can be specified in hours (h) or minutes (m):

+0h - Publish at the base scheduled_for time
+1h - Publish 1 hour after the base time
+30m - Publish 30 minutes after the base time
+2h30m - Publish 2 hours and 30 minutes after the base time

Use Cases

Teaser → Full Reveal

Post a teaser story first, then reveal the full content in the feed later

{
  "platform_types": {
    "instagram": ["story", "feed"]
  },
  "scheduled_for": "2024-12-25T09:00:00Z",
  "type_schedule": {
    "story": "+0h",
    "feed": "+2h"
  }
}

Cross-Platform Viral

Release content on different platforms at staggered times for maximum reach

{
  "platforms": ["instagram", "twitter"],
  "platform_types": {
    "instagram": ["feed"],
    "twitter": ["tweet"]
  },
  "scheduled_for": "2024-12-25T10:00:00Z",
  "type_schedule": {
    "feed": "+0h",
    "tweet": "+30m"
  }
}

Approval Workflow

If your account has approval workflow enabled, scheduled posts will enter a pending approval state before being published. Use the require_approval parameter to explicitly require approval:

Require Approvaljson

{
  "caption": "Important announcement",
  "platforms": ["instagram", "facebook"],
  "scheduled_for": "2024-12-25T10:00:00Z",
  "require_approval": true
}

Managing Scheduled Posts

You can list, update, and delete scheduled posts using these endpoints:

List Scheduled Postsbash

curl -X GET "https://your-domain.com/api/agents/v1/content/scheduled?status=scheduled" \
  -H "X-API-Key: your_api_key_here"

Update Scheduled Timebash

curl -X PATCH "https://your-domain.com/api/agents/v1/content/scheduled?job_id=pub_abc123" \
  -H "X-API-Key: your_api_key_here" \
  -H "Content-Type: application/json" \
  -d '{
    "scheduled_for": "2024-12-26T10:00:00Z"
  }'

Cancel Scheduled Postbash

curl -X DELETE "https://your-domain.com/api/agents/v1/content/scheduled?job_id=pub_abc123" \
  -H "X-API-Key: your_api_key_here"

Next: Media Upload

Learn how to prepare and upload media files from various sources in theMedia Upload section.