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.Registered tester accounts can create scoped API keys during beta; public paid-plan entitlement can be tightened later when the API ships as a Pro feature.
  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.

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": "sprklyapp",
      "profileUrl": "https://instagram.com/sprklyapp",
      "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

[email protected]

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.
  • Free legacy accounts cannot upload media through the API; use public mediaUrls or upgrade to a paid plan.
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 and Bulk Schedule UIs generate 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.
captionstringRequired unless mediaUrls or mediaId is supplied. Max 2,200 chars.
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.
categorystringOptional label for reporting/grouping.

Errors

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

{
  "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.

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.

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