sprkly API docs

Let products and agents schedule social content through sprkly.

sprkly's external API lets SaaS apps, automation pipelines, and AI agents connect accounts, create content jobs, schedule posts into D1, queue due-now jobs for the next Worker tick, and poll status without using the browser dashboard.

Base URL

https://sprkly.app

Authentication

All API requests use scoped Bearer API keys.

Quick start

Use this flow when another app, internal automation, or AI agent wants sprkly to queue and publish content through the centralized Worker publisher.

  1. 1.Every plan can create scoped API keys: Free 1 key and 3,000 requests a month, Creator and Brand 3 keys and 7,500, Pro 5 keys and 15,000, Agency 5 keys and 30,000. MCP is on every paid plan.
  2. 2.Create a scoped API key in sprkly settings; choose all connected accounts or specific account/profile IDs for that key.
  3. 3.Connect each social profile through sprkly, then call GET /api/v1/connections to see account IDs, platforms, and handles visible to the key.
  4. 4.Call POST /api/v1/posts or POST /api/v1/posts/schedule from your backend or agent pipeline, passing profileIds when targeting specific accounts. Use POST /api/v1/publish only when you intentionally want a due-now row for the next Worker tick.
  5. 5.Store returned postIds and poll GET /api/v1/posts/{id} until posted or failed.
  6. 6.Use permalink and failedReason to reconcile results in your own app.

Zapier and Make templates

sprkly is ready for user-owned Zapier and Make.com automation templates. Users sign up, connect their social accounts, create a scoped API key, then copy or fork a template that calls the sprkly API from a trusted automation backend.

1. Discover accounts

Call GET /api/v1/connections and let users choose the profileId for each platform.

2. Upload or map media

Use public mediaUrls when available, or POST /api/v1/media and pass the returned mediaId.

3. Schedule and reconcile

POST /api/v1/posts with externalId, then poll GET /api/v1/posts/{id} for status and permalinks.

Read template guideCreate API key

Authentication

Send your API key as a Bearer token. API keys are scoped, can be revoked, and should only be used from trusted server-side code.

curl -sS https://sprkly.app/api/v1/posts/post_123 \
  -H "Authorization: Bearer $SPRKLY_API_KEY"

post:write

Create scheduled posts and publish jobs.

post:read

Read post status, failures, and permalinks.

account:read

List connected account ids, platforms, and handles.

account:write

Create social account connection requests.

media:write

Upload media from trusted automation backends.

automation:read

Export an auto reply as a template file. Through MCP, also list the ready-made templates, list your automations and see this month's usage. Needs a connected Instagram account.

automation:write

Import a template file and set up the auto reply. Through MCP, also set one up from a ready-made template, and pause or resume one. Needs a connected Instagram account.

inbox:read

MCP only. Read your inbox: who wrote, their DMs and comments. Off unless you tick inbox access when you make the key.

inbox:write

MCP only. Reply to a DM or a comment as you. Off unless you tick inbox access when you make the key.

Automations set up with a key

  • When a key turns an automation on, the owner gets a short email. It names the automation, the account, what changed and when. Changes made in the sprkly app send no email.
  • POST /api/v1/automations/templates with a profileId returns buttonHosts: where each button link goes.
  • Button links have to start with https://.
  • A link made to look like WhatsApp, but not on wa.me or whatsapp.com, is refused.
  • A link with a name and an @ before the host is refused.
  • When a new version drops a link, buttons already sent with it stop working. A tap gets a 410 and "This link is no longer active."
  • An exported template has {link} in place of each WhatsApp button link. Put your own link in before you import it.
Keep keys server-side. Never expose API keys in frontend JavaScript, mobile apps, public repos, screenshots, analytics logs, or agent transcripts. Use backend secrets or CI secret storage.

Endpoint reference

GET/api/v1/connectionsscope: account:read

List connected social accounts

Returns the active connected accounts visible to the API key, including each account id, platform, handle, profile URL, and connection timestamps. Token material is never returned.

Request

No request body.

Response

{
  "accounts": [
    {
      "id": "profile_instagram_123",
      "platform": "instagram",
      "handle": "sprkly.app",
      "profileUrl": "https://instagram.com/sprkly.app",
      "profileImageUrl": null,
      "tokenExpiresAt": null,
      "connectedAt": "2026-05-01T00:00:00.000Z",
      "updatedAt": "2026-05-01T00:00:00.000Z"
    }
  ],
  "count": 1
}
  • Use these account ids as profileIds when creating an account-scoped API key or publishing to a specific connected account.
POST/api/v1/connectionsscope: account:write

Create a social account connection request

Creates a short-lived human handoff link for connecting Instagram, TikTok, YouTube, Threads, or Facebook to the sprkly account that owns the API key.

Request

{
  "platform": "instagram"
}

Response

{
  "requestId": "conn_...",
  "platform": "instagram",
  "connectUrl": "https://sprkly.app/mcp/connect/conn_...",
  "expiresAt": "2026-05-01T12:15:00.000Z"
}
  • Open the connectUrl in a browser and complete the OAuth flow before scheduling posts for that platform.
POST/api/v1/mediascope: media:write

Upload media for automation templates

Uploads an image or video from a trusted server-side integration and returns a sprkly mediaId plus a signed serve URL. Use this when Zapier, Make, or another automation tool receives a file instead of a public media URL.

Request

multipart/form-data

file=@launch-video.mp4

Response

{
  "success": true,
  "url": "https://sprkly.app/api/media/serve?key=uploads%2F...",
  "mediaId": "media_..."
}
  • Maximum upload size is 50 MB.
  • Pass the returned mediaId to POST /api/v1/posts when the source app cannot provide a stable public media URL.
  • Trials and paid plans can both upload. Only expired accounts are refused, with upload_plan_required.
POST/api/v1/media/from-urlscope: media:write

Add media from a link

Give sprkly a public link and it downloads the file, then returns a mediaId. We delete the file 48 hours after its post goes out. A file from a failed post, or one never used, is deleted after 7 days. Use this instead of passing the link as mediaUrls: TikTok video, YouTube video, Facebook Reels and Facebook photos cannot publish from an outside link at all, and the failure only shows up hours later when the post goes out.

Request

{
  "url": "https://cdn.example.com/clips/launch.mp4"
}

Response

{
  "success": true,
  "mediaId": "media_...",
  "url": "https://sprkly.app/api/media/serve?key=uploads%2F...",
  "contentType": "video/mp4",
  "sizeBytes": 8412334
}
  • The link must point at the file. Google Drive and Dropbox share links work too: sprkly turns them into a download link for you.
  • Maximum size is 50 MB. The file type is read from the file itself, not from the link.
  • Sending the same link twice returns the same mediaId and uses no extra storage.
POST/api/v1/postsscope: post:write

Create or schedule posts

Canonical partner endpoint for creating scheduled posts. sprkly validates the API key, scopes, quota, profile ownership, media ownership, and platform names before inserting jobs for the publisher.

Request

{
  "platforms": ["instagram", "tiktok"],
  "profileIds": ["profile_instagram_123", "profile_tiktok_456"],
  "caption": "New launch is live: https://example.com",
  "title": "New launch is live",
  "scheduledTime": "2026-05-01T15:00:00.000Z",
  "platformMeta": {
    "instagram": { "coverUrl": "https://cdn.example.com/reel-cover.jpg" },
    "tiktok": {
      "privacyLevel": "PUBLIC_TO_EVERYONE",
      "disableComment": false,
      "disableDuet": true,
      "disableStitch": true,
      "commercialContentDisclosure": false,
      "brandOrganicOptIn": false,
      "brandContentOptIn": false
    },
    "facebook": { "coverUrl": "https://cdn.example.com/reel-cover.jpg" },
    "youtube": { "thumbnailUrl": "https://cdn.example.com/reel-cover.jpg" }
  },
  "externalId": "my-app-launch-001",
  "category": "launch"
}

Response

{
  "postIds": ["post_...", "post_..."],
  "status": "scheduled",
  "scheduledTime": "2026-05-01T15:00:00.000Z"
}
  • If multiple platforms/profiles are supplied, sprkly creates one scheduled row per matching profile.
  • For production integrations, pass explicit profileIds so content cannot publish to an unintended active account.
  • TikTok posts require title plus platformMeta.tiktok.privacyLevel; if commercialContentDisclosure is true, at least one of brandOrganicOptIn or brandContentOptIn must be true.
  • platformMeta can carry explicit video cover metadata such as Instagram/Facebook coverUrl, TikTok videoCoverTimestampMs, or YouTube thumbnailUrl; the Compose UI generates the same shape when users drop a video cover image.
  • Use externalId to map sprkly posts back to your own system.
POST/api/v1/posts/schedulescope: post:write

Schedule posts explicitly

Alias of POST /api/v1/posts for integrations that prefer an explicit scheduling path. scheduledTime must be a future ISO 8601 timestamp.

Request

{
  "platforms": ["threads"],
  "caption": "Behind the scenes update",
  "scheduledTime": "2026-05-02T09:30:00.000Z"
}

Response

{
  "postIds": ["post_..."],
  "status": "scheduled",
  "scheduledTime": "2026-05-02T09:30:00.000Z"
}
  • Use this route when your product already knows the publish time.
POST/api/v1/publishscope: post:write

Queue for the next publisher tick

Creates scheduled jobs for the next publisher tick when scheduledTime is omitted. This route still writes scheduled D1 rows; sprkly Worker cron performs the actual social-platform publish through the centralized publisher.

Request

{
  "platforms": ["instagram"],
  "caption": "Fresh update from our agent-curated content queue",
  "mediaUrls": ["https://cdn.example.com/card.jpg"],
  "externalId": "agent-run-2026-05-01-001"
}

Response

{
  "postIds": ["post_..."],
  "status": "scheduled",
  "scheduledTime": "2026-05-01T12:01:00.000Z"
}
  • Immediate publish means scheduled for the next sprkly publisher cron run, not a synchronous social network API call.
  • Poll GET /api/v1/posts/{id} to know whether it succeeded and to retrieve permalinks.
GET/api/v1/posts/{id}scope: post:read

Get post status

Returns the current scheduled post state for a post owned by the API-key user. Use this to reconcile agent runs, partner dashboards, and publish-result webhooks in your own app.

Request

No request body.

Response

{
  "id": "post_...",
  "status": "posted",
  "caption": "Fresh update from our queue",
  "platforms": ["instagram"],
  "profileIds": ["profile_instagram_123"],
  "mediaUrls": ["https://..."],
  "scheduledTime": "2026-05-01T12:01:00.000Z",
  "publishedAt": "2026-05-01T12:02:10.000Z",
  "failedReason": null,
  "externalId": "agent-run-2026-05-01-001",
  "permalink": "https://instagram.com/p/...",
  "platformMeta": null,
  "createdAt": "2026-05-01T12:00:05.000Z",
  "updatedAt": "2026-05-01T12:02:10.000Z"
}
  • 404 means the post does not exist or does not belong to the API-key owner.

Post payload fields

FieldTypeNotes
platformsstring[]Required. One or more of instagram, tiktok, youtube, threads, facebook, bluesky, x.
captionstringRequired unless mediaUrls or mediaId is supplied. Each platform's own limit applies: Instagram and TikTok video 2,200, TikTok photos 4,000, YouTube 5,000 bytes, Threads 500. No < or > on YouTube. Links in a caption are posted as you wrote them. sprkly does not check them.
titlestringRequired for TikTok and YouTube publishing. Max 150 chars for TikTok.
scheduledTimeISO datetimeOptional for /publish. Required future time for explicit scheduling.
profileIdsstring[]Recommended for production. Use GET /api/v1/connections to discover ids. Must be active, owned by the API-key user, within the API key account scope, and match requested platforms.
mediaUrlsstring[]Public URLs reachable by platform APIs. Use mediaId when you want sprkly to resolve/sign its own authenticated uploads.
mediaIdstringUse an existing active sprkly media asset. sprkly resolves it to a public serve URL.
platformMetaobjectPlatform-specific settings. TikTok requires tiktok.privacyLevel and supports disableComment, disableDuet, disableStitch, commercialContentDisclosure, brandOrganicOptIn, brandContentOptIn, and videoCoverTimestampMs.
externalIdstringYour system’s ID for reconciliation. Some values are reserved for sprkly: ig, ig-container, tiktok-pending, threads, threads-container, yt, fb, bsky, x, linkedin, pinterest and telegram, on their own or followed by a colon (like x:123). These are refused with 400 invalid_external_id.
categorystringOptional label for reporting/grouping.

Errors

Errors return a JSON object with a human message and stable machine-readable code.

A 429 also sends Retry-After (seconds to wait), X-RateLimit-Limit, X-RateLimit-Remaining and X-RateLimit-Reset (your monthly requests), and X-RateLimit-Burst (your requests a minute).

{
  "error": "API key does not have the required scope",
  "code": "insufficient_scope"
}
missing_api_key

Authorization header is missing or is not a Bearer token.

invalid_api_key

The API key is invalid, revoked, or expired.

insufficient_scope

The key does not include the scope required by the endpoint.

api_access_disabled

API access is disabled because the account is missing or the key/user is invalid. During beta, registered tester accounts are allowed regardless of payment tier.

missing_content

The request has no caption, mediaUrls, or mediaId.

missing_platforms

platforms is missing or empty.

unsupported_platform

A platform is not supported by sprkly.

invalid_scheduled_time

scheduledTime is not a valid ISO 8601 datetime.

scheduled_time_in_past

scheduledTime must be in the future.

invalid_profile_ids

One or more profileIds are inactive, not owned by the account, or do not match the requested platforms.

profile_scope_denied

One or more profileIds are outside the selected accounts allowed for this API key.

media_not_found

The mediaId is not active/ready or does not belong to the account.

missing_file

The media upload request did not include a file field.

file_too_large

The uploaded file exceeds the 50 MB API upload limit.

upload_plan_required

The account cannot upload media through the API on its current plan.

storage_quota_exceeded

The account has exceeded its media storage quota.

quota_exceeded

The account has exceeded its scheduling quota.

rate_limited

429. Too many requests in one minute: Free allows 20, every paid plan 60. Wait the seconds in Retry-After.

monthly_quota_exceeded

429. All requests for this month are used: Free 3,000, Creator and Brand 7,500, Pro 15,000, Agency 30,000. REST and MCP share the count. It resets on the 1st (UTC). Retry-After says how long.

key_over_plan_limit

403. The plan holds fewer keys than you have: Free 1, Creator and Brand 3, Pro and Agency 5. The oldest keys work. Revoke one or upgrade.

post_not_found

The post does not exist or is not owned by the account.

Recommended agent workflow

sprkly is designed to become the publishing layer for content agents. Your agents can gather product updates, convert them into channel-specific captions, attach approved media, and hand the final schedule to sprkly.

# 1. Agent consolidates content from your product/app/wiki/CRM.
# 2. Agent chooses platform, caption, approved media, and schedule time.
# 3. Agent creates a scheduled sprkly job; the Worker cron owns final social delivery.
curl -sS -X POST https://sprkly.app/api/v1/posts/schedule \
  -H "Authorization: Bearer [REDACTED]" \
  -H "Content-Type: application/json" \
  -d '{
    "platforms": ["instagram"],
    "caption": "New feature is live. See what changed: https://example.com",
    "scheduledTime": "2026-05-01T15:00:00.000Z",
    "externalId": "agent-run-2026-05-01-001"
  }'

# 4. Store postIds, then poll status until posted or failed.
curl -sS https://sprkly.app/api/v1/posts/post_... \
  -H "Authorization: Bearer $SPRKLY_API_KEY"

For production agent systems, keep a queue of generated drafts, require approval when needed, store sprkly postIds, and reconcile publishedAt/permalink back into your own analytics or CRM.

Connect an AI agent (MCP)

Everything above is also available over the Model Context Protocol, so Claude, Codex, Cursor or ChatGPT can read your queue and schedule posts directly. Same account, same quotas, same publishing pipeline. No API key needed if the client speaks OAuth.

Server URL

https://sprkly.app/api/mcp

Claude

Settings → Connectors → Add custom connector. Paste the URL, click Connect, approve. Works across claude.ai, Desktop, mobile and Cowork.

# Claude Code
claude mcp add --transport http sprkly https://sprkly.app/api/mcp

Codex

Add it to ~/.codex/config.toml by hand. codex mcp add only takes stdio servers. Then log in.

[mcp_servers.sprkly]
url = "https://sprkly.app/api/mcp"
auth = "oauth"

# then, in a terminal:
# codex mcp login sprkly

Prefer a key to a browser round-trip? Every client that speaks plain HTTP can send Authorization: Bearer sk_live_… instead. Full setup for Cursor, VS Code, ChatGPT and n8n, plus every tool the server exposes, is on the MCP reference.

Need API access?

API access is currently enabled for registered tester accounts during beta and can later be tightened into the Pro/API entitlement. Contact sprkly support if your account needs API-key setup help.

Contact supportOpen settings