ScheduleEnvelope

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "https://artifacts.apis.io/getsocialclaw-com/json-schema/getsocialclaw-com-schedule-envelope-schema.json",
  "title": "ScheduleEnvelope",
  "description": "Schedule document accepted by validation, preview, apply, and dashboard compose workflows.",
  "x-generated": "2026-11-10",
  "x-method": "derived",
  "x-generator": "derive-json-schema.py",
  "x-source": "openapi/getsocialclaw-com-openapi.json#/components/schemas/ScheduleEnvelope",
  "type": "object",
  "additionalProperties": true,
  "properties": {
    "timezone": {
      "type": "string",
      "description": "IANA timezone. Defaults to UTC."
    },
    "mode": {
      "type": "string",
      "enum": [
        "scheduled",
        "draft"
      ],
      "description": "scheduled creates runnable posts; draft creates an editable draft run."
    },
    "idempotencyKey": {
      "type": [
        "string",
        "null"
      ],
      "description": "Optional idempotency key. Also accepted as idempotency_key."
    },
    "posts": {
      "type": "array",
      "description": "Flat list of posts.",
      "items": {
        "$ref": "#/$defs/PostInput"
      }
    },
    "campaigns": {
      "type": "array",
      "description": "Campaign graph model.",
      "items": {
        "$ref": "#/$defs/CampaignInput"
      }
    },
    "schedule": {
      "type": "object",
      "description": "Optional wrapper. Routes accept either the envelope directly or { schedule: envelope }.",
      "additionalProperties": true
    }
  },
  "$defs": {
    "AssetInput": {
      "type": "object",
      "description": "Media asset referenced by a post.",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Client-side or SocialClaw asset id."
        },
        "url": {
          "type": "string",
          "description": "Publicly reachable media URL."
        },
        "managed": {
          "type": "boolean",
          "description": "True when this is a SocialClaw-managed asset."
        },
        "originalFilename": {
          "type": [
            "string",
            "null"
          ],
          "description": "Original file name."
        },
        "mime": {
          "type": [
            "string",
            "null"
          ],
          "description": "MIME type."
        },
        "kind": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "image",
            "video",
            "audio",
            "other",
            null
          ]
        },
        "size": {
          "type": [
            "integer",
            "null"
          ],
          "description": "File size in bytes."
        },
        "duration": {
          "type": [
            "number",
            "null"
          ],
          "description": "Duration in seconds for video/audio."
        },
        "width": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Media width in pixels."
        },
        "height": {
          "type": [
            "integer",
            "null"
          ],
          "description": "Media height in pixels."
        },
        "altText": {
          "type": [
            "string",
            "null"
          ],
          "description": "Alt text where the provider supports it."
        }
      },
      "required": [
        "url"
      ]
    },
    "CampaignInput": {
      "type": "object",
      "description": "Campaign graph with targets and steps.",
      "additionalProperties": true,
      "properties": {
        "id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Campaign id."
        },
        "name": {
          "type": "string",
          "description": "Campaign name."
        },
        "targets": {
          "type": "array",
          "description": "Publishing targets.",
          "items": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "account": {
                "type": "string",
                "description": "Connected account handle."
              },
              "publish_at": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Base publish time.",
                "format": "date-time"
              },
              "steps": {
                "type": "array",
                "description": "Campaign steps.",
                "items": {
                  "$ref": "#/$defs/PostInput"
                }
              }
            }
          }
        }
      },
      "required": [
        "name",
        "targets"
      ]
    },
    "PostInput": {
      "type": "object",
      "description": "Post to validate, schedule, or publish.",
      "additionalProperties": true,
      "properties": {
        "provider": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "x",
            "threads",
            "meta",
            "facebook",
            "instagram_business",
            "instagram",
            "snapchat",
            "tiktok",
            "linkedin",
            "linkedin_page",
            "pinterest",
            "youtube",
            "reddit",
            "discord",
            "telegram",
            "wordpress",
            null
          ],
          "description": "Provider. Optional when account handle identifies the provider."
        },
        "account": {
          "type": "string",
          "description": "Connected account handle or id."
        },
        "name": {
          "type": [
            "string",
            "null"
          ],
          "description": "Post title, campaign step title, or provider title."
        },
        "title": {
          "type": [
            "string",
            "null"
          ],
          "description": "Alias for name on providers requiring titles."
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "Primary post text."
        },
        "text": {
          "type": [
            "string",
            "null"
          ],
          "description": "Alias for description."
        },
        "publish_at": {
          "type": [
            "string",
            "null"
          ],
          "description": "Scheduled publish time.",
          "format": "date-time"
        },
        "publishAt": {
          "type": [
            "string",
            "null"
          ],
          "description": "Camel-case alias for publish_at.",
          "format": "date-time"
        },
        "media_link": {
          "type": [
            "string",
            "null"
          ],
          "description": "Single public media URL."
        },
        "mediaLink": {
          "type": [
            "string",
            "null"
          ],
          "description": "Camel-case alias for media_link."
        },
        "assets": {
          "type": "array",
          "description": "One or more asset objects or URL strings.",
          "items": {
            "anyOf": [
              {
                "$ref": "#/$defs/AssetInput"
              },
              {
                "type": "string",
                "format": "uri"
              }
            ]
          }
        },
        "settings": {
          "type": "object",
          "description": "Provider-specific settings from the publish settings API. Standalone Instagram supports destination/format plus per-media alt text and people tags, collaborators, Reel cover/thumbnail/feed/audio/Trial controls, AI disclosure, and location IDs. post_and_story requires one asset and creates two independent jobs."
        },
        "interaction_type": {
          "type": [
            "string",
            "null"
          ],
          "enum": [
            "post",
            "reply",
            "comment",
            null
          ]
        },
        "parent_step_id": {
          "type": [
            "string",
            "null"
          ],
          "description": "Parent step id for reply/thread workflows."
        }
      },
      "required": [
        "account"
      ]
    }
  }
}