sprkly

Download an image or video from a public link into sprkly and get a media_id back, for reuse across several posts. You usually do NOT need this: sprkly_schedule_post accepts a link directly in media_urls and pulls it into storage itself whenever the target platform requires that. Reach for this tool only when the user wants one media_id to attach to more than one post. Google Drive and Dropbox share links are converted automatically; the file must be shared publicly. Limit 50 MB.

{
  "type": "object",
  "properties": {
    "url": {
      "type": "string",
      "description": "Direct https link to the image or video file. Must be publicly reachable."
    }
  },
  "required": [
    "url"
  ]
}

Remove a post from the queue. This is a soft delete. The user can restore it from the Deleted tab for 30 days. Posts that have already published cannot be deleted this way. Always confirm with the user before calling.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "The scheduled post id to delete."
    }
  },
  "required": [
    "post_id"
  ]
}

Compose a caption from a content hint and save it as a draft in sprkly, shaped to the tightest caption limit among the target platforms. Returns a draft id; the draft appears under /drafts for the user to review.

{
  "type": "object",
  "properties": {
    "content_hint": {
      "type": "string",
      "description": "What the post should be about: a topic, phrase, or key message."
    },
    "platforms": {
      "type": "array",
      "description": "Intended platforms, used to pick the caption length ceiling.",
      "items": {
        "type": "string",
        "enum": [
          "instagram",
          "tiktok",
          "youtube",
          "threads",
          "facebook"
        ]
      }
    },
    "tone": {
      "type": "string",
      "description": "Voice for the draft.",
      "enum": [
        "casual",
        "professional",
        "promotional"
      ],
      "default": "casual"
    },
    "name": {
      "type": "string",
      "description": "Optional label for the draft."
    },
    "profile_ids": {
      "type": "array",
      "description": "Optional accounts to pre-select on the draft. From sprkly_list_profiles.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "content_hint"
  ]
}

Download one Instagram auto reply as a shareable template. The file holds the trigger, the keyword and the message, and never a post id, a profile id or any account details, so it is safe to send to someone else. An auto reply that is still a draft has nothing published to export.

{
  "type": "object",
  "properties": {
    "automation_id": {
      "type": "string",
      "description": "The automation id to export."
    }
  },
  "required": [
    "automation_id"
  ]
}

Plan tier, trial state, connected account count, scheduled post counts by status, and the next three upcoming posts. Never returns tokens or secrets.

{
  "type": "object"
}

How the user's published posts actually performed: total views and engagement, week-on-week / month-on-month / year-on-year change, their best posting hour, weekday and content category, and the top posts behind those numbers. Every recommendation carries a `samples` count — say how thin the evidence is rather than presenting a one-post pattern as a finding. Every period-on-period percentage carries the post counts and raw totals it came from: quote those, because a big percentage off a tiny base is not a big change. `topPosts` is grouped by platform and ranked only inside each group; `relativeToPlatformBest` compares a post with others on its OWN platform and never across platforms, so use the absolute `value` and its `metric` label to weigh one platform against another. Instagram contributes likes and comments only, and Threads and Facebook produce no metrics at all, so read `coverage` before comparing platforms.

{
  "type": "object",
  "properties": {
    "days": {
      "type": "integer",
      "description": "How many days back to analyse. Default 30.",
      "minimum": 1,
      "maximum": 365
    },
    "profile_ids": {
      "type": "array",
      "description": "Limit to these accounts. Omit for every account this connection can see.",
      "items": {
        "type": "string"
      }
    }
  }
}

Subscription status, current plan, period end, purchased handles and the last few billing events. No payment method details; the Stripe customer id is truncated.

{
  "type": "object"
}

Whether a post is awaiting human review, approved or rejected, including reviewer notes and timestamps.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "The scheduled post id."
    }
  },
  "required": [
    "post_id"
  ]
}

Full detail for one post: status, targets, scheduled and published times, permalink, and the failure reason if it did not publish. Media comes back as mediaIds in slide order, not as links. Ids and profile ids are plumbing: talk to the user about accounts by handle and about posts by their caption, and do not read ids out unless they ask for one.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "The scheduled post id."
    }
  },
  "required": [
    "post_id"
  ]
}

This creator's allowed TikTok privacy levels and interaction settings, fetched live from TikTok. You usually do NOT need this before scheduling: sprkly_schedule_post checks privacyLevel against this same list itself and, when it is wrong, returns the levels that would work. Call this only when the user asks what their options are, or you want to offer them a choice.

{
  "type": "object",
  "properties": {
    "profile_id": {
      "type": "string",
      "description": "The TikTok profile id to query, from sprkly_list_profiles."
    }
  },
  "required": [
    "profile_id"
  ]
}

Read an auto reply template, and optionally set it up. With no profile_id NOTHING is written: the template is checked and handed back, which is the safe first call. With a profile_id the automation is created, and it goes live when the trigger can be satisfied. A keyword or every-comment trigger needs post_id as well; without one it saves as a draft that sends nothing until a post is chosen.

{
  "type": "object",
  "properties": {
    "template": {
      "type": "object",
      "description": "The template, as an object or as the file text."
    },
    "profile_id": {
      "type": "string",
      "description": "The Instagram account to set it up on. Leave this out to only check the template."
    },
    "post_id": {
      "type": "string",
      "description": "The published post to watch. Needed for a keyword or every-comment trigger."
    }
  },
  "required": [
    "template"
  ]
}

Every ACTIVE social account linked to this sprkly account: platform, handle, follower count, and whether it needs reconnecting. Disconnected/inactive accounts are never listed, so any profileId returned here is a valid posting target. Never returns access tokens.

{
  "type": "object"
}

The profile ids needed to target a post, with each one's platform and handle. Call this before sprkly_schedule_post.

{
  "type": "object"
}

The post queue, newest first, with a caption preview, targets, status and failure reason. Supports a status filter and cursor pagination.

{
  "type": "object",
  "properties": {
    "status": {
      "type": "string",
      "description": "Filter by status.",
      "enum": [
        "draft",
        "pending_approval",
        "scheduled",
        "posted",
        "failed"
      ]
    },
    "limit": {
      "type": "integer",
      "description": "Maximum posts to return.",
      "minimum": 1,
      "maximum": 50,
      "default": 20
    },
    "cursor": {
      "type": "string",
      "description": "Pagination cursor. Pass the nextCursor value from a previous response."
    }
  }
}

Submit a draft post for human review. Moves the post to pending_approval and returns an approval id to poll with sprkly_get_post_approval_status. Use this when the user wants a person to sign off before anything publishes.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "The draft post id to submit."
    },
    "note": {
      "type": "string",
      "description": "Optional context for the reviewer."
    }
  },
  "required": [
    "post_id"
  ]
}

Queue a post for publishing, in ONE call. Attach media by passing the user's link straight to media_urls: sprkly downloads it into storage itself for the platforms that need that, so no upload tool has to run first. Runs the same quota, duplicate-content and platform pre-flight checks as the sprkly app. Instagram and TikTok require media at submission time; YouTube and TikTok require a title, and TikTok also requires platform_meta.tiktok.privacyLevel — just send the level the user asked for and this tool names the allowed values if it is not one of them. It reads the real bytes of the media and the response says what will actually publish on each platform (a Reel, a 3-slide carousel, a photo set, a Page feed video) plus anything worth passing on: relay that to the user. Confirm the date, time and target accounts with the user first. If a target platform has more than one connected account and profile_ids is not given, the tool returns needsAccountChoice with the options instead of scheduling — put that choice to the user, then re-call.

{
  "type": "object",
  "properties": {
    "caption": {
      "type": "string",
      "description": "Post caption, max 2200 characters."
    },
    "platforms": {
      "type": "array",
      "description": "Platforms to publish to. A platform with exactly one connected account is targeted directly; one with several makes the tool answer needsAccountChoice so the user can pick.",
      "items": {
        "type": "string",
        "enum": [
          "instagram",
          "tiktok",
          "youtube",
          "threads",
          "facebook"
        ]
      }
    },
    "profile_ids": {
      "type": "array",
      "description": "Specific accounts to publish to, from sprkly_list_profiles. When given, this list IS the target set — platforms are not fanned out.",
      "items": {
        "type": "string"
      }
    },
    "all_accounts": {
      "type": "boolean",
      "description": "Explicitly post to EVERY connected account on every listed platform, skipping the needsAccountChoice question. Only pass true when the user has said they want all accounts.",
      "default": false
    },
    "scheduled_time": {
      "type": "string",
      "description": "ISO 8601 timestamp to publish at. Must be in the future. If omitted the post goes out on the next publisher run, about a minute from now — there is no smart slot-picking, so pass an explicit time unless the user wants it published immediately. sprkly_get_analytics can suggest one."
    },
    "media_urls": {
      "type": "array",
      "description": "Publicly reachable image or video URLs to attach, in slide order. Pass links through for ANY platform. Instagram and Threads fetch them directly; for TikTok, YouTube and Facebook sprkly downloads the file into its own storage while scheduling, so a link works there too and any problem with it is reported now, in this call. Google Drive and Dropbox share links are converted automatically. JPEG, PNG, WebP, GIF, MP4, MOV and WebM only: AVIF and HEIC (the iPhone camera default) are refused with re-export instructions, because sprkly cannot convert them. Each file must be publicly reachable and under 50 MB.",
      "items": {
        "type": "string"
      }
    },
    "media_id": {
      "type": "string",
      "description": "Id of a single media file already uploaded to sprkly. Shorthand for a one-item media_ids."
    },
    "media_ids": {
      "type": "array",
      "description": "Ids of media files already uploaded to sprkly, in slide order. Array order is the published order. Use these when the user already has media in sprkly, or when one file is going on several posts; for a link the user just gave you, media_urls is fewer steps. Every photo in a set must be the SAME shape or the call is refused: export them all at 1080x1920 (9:16), 1080x1440 (3:4), 1080x1350 (4:5) or 1080x1080 (1:1). Instagram takes at most 10 slides; TikTok photo sets take up to 35.",
      "items": {
        "type": "string"
      }
    },
    "title": {
      "type": "string",
      "description": "Post title. Required for YouTube (max 100 characters) and TikTok (max 150 characters)."
    },
    "category": {
      "type": "string",
      "description": "Optional content category, e.g. \"fitness\"."
    },
    "platform_meta": {
      "type": "object",
      "description": "Platform-specific publishing options, keyed by platform.",
      "properties": {
        "instagram": {
          "type": "object",
          "description": "Instagram publishing options.",
          "properties": {
            "surface": {
              "type": "string",
              "enum": [
                "feed",
                "story"
              ],
              "description": "Where to publish. 'story' posts to the account's Story instead of the feed: it disappears after 24 hours, takes exactly ONE photo or video, and sends no caption — Instagram Stories have no caption field. Omit for a normal feed post or Reel. The media cannot decide this: a 9:16 video is a Reel or a Story, so ask the user which they want rather than guessing."
            }
          }
        },
        "tiktok": {
          "type": "object",
          "description": "TikTok publishing options. privacyLevel is REQUIRED for every TikTok post.",
          "properties": {
            "privacyLevel": {
              "type": "string",
              "description": "REQUIRED for TikTok posts. Must be one of this creator's allowed options: fetch them with sprkly_get_tiktok_posting_options.",
              "enum": [
                "PUBLIC_TO_EVERYONE",
                "MUTUAL_FOLLOW_FRIENDS",
                "FOLLOWER_OF_CREATOR",
                "SELF_ONLY"
              ]
            },
            "title": {
              "type": "string",
              "description": "Optional TikTok-only title, used instead of the top-level title on TikTok. Trimmed to 150 characters. The top-level title is still required even when you set this one."
            },
            "commercialContentDisclosure": {
              "type": "boolean",
              "description": "Declare the post as commercial content. When true, at least one of brandContentOptIn or brandOrganicOptIn must also be true."
            },
            "brandContentOptIn": {
              "type": "boolean",
              "description": "Branded content: the post promotes a third party. Cannot be combined with privacyLevel SELF_ONLY."
            },
            "brandOrganicOptIn": {
              "type": "boolean",
              "description": "Organic branding: the post promotes the creator's own brand."
            },
            "brandName": {
              "type": "string",
              "description": "Optional brand name shown with the commercial content disclosure."
            },
            "autoAddMusic": {
              "type": "boolean",
              "description": "Attach TikTok's recommended music. Photo posts only; defaults true.",
              "default": true
            },
            "disableComment": {
              "type": "boolean",
              "description": "Turn off comments on the post."
            },
            "disableDuet": {
              "type": "boolean",
              "description": "Disallow duets of the video."
            },
            "disableStitch": {
              "type": "boolean",
              "description": "Disallow stitches of the video."
            }
          }
        }
      }
    }
  }
}

Change the caption, publish time, target accounts or attached media on a post that has not published yet. Only posts with status "scheduled" can be edited.

{
  "type": "object",
  "properties": {
    "post_id": {
      "type": "string",
      "description": "The scheduled post id."
    },
    "caption": {
      "type": "string",
      "description": "Replacement caption, max 2200 characters."
    },
    "scheduled_time": {
      "type": "string",
      "description": "New ISO 8601 publish time. Must be in the future."
    },
    "profile_ids": {
      "type": "array",
      "description": "Replacement target accounts. Platforms are re-derived from them.",
      "items": {
        "type": "string"
      }
    },
    "media_id": {
      "type": "string",
      "description": "Replacement sprkly media file id. Shorthand for a one-item media_ids."
    },
    "media_ids": {
      "type": "array",
      "description": "Replacement media, in slide order. Replaces the whole set, it does not append — pass every slide you want the post to keep.",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "post_id"
  ]
}

Upload files the user has on their machine (slides, photos, a short video) into sprkly and get a media_id for each. LINK MODE is the way to send a file from disk. Send files, one entry per file with its filename, sha256 and size_bytes. You get back one uploadUrl per file. PUT the bytes to it: curl -sS -X PUT --data-binary @01.jpg "<uploadUrl>". Each PUT answers JSON with mediaId. Links last 15 minutes. Up to 50 MB per file and 35 files per call. The bytes never pass through you, so a whole carousel costs a few hundred tokens. INLINE MODE is for tiny files only (a few KB): data_base64 plus filename, 25 MB at most. base64 costs about one token per character, so never inline a real slide. When files is sent, data_base64 and filename are ignored. For a public link use media_urls on sprkly_schedule_post instead. The same bytes sent twice return the same media_id.

{
  "type": "object",
  "properties": {
    "files": {
      "type": "array",
      "description": "LINK MODE. One entry per file, in slide order. Get the values in Bash: sha256sum 01.jpg (first 64 characters) and stat -c %s 01.jpg. 1 to 35 entries.",
      "minItems": 1,
      "maxItems": 35,
      "items": {
        "type": "object",
        "properties": {
          "filename": {
            "type": "string",
            "description": "The file name, for example 01.jpg."
          },
          "sha256": {
            "type": "string",
            "description": "SHA-256 of the file, 64 hex characters."
          },
          "size_bytes": {
            "type": "integer",
            "description": "Exact file size in bytes.",
            "minimum": 1
          }
        },
        "required": [
          "filename",
          "sha256",
          "size_bytes"
        ]
      }
    },
    "data_base64": {
      "type": "string",
      "description": "INLINE MODE, tiny files only. The file contents, base64 encoded. Standard or URL-safe alphabet, with or without a data: prefix. Ignored when files is sent."
    },
    "filename": {
      "type": "string",
      "description": "INLINE MODE. The file name, for example 01.jpg. Used in the response and in error messages. The bytes decide the real type. Ignored when files is sent."
    },
    "content_type": {
      "type": "string",
      "description": "INLINE MODE. Optional MIME hint such as image/jpeg. sprkly sniffs the bytes and that wins."
    }
  },
  "required": []
}

Check a caption against each target platform's posting rules before scheduling: caption length, media requirements, hashtag ceilings, whether links are clickable, required YouTube titles, and PII or prohibited-content warnings. Pure analysis. Writes nothing.

{
  "type": "object",
  "properties": {
    "caption": {
      "type": "string",
      "description": "The caption to check."
    },
    "platforms": {
      "type": "array",
      "description": "Target platforms to check against.",
      "items": {
        "type": "string",
        "enum": [
          "instagram",
          "tiktok",
          "youtube",
          "threads",
          "facebook"
        ]
      }
    },
    "mediaUrlsCount": {
      "type": "integer",
      "description": "How many images or videos will be attached. Instagram and TikTok require at least one.",
      "minimum": 0
    },
    "hashtags": {
      "type": "array",
      "description": "Hashtags posted alongside the caption, if they are not already in it.",
      "items": {
        "type": "string"
      }
    },
    "title": {
      "type": "string",
      "description": "Post title. Required for YouTube, max 100 characters."
    },
    "platformMeta": {
      "type": "object",
      "description": "Platform-specific publishing options, keyed by platform."
    }
  },
  "required": [
    "caption",
    "platforms"
  ]
}