Your channels.
Your AI assistant.

Connect in three steps.

MCP lets a compatible AI client use SocialBlaze tools. You do not need to write GraphQL to read posts, make drafts or schedule through the named tools.

https://backend.socialblaze.ai/api/developer/mcp

Client features and account availability vary. A custom MCP connection is not a claim of a marketplace-listed connector. For a personal server app, use the API quickstart; for other users, use OAuth app registration.

Connect with Claude

1. Open Customize > Connectors, choose Add, then Add custom connector. Name it SocialBlaze, paste the MCP server URL above and continue.
2. Review the detected authentication settings. Choose Sign in now and, under OAuth client, Register automatically. SocialBlaze uses automatic registration rather than Claude’s published identity. Sign in to SocialBlaze, review the requested permissions and select channels, then finish with Add. No API key is needed for this OAuth connection.
3. In a new chat, open +, then Connectors, and enable SocialBlaze. If Claude says this server is already connected, use its existing entry under Yours instead of creating another connector.

Workspace administrators may need to add the connector first. See the Claude custom connector guide for current screens and account requirements.

A connected channel is missing in my AI

Check that the channel is unlocked and accessible in SocialBlaze. Then reconnect SocialBlaze from your AI app, review the requested permissions and select the missing channel. Adding or unlocking a channel does not add it to an existing AI connection; refreshing that connection keeps its channel selection. Keep your existing connection until reconnection works. You do not need to reconnect Instagram or Facebook just to change your AI connection’s channel selection.

If you have analytics permission and the channel is visible but no saved report is available, that is a separate data-availability issue. Changing the channel selection does not collect or refresh analytics.

Try useful, bounded requests

For “last 10 published,” keep every returned channel post separate, even when captions or article links match. Results cover the channels you authorized, not necessarily your whole account. A missing saved report or unknown metric is not zero; reading a report does not refresh a network. Post preview cards are in preview. In ChatGPT, the first display may fail; choose Try again to load the cards. If an image cannot load, open the saved post in SocialBlaze. Availability in other AI apps varies. Externally hosted images can be unavailable; a preview does not repair their source. Scheduled or accepted posts are not confirmed deliveries; check the returned status before reporting success.

Service status has its own home.

See current evidence for core services, API & MCP and network publishing on the Service status page.

Follow what we are building.

See shipped work, current improvements and planned directions on the Roadmap page.

Build your first API request.

Sign in to your SocialBlaze account, open the developer console, and create a key. Choose the channels and permissions your integration needs. Copy the secret once and store it on your server.

curl -A 'SocialBlazeDeveloperClient/0.1 (+https://socialblaze.ai/api)' 'https://backend.socialblaze.ai/api/developer/graphql' \
  -H "Authorization: Bearer $SOCIALBLAZE_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '{"query":"{ channels { id name service connected } }"}'

The returned channel IDs belong to your selected access. Use those IDs when creating posts. The console includes a runnable explorer that keeps its credential in memory for that session.

Draft. Review. Schedule. Publish.

mutation Publish($key: String!, $channels: [ID!]!, $text: String!) {
  createPost(requestKey: $key, channelIds: $channels, text: $text,
    mode: publishNow) {
    accepted published
    posts { id channelId status publishingState publishedUrl
      failure { code message automaticRetrySafe } }
  }
}

Accepted does not mean delivered. Read post.allowedActions for scoped local edit/cancel guidance; every mutation still rechecks the current version and publishing state. Read each returned post ID to check its status, published URL and failure details. A mixed invalid batch saves nothing. Never retry an uncertain write with a new request key.

Retain contentItemId from createPost or createThread. Deleting one destination can preserve its source draft. To remove the complete local content group, read its current content-item version and use deleteContentItem; confirm the group and its posts are absent afterward.

Read delivered posts without combining channels

Read each network post separately, keeping its ID, channel and returned URL. The default descending record-ID order matches the website feed within the credential's authorized channels. A selected-channel grant does not expose every channel in the workspace. For chronology based on eligible recorded delivery evidence, request sort: [{field: publishedAt, direction: desc}] and optional publishedAfter/publishedBefore. Read nullable publishedAt and publishedAtBasis. native_terminal_delivery_observed is the first local terminal-confirmation time, not an independently verified original provider publication instant; scheduled, created and edited dates never fill an unknown publication time. Unknown times sort last and cannot establish a complete chronological last-ten claim. Reset cursors when filters or sorting change.

query {
  posts(first: 10, status: "delivered") {
    nodes { id channelId text publishedUrl publishedAt publishedAtBasis }
    pageInfo { endCursor hasNextPage }
  }
}
# Default order matches the website feed's descending record IDs.
# For known recorded publication times, use sort:[{field:publishedAt,direction:desc}].

Images, video and documents

Attach JPEG, PNG or WebP images within each destination’s limit, or one MP4/MOV video. Standard posts accept up to 10 images on Facebook, Instagram, Tumblr and WordPress; 20 on LinkedIn and Threads; 35 on TikTok; 4 on Bluesky, Mastodon and Google Business Profile; and 1 on Pinterest. YouTube requires video. Tumblr accepts one H.264 MP4/MOV video up to ten minutes long, within the same 50 MB import limit. A shared post must fit every selected destination. Multi-post groups and threads keep an eight-attachment total per request. Images may include a separate protected thumbnailUrl for their SocialBlaze preview; it does not replace the image sent to a network. Images also accept a separate protected animatedThumbnail: a public GIF or WebP preview up to 1 MiB. Static and animated previews each use their own import allowance and retain their separate URLs. The original image still has to meet the destination’s image rules. Asset reads expose both URLs; isAnimated stays null until animation is measured, so a preview URL is not proof the original image is animated. LinkedIn also accepts one PDF with a title and an optional HTTPS thumbnailUrl for the SocialBlaze preview. Preview images are validated JPEG, PNG or WebP files limited to 1 MB; LinkedIn renders its own document pages. Images are limited to 8 MB each, videos to 50 MB and PDFs to 20 MB. Channel-specific validation still applies; query configuration and channel.capabilities.

Edit and request review together

For an integration-owned plain single-channel draft on a channel requiring approval, use updatePost with approvalChange: request or revert. Named MCP edit_post supports these choices without text. Supply the latest version, a stable request key, drafts:write and posts:review. Content and attachments change atomically with the review request. Approval alone does not publish; explicitly submit the unchanged approved draft afterward. Changed approved content needs review again.

Change a future publishing method

Use updatePost(publishingMethod: automatic) or reminder, or named edit_post, to switch one safe future post while retaining its ID. Supply its current version and a stable request key. This requires both draft and publishing permissions. Automatic posts must have one future schedule; reminders must be queued and unnotified. Posts with publishing attempts, review requirements or thread membership cannot be converted. A reminder needs an active signed-in mobile notification device. Conversion rechecks the destination, plan, media and current access; it does not confirm network delivery.

Track the composer source

createDraft, createPost, createThread and each createContentItemVariants entry accept nullable source, a caller-declared tracking label of up to 250 characters. Matching named MCP creation tools support it, including review posts. A thread shares its label across its entries; variants can use separate labels. Read it through post.provenance.composerSource and composerSourceBasis; named get_post and Node getPost include provenance. Ordinary list reads also include it; lists with saved metrics omit provenance and animated-preview metadata to stay within the same query budget. Read individual posts for both together. Omission or null on creation leaves the label unknown. Draft and future-post edits also accept it: omission preserves the label and null clears it. This label does not change recorded creation transport, grant permissions or prove AI authorship.

Declare AI assistance

Draft and future-post edits accept nullable aiAssisted, including named MCP edit_post. False remains false, null clears the caller declaration, and omission preserves it. This does not change creation transport or detect who authored the text. Use the latest version and the same request key for an unchanged retry.

Rules for each format

Read configuration.services.contentRules or channel.capabilities.contentRules for each automatic post format and attachment type. Rules include caption and title counting, attachment counts, allowed file types and byte limits, required channel choices and first-comment support. This catalog describes SocialBlaze validation. Your plan, current permissions, dimensions and provider checks still apply; it does not confirm delivery. Reels require one video; automatic Stories require one image or video.

Channel metadata and mentions

Read workspace membership totals and native plan limits through account.organizations. Channels include provider destination IDs, safe profile URLs, network icons and publishing capabilities. Page large selections with channels(first, afterId); MCP list_channels returns pagination metadata.

Post and library assets return stored mimeType, width and height when known; unknown values remain null. No media download is needed to read them. Structured Facebook Page and LinkedIn mentions use channelOptions.mentions with Unicode code-point start/length offsets and a matching label. Read post.annotations for validated mentions and literal links. Invalid or overlapping ranges are rejected; changed captions must provide updated mention positions.

Recorded provenance and account state

Read post.provenance for recorded creation transport and optional caller-declared AI assistance. Set aiAssisted explicitly when known; unknown stays null. A request through an AI client does not prove that AI wrote its caption. Provider video disclosure uses its separate channel setting.

account.preferences returns your stored calendar and time display codes when known. Channel reads distinguish queuePaused, workspacePublishingPaused and credentialsExpired; pausing publication does not itself mean the provider credential expired.

Network text counting

Bluesky uses compact visible URL labels with full destinations retained in UTF-8 byte-indexed link facets. Saved captions retain their original URLs. Mastodon uses its configured instance metadata and official grapheme, reserved URL and remote mention rules; content warnings count literally. Read textLimitsBasis, textLimitsMetadataAvailable and charactersReservedPerUrl in publishing capabilities to distinguish current instance metadata from conservative fallback. Metadata reads are bounded and cached.

TikTok photos, video and delivery

Photo captions allow 4,000 UTF-16 units with an optional title of up to 90 units. Video captions allow 2,200 units. Set channelOptions.isAiGenerated explicitly for video disclosure; true is rejected for photos. Future video metadata edits preserve an explicit false. Read tiktokPostingChoices(channelId) or MCP get_tiktok_posting_choices for the selected creator’s actual privacy choices, interaction restrictions and video duration. These reads may use a cache up to 60 seconds old; publishing revalidates them. Choose the audience and consent explicitly. A returned publish ID confirms acceptance: developer posts remain processing until a verified provider callback or a bounded provider status read confirms delivery for the same original attempt. Status verification does not submit another publication. A public post URL may remain unknown.

Instagram image mentions

Set images[].userTags with a public handle without @ and numeric x/y positions from 0 to 1. Use up to twenty unique handles per image. Feed images and carousel children support positioned mentions; carousel parents and automatic Stories do not. Remove positioned mentions before scheduling an automatic Story. These fields are Instagram-only, and invalid or duplicate handles and coordinates are rejected. Library templates preserve image mentions when reused. They are not internal content tags.

Manual publishing reminders

Set publishingMethod: reminder for your selected channels. Each receives its own reminder. Enable notifications in the signed-in SocialBlaze phone app first. The reminder keeps a prepared draft and opens its content when due; it never automatically publishes. Explicit date, next manual queue slot and priority are supported. changeReminder reschedules or cancels it, or records your own publication confirmation. For Instagram reminders, stickerFields can hold music, products, text, topics and other finishing instructions, up to 2,000 characters each. The signed-in reminder screen displays and copies them. Add these details yourself in Instagram; automatic publishing rejects populated finishing fields. A sent notification or manual confirmation is not a network delivery receipt. A multi-channel request shares imported media and either saves the whole group or nothing. Deleting its content item cancels every pending reminder. For team review, also set requestApproval: true with posts:review and explicit posts:publish consent. The reminder waits for native approval, remains protected from automatic publication and is canceled when review is withdrawn or approval becomes stale.

YouTube video settings

Choose privacy and madeForKids explicitly. Query configuration.youtubeCategories for provider category IDs and set categoryId when needed. Optional embeddable, license (youtube or creativeCommon), notifySubscribers and isAiGenerated reach the native YouTube upload. Explicit false values are preserved. You can edit these settings on a future post through updatePost.channelOptions without replacing its video. AI disclosure refers to realistic altered or synthetic content; follow YouTube’s disclosure requirements.

Video covers

For one Instagram, TikTok or Pinterest video, set thumbnailOffset in channel options to the cover frame’s millisecond offset. It must be inside the imported video duration. For a safe future post, updatePost can change the cover on an existing tenant-owned import or replace the video and choose its cover in the same request. Existing native posts can use this edit when their media is a supported tenant-owned import; arbitrary external video URLs are not eligible for a cover-only edit. Omitted media and scheduling keep the saved asset and time. Reuse the same request key after an uncertain response. Pinterest receives the whole-second frame offset and accepts one imported MP4/MOV video up to 50 MB; its video is uploaded and processed before the Pin is created. Instagram Reels also accept shareToFeed, including an explicit false. Other channels and Instagram Stories reject these options.

Future edits require the current post version and a schedule more than two minutes away. In-flight and delivered posts cannot be changed. A Reel feed-sharing edit preserves its video and cover when those fields are omitted. For Pinterest, edit channelOptions.destinationUrl to change its destination link; an explicit null clears the saved link. Post reads return that value in both destinationUrl and the channel options. These edits do not publish immediately.

Link cards

For standard Facebook, LinkedIn, Bluesky or Threads posts without other attachments, supply linkUrl in channel options. LinkedIn and Bluesky also accept linkTitle and linkDescription. Facebook and Threads use the destination website preview. LinkedIn and Bluesky also accept linkThumbnailUrl with the link URL: a direct public JPEG, PNG or WebP up to 1,000,000 bytes, with eight distinct previews per request. It is protected-imported and uploaded to the provider; an upload failure stops before publication. Save a new preview in the draft before submitting it. Null clears a saved preview. HTTPS links cannot contain credentials. No server-side scraping occurs. Edit future cards with updatePost.channelOptions; an explicit null linkUrl clears the card and its title/description. Clearing it and replacing media in the same request is atomic. Draft options merge explicitly changed fields; an empty list resets every choice.

Locations and Threads topics

Instagram feed/Reel and Threads posts accept a numeric provider locationId and optional locationName. Instagram carousel children do not receive the tag. Automatic Instagram Stories reject this option. Threads also accepts a topic up to 50 UTF-16 units, without an ampersand or period. Omitted choices survive future edits; null clears them.

Content warnings and AI disclosure

Mastodon accepts spoilerText; the warning counts literally and shares the configured instance character allowance with the prepared caption. Instance URL and remote mention counting applies to the caption, not the warning. Use null to clear a saved warning. Instagram, YouTube and TikTok video accept isAiGenerated. Instagram sends this on the parent media container only. Unsupported network options are rejected before any posts are saved.

First comments

First comments use separate UTF-16 limits: Facebook 5,000, Instagram 2,200, LinkedIn 1,250 and Threads 500. Read maxFirstCommentLength and firstCommentLengthUnit from the channel capability. Emoji may count as two units. Unsupported destinations and Stories reject comments; text is never silently truncated. Existing plan permissions still apply.

Caption limits

Most developer captions use UTF-16 units, where many emoji count as two. LinkedIn HTTP(S) URLs count as 24 units; Instagram logical newlines count as two. Facebook captions allow 5,000, Instagram 2,196; Pinterest and YouTube titles allow 100. Google Business retains its native 1,500 limit. Mastodon uses bounded instance metadata with a configured conservative fallback; read its capability fields for the current basis and metadata availability. Bluesky counts graphemes after compact visible link labels, while preserving full URL destinations in link facets. Original saved captions remain unchanged. Read channel capabilities for the current limit and counting unit.

Google Business posts

Use channelOptions.businessPost for standard updates, events and offers. Events and offers need a title and local start/end dates. Optional paired times use HH:mm; omitting both covers the whole local day. UTC publication scheduling remains separate. Standard updates and events support action buttons; offers use coupon, redemption link and terms. Call buttons use the business phone without an action URL. Other buttons require HTTPS URLs. These options require automatic publishing, retain the existing summary/image limits and never imply confirmed provider delivery.

Instagram audio

Browse or search licensed music and original sounds through the audio catalog queries. Facebook Login is required. For a single-video Reel, supply an audio ID and optional volume levels in the channel options. Previews expire; permission and partial-result errors are explicit. Saved draft options survive later submission.

Ordered threads

Bluesky, Mastodon and Threads support 2–25 entries. Replies wait for confirmed parent delivery. Rescheduling or canceling the root keeps its safe future replies together. Bluesky and Threads entries also accept linkUrl; Bluesky accepts linkTitle, linkDescription and a protected linkThumbnailUrl. Cards cannot be combined with other media; Threads uses the destination website preview. Mastodon rejects cards. Threads allow eight attachments across the request and at most 100 destination posts.

mutation {
  createThread(requestKey: "launch-thread-001", channelIds: ["YOUR_CHANNEL_ID"],
    mode: schedule, dueAt: "2026-11-01T14:00:00+00:00",
    entries: [{text: "First part"}, {text: "The follow-up"}]) {
    accepted posts { id status thread { rootPostId parentPostId position total } }
  }
}

Edit attachments across a future thread

Use updateContentItem.threadEntries or named edit_content_item to replace or clear attachments and link choices for the complete existing thread. Supply every entry in order, its caption, the current group version and a stable request key. Omitted attachments stay unchanged; images: [] or clearMedia: true removes them. Shared uploads are imported once per entry across channels. Every destination must be unattempted, unpublished and more than two minutes in the future. The whole edit saves atomically. Keep the same entry count and edit scheduling separately; resizing and combined media/schedule edits are not supported.

Content group filters

Filter contentItems by draftContent or postContent, and sort by createdAt and updatedAt. Discovery defaults to your integration. Explicit discovery: workspace requires separately approved content:read plus posts:read; existing credentials do not gain it automatically. It also reads groups visible under your native workspace permissions and selected channels. Groups containing an inaccessible destination are excluded, including their shared caption and media. Check managedByCurrentIntegration; cross-integration group changes remain blocked, while individual post changes retain their separate authorization checks. Cursors bind discovery, filters, order and channel access; reset pagination when those change. SDK0.1.14 provides contentItems(options) and contentItem(id, options) read helpers.

Team review

Use posts:review and requestApproval: true to create posts with publication suspended. requestPostApproval sends an existing unpublished post into review. withdrawPostApproval returns it to a draft only when your native approval permissions allow it. Review permission never grants automatic publication.

Adapt each destination.

Use createContentItemVariants when each channel needs a different caption, title, attachment, native option or schedule. Supply distinct selected channel IDs in posts. The group supports up to 25 destinations and eight attachments total, within your existing media and posting limits. Identical media entries share one protected import.

mutation Campaign($key: String!, $posts: [ContentVariantInput!]!) {
  createContentItemVariants(requestKey: $key, title: "Product launch", posts: $posts) {
    contentItemId accepted published
    posts { id channelId text title status isDraft publishingMethod
      manualReminder { state providerDeliveryConfirmed } dueAt version }
  }
}
# Each posts entry supplies its own channelId, text, optional media,
# channelOptions, mode and dueAt. Read real channel IDs first.

Validation and saving are atomic: one failed variant saves no partial campaign. Each entry defaults to the queue, or to its supplied schedule. Use mode: publishNow only for an intentional immediate submission. Set requestApproval: true for suspended team review. Acceptance is still not confirmed delivery.

Read contentItem.hasChannelVariants and the group version, then read individual post IDs for full details. Edit an individual post to preserve different captions. A group text or media edit intentionally applies the same change to every safe future destination. Group and individual versions are different.

Promote an existing draft

Read an integration-owned, unsubmitted channel-less draft and its current group version. Call promoteContentItemDraft with a nonempty posts list to turn that same content item into distinct channel posts. Each entry supplies its own channel ID, explicit text and optional media, native choices and schedule. The source caption and attachments stay saved; omitted entry media does not inherit them.

mutation Promote($id: ID!, $version: String!, $key: String!,
    $posts: [ContentVariantInput!]!) {
  promoteContentItemDraft(id: $id, version: $version, requestKey: $key,
    posts: $posts) {
    contentItemId accepted published
    posts { id channelId text status isDraft publishingMethod
      manualReminder { state providerDeliveryConfirmed } dueAt version }
  }
}
# Each entry needs its channelId and explicit text, plus any media/options.
# Read the existing draft's ID/version first; do not mix posts and channelIds.

Use either per-channel posts or the existing shared channelIds form. Do not combine them, or mix entry choices with top-level scheduling options. A failed destination saves no partial promotion. Reuse the same request key for an unchanged retry; a submitted draft cannot be promoted again under a new key. Requesting review needs drafts:write and posts:review; automatic submission needs posts:publish. Native team approval rules still apply. Entries use ContentVariantInput. Each entry accepts nullable aiAssisted: false stays false, null or omission leaves assistance unknown, and changed entry text never inherits the original draft's declaration. Each destination can stay a draft, use automatic publishing or use a manual reminder. Keep contentItemId for complete group cleanup.

Automatic URL shortening by workflow

Shortening runs before the final save, using the author's configured connectors. Settings are never silently disabled. Support depends on workflow, attachment and native channel choices; unsupported combinations return an actionable error.

The basic text profile covers Facebook, Bluesky, LinkedIn, Threads, Tumblr, Google Business Profile, Mastodon and WordPress. Native-limited image profiles also include Instagram and Pinterest; video profiles include the native-supported YouTube/TikTok and other validated services. Uniform scheduled promotion and existing stored/native transitions have separate validated choice catalogs; the mixed-group rules above do not admit arbitrary options. Explicit stored privacy/consent and current native validation remain required. Saving never arms work, and review never grants publication. Read allowedActions and current versions; withdraw pending review before deletion when that action is advertised. Preparation acceptance and shortening do not confirm network delivery.

Save a destination before scheduling

Set saveToDraft: true on an entry to save a channel-bound draft. It needs drafts:write, without publishing permission or a fresh publishing login. Saving alone creates no publishing schedule or phone reminder. Mode and date values on a saved entry do not schedule it or become reusable scheduling instructions; choose a fresh mode and date when you explicitly schedule it later. Null is not accepted for saveToDraft.

mutation SaveForChannel($key: String!, $channel: ID!, $text: String!) {
  createContentItemVariants(requestKey: $key, posts: [{
    channelId: $channel, text: $text, saveToDraft: true
  }]) {
    contentItemId accepted published
    posts { id channelId isDraft publishingMethod version }
  }
}

Read the destination ID and its latest version, then use armDestinationDraft or named arm_destination_draft to schedule that same post. The named tool calls the ID postId. Choose publishNow, schedule with dueAt, addToQueue or prioritize. If you omit the mode, a supplied date selects scheduling; otherwise the queue is used. Automatic publishing rechecks current publishing permission, channel access, media, approval requirements and login health.

mutation ScheduleSavedDraft($id: ID!, $version: String!, $key: String!,
    $when: String!) {
  armDestinationDraft(id: $id, version: $version, requestKey: $key,
    mode: schedule, dueAt: $when) {
    id version deleted
  }
}
# Use the destination post ID and its latest version, not the group ID.
# Then read the post to check publishing state; this is not a delivery receipt.

Return a future destination to draft

For an owner-managed automatic destination whose publication has not started, updatePost(saveToDraft: true) can preserve the same destination ID, source group and attachments while deactivating its single future schedule. Supply the current version and a stable request key, with both publishing and draft permissions. The schedule must be more than two minutes away. Return it first, then edit its current draft separately; review, reminder, thread and attempted-publication states keep their dedicated flows. Explicitly arm the draft again when ready.

Review a saved draft

On a channel requiring approval, combine saveToDraft: true with requestApproval: true. This needs draft and review permissions. The draft remains unarmed after approval: explicitly schedule the unchanged approved version afterward. Editing it requires fresh approval. By contrast, requesting review while explicitly scheduling an automatic post suspends that schedule until approval.

Keep manual publishing explicit

Set an entry’s publishingMethod: reminder when someone will finish publishing on their phone. A saved draft retains that choice without requiring a device. When you later schedule it, an omitted publishing method keeps its saved choice; an explicit method selects that method again. Null is not accepted. Scheduling a reminder requires draft and publishing permissions, an active signed-in notification device and any required approval. publishNow queues a reminder due now; it does not publish to the network automatically.

Read isDraft, publishingMethod and manualReminder.state together. A pending saved-review entry is still a draft, and a saved reminder choice has no active reminder yet. providerDeliveryConfirmed: false is not proof of network delivery. Mixed groups can contain saved, scheduled and reminder entries; their per-post actions remain separate. Use edit_post with draft: true to edit a safe saved destination, and canonical deleteContentItem or delete_content_item for whole-group cleanup. Withdraw pending review first. Claimed or uncertain publication requires reconciliation rather than blind deletion.

Named tools for AI clients

get_publishing_configuration and get_channel expose actual media and consent requirements. Use list_content_items, get_content_item, create_content_item_draft, promote_content_item_draft and create_content_item_variants without writing GraphQL. Edit, delete and association tools retain the same scope, version and retry checks.

Reuse your saved content.

Browse, create and edit the templates in your actual SocialBlaze content library. Reuse text, image, video and PDF templates in drafts. Editing needs the current version. Removing a template preserves shared uploaded files.

query {
  libraryItems(first: 20) {
    nodes { id title text description emoji visibility version assets { type url title altText } }
    pageInfo { endCursor hasNextPage }
  }
}

Use createDraftFromLibraryItem with its ID, version, request key and selected channels. Library access follows your current plan and team permissions.

Templates accept an optional description (up to 1,000 characters), emoji (up to 32 characters) and visibility: internal for your workspace or private for their creator. Existing templates and omitted visibility stay internal. Only the creator can make a shared template private; private templates are hidden from other members in the API, native library and mobile reads. Filter libraryItems(visibility: private) or internal. There is no public curated template catalog. Null clears description or emoji; omitted fields survive edits. Native edits retain these choices.

Build the report you need.

Explicit TikTok provider collections enumerate public videos only. enumerationComplete describes that source traversal; complete remains false because photos and private videos are excluded. Read basis and note on reports, aggregate references and ranking coverage before interpreting totals or empty results.

Ordinary channel reports, individual post metrics, rankings and aggregate reads use existing SocialBlaze website data and saved snapshots only. A read does not contact a provider, queue collection or refresh missing data. Available metrics differ by network; unavailable values stay unknown, never zero.

query Report($channel: ID!, $start: String!, $end: String!, $report: ID,
    $first: Int = 20, $after: String) {
  channelReport(channelId: $channel, startDate: $start,
    endDate: $end, reportId: $report) {
    id state complete basis note enumerationComplete metricsUpdatedAt expiresAt errorCode
    metrics { key value status basis }
    posts(first: $first, after: $after) { nodes { externalId text publishedAt publicationDate publicationTimeBasis
      metrics { key value status } }
      pageInfo { endCursor hasNextPage } }
  }
}

Read readMode, storedAnalytics and available stored date ranges when no normalized report is available. Native sections retain their original labels and measurement bases. A row update timestamp is not proof that every metric was collected then. Missing data stays unavailable; publishing-token expiry alone does not prevent an authorized historical read. Date ranges remain limited by the account's available history. Inspect complete, each metric's status and its basis before interpreting totals. Every channel report and aggregate reference identifies its network service. Aggregate metricsUpdatedAt is the latest known contributing timestamp; oldestMetricsUpdatedAt gives the oldest contributing instant and stays null when a ready source has unknown freshness.

Optional LinkedIn video statistics include unique per-post viewers and totalTimeWatched in minutes. Unique viewers are never summed across posts. Instagram follows is an attributed count for eligible feed posts and Stories, not Reels or net follower growth. These values depend on provider access and availability; unavailable values remain null. No Instagram watch-time unit is inferred.

LinkedIn report traversal is bounded. If the reader reaches its page limit or cannot safely advance, usable observed rows may be returned with partial coverage. Their totals describe only that observed subset, never all posts in the account. Read the report note and enumeration status before comparing channels.

Performance rows can expose publicationDate and publicationTimeBasis separately from publishedAt. A historical native calendar day with unknown timezone keeps publishedAt: null; do not invent a midnight UTC publication time. Keep separate network posts separate rather than combining posts that link to the same article.

Collect new provider data only when requested

Use the explicit refreshChannelReport mutation or named MCP refresh_channel_report only after the user asks to collect new provider data. Collection may require current provider analytics permission and consumes the separate refresh budget. It can return queued; poll the same returned report ID and dates with channelReport. Ordinary reads never sign in, reconnect accounts or start this operation automatically.

mutation CollectNewReport($channel: ID!, $start: String!, $end: String!) {
  refreshChannelReport(channelId: $channel, startDate: $start, endDate: $end) {
    id channelId state complete errorCode
  }
}
# Only run after an explicit request to collect new provider data.
# If queued, poll channelReport using the returned report ID and dates.

Include saved metrics with post reads

Set includeMetrics: true on post or posts, or named MCP get_post and list_posts. Supply metricSnapshots with a channel ID, report ID and matching start/end dates for each channel. Both posts:read and analytics:read are required. This only reads existing snapshots; it never contacts a network or starts report collection. Read metricsState, metricsErrorCode, each metric status/basis and metricsUpdatedAt. Missing or unavailable metrics stay null. Stored history can be stale; retain the associated report's stale and freshness indicators instead of treating it as newly collected. Omit the option for ordinary post reads; normal selection and complexity limits apply.

query SavedPostMetrics($id: ID!, $pins: [PostMetricSnapshotInput!]!) {
  post(id: $id, includeMetrics: true, metricSnapshots: $pins) {
    id metricsState metricsErrorCode metricsUpdatedAt
    metrics { name value unit status basis comparisonBasis }
  }
}
# pins: [{channelId: YOUR_CHANNEL_ID, reportId: EXISTING_REPORT_ID,
#         startDate: MATCHING_START_DATE, endDate: MATCHING_END_DATE}]
# Supply these as JSON variables, using the snapshot's actual IDs and dates.

Count local publishing records

publishingActivity counts retained automatic post records by original creation date in your chosen timezone. Each destination and thread entry counts separately. Aggregate counts include soft-deleted records, exclude drafts and manual reminders, and cannot recover purged records or provider-only history. Native drafts may retain older creation dates after submission. This is not exact historical submission or publication dates; currentlyDelivered describes current status among these records. Keep the returned basis and note visible.

recordedCommitEvents separately counts retained native attempts by recorded provider acknowledgement date, independently of original creation dates. An intentional republication counts again. Acceptance can precede processing or delivery, so these are not delivery totals. Keep commitEventBasis, commitEventCountUnit, commitEventNote and the false commitEventHistoryComplete flag visible.

query {
  publishingActivity(startDate: "2026-09-01", endDate: "2026-09-30",
    timezone: "America/New_York") {
    count currentlyDelivered complete basis countUnit note
    recordedCommitEvents commitEventBasis commitEventCountUnit
    commitEventHistoryComplete commitEventNote
    channels { channelId service coverage count }
  }
}

Count known recorded publication times

publishedActivity counts retained currently-delivered destination records whose eligible native recorded delivery time falls in the requested calendar range and timezone. It uses the same timestamp rules as nullable post.publishedAt; created, edited, scheduled and acknowledgement dates never substitute. Each network destination/thread record counts separately, including aggregate soft-deleted records. Keep rangeStartUtc, rangeEndUtcExclusive, basis, countUnit and complete: false. unknownTimeExcluded counts all selected retained delivered records with unknown times, not unknown posts assigned to this month. Purged, overwritten and provider-only history remains outside this known-time subset.

query {
  publishedActivity(startDate: "2026-09-01", endDate: "2026-09-30",
    timezone: "America/New_York") {
    count unknownTimeExcluded complete includesSoftDeleted
    rangeStartUtc rangeEndUtcExclusive basis countUnit unknownTimeExcludedBasis note
    channels { channelId service count unknownTimeExcluded coverage }
  }
}

Use named MCP get_published_activity, Node publishedActivity or CLI tools call get_published_activity. This reads local records without provider collection. Original-creation-cohort publishingActivity and acknowledgement-based recordedCommitEvents retain their separate meanings.

Rank observed performance

rankedPosts requires an explicit metric and either lifetime or period_total basis. Unknown values and incompatible bases are excluded; zero stays a real score. Per-network coverage distinguishes complete, partial, queued and unavailable sources. Reuse report IDs for stable comparisons. Each result identifies its metric unit; engagement rates use percentage units and retain their comparison basis. Different known rate formulas are not ranked together, and rates are never summed. LinkedIn unique reach is not summed across posts. Facebook Like reactions are separate from total reactions when the provider returns them; missing values remain null. Performance does not prove that the copy caused the result.

query {
  rankedPosts(startDate: "2026-09-01", endDate: "2026-09-30",
    metric: "reactions", metricBasis: "lifetime", first: 10) {
    state complete metric metricBasis note
    posts { channelId externalId text publishedAt publicationDate publicationTimeBasis value }
    channels { channelId service reportId coverage basis note enumerationComplete missingMetricPosts }
  }
}

Named MCP tools are get_publishing_activity and rank_posts. SDK methods are publishingActivity and rankPosts.

Connect with OAuth.

Register a public PKCE client or a confidential server app in the console. Register exact callback URLs, choose scopes, and provide your app's privacy URL. Each customer chooses their channels and can disconnect your app.

1. Generate a random verifier and its S256 challenge. Keep a random state value to verify the callback.
2. Open /api/developer/oauth/authorize with client ID, registered redirect URI, scopes, state, challenge, code_challenge_method=S256 and the requested resource.
3. Exchange the returned code at /api/developer/oauth/token, including the original verifier and resource. Confidential clients also authenticate with their secret.
4. Store credentials securely. Access tokens last one hour; refresh tokens rotate and expire after 30 days. Never reuse a replaced refresh token.

Resources are https://backend.socialblaze.ai/api/developer or its /graphql or /mcp endpoint. Existing AI connector tokens use a separate audience.

Put your account within reach.

Use a custom remote MCP connection in a compatible assistant or developer client. The endpoint is https://backend.socialblaze.ai/api/developer/mcp. Use OAuth sign-in when your client supports it; no developer key is needed for that flow. Use a scoped developer key only in clients that support secure Bearer authentication.

{
  "mcpServers": {
    "socialblaze": {
      "url": "https://backend.socialblaze.ai/api/developer/mcp",
      "headers": {"Authorization": "Bearer YOUR_DEVELOPER_KEY"}
    }
  }
}

Client configuration syntax varies. Tools are filtered by the granted scopes. Available tools cover account/channel reads, drafts, publishing, threads, review, templates and reports. Schema resources and generic GraphQL tools use the same permissions and quotas. A listing here does not imply a marketplace-listed connector.

n8n

Add an MCP Client step, choose HTTP Streamable and use https://backend.socialblaze.ai/api/developer/mcp. Select Bearer Auth and save your scoped key in an n8n credential. Choose a tool, then use JSON input for nested parameters. Start with get_account or a draft mutation; retain the same request key when retrying an event.

Zapier

In your app connections, add MCP Client by Zapier. Enter the endpoint above, choose Streamable HTTP and OAuth. Sign in to SocialBlaze, review the requested permissions and select channels. Use a read-only tool for reports or Run Tool for an authorized draft action. Enable error handling and inspect the returned structured data before starting another step.

Some Zapier MCP Client editors send array text as strings. channelIds requires a real array. If the editor flattens it, use execute_mutation with one GraphQL mutation string containing the literal channelIds: ["YOUR_CHANNEL_ID"]. Start with a future schedule, keep its request key and inspect errors before continuing.

These use the platforms’ generic MCP clients. Client account availability and provider fees are separate from SocialBlaze API limits.

Limits you can build around.

UTC windows are shared across every key and authorized app. More keys do not multiply allowances. Only the selected operation and reachable fragments are charged: one unit per 25 complexity points rounded up, minimum one, plus two for mutations. Response headers and MCP metadata report the charged work units and cost basis. This is an initial conservative policy; provider refreshes and media retain separate budgets. Cached reads still cost local query work. Website posting and network/provider limits are separate.

• 401: credential expired, revoked or invalid.
• 403: missing scope, channel access or team permission.
• 409: stale version, changed retry input or an unsafe publication state.
• 422: inspect the validation details, including channels.ID.
• 429: follow Retry-After; reuse the same mutation key.

GraphQL can return errors with HTTP 200. Always inspect errors. Every mutation also has a try variant, such as tryCreateDraft, with a typed success result or MutationError. Select __typename and the error’s code, httpStatus, message, fields and retryAfterSeconds. A typed error can appear in data with HTTP 200, so check that outcome as well. These are preview limits, not a promise that a provider allows the same volume.

Start with a small workflow.

Import an n8n workflow

Download a workflow, choose Import from File in n8n, edit its inputs, then attach your own Bearer Auth credential to the MCP Client step. Each starts with a manual trigger and stays inactive after import. Keys belong in n8n credentials, never in the JSON.

• Event to draft / stable event ID for retries; never publishes.
• Local publishing activity / original record creation dates, with explicit counting limits.
• Observed post ranking / chosen metric and basis, with coverage and report pins.

Imported with n8n 2.43.5; MCP node calls verified against an isolated API fixture. Hosted execution with your own credentials is a separate check. These use generic MCP clients and do not imply a marketplace-listed app or published Zapier template. Keep external messaging authorization in your own workflow.

Read the current schema.

The reference is generated from the implemented GraphQL types. Authenticated introspection and the explorer provide the deployed contract. SocialBlaze uses its own identifiers and schema.

Give your coding assistant the AI-readable API guide so it can use the correct endpoints, permissions, versions and retry rules.

Server-side Node client

The versioned package includes TypeScript declarations and a command-line client. Install the downloaded file with npm install ./socialblaze-developer-client-0.1.14.tgz. Keep your key in a server environment variable.

Use named post and draft commands, tools list, tools describe NAME, tools call NAME, schema describe TYPE and doctor. Supply JSON directly, from a file or stdin. --dry-run checks basic advertised input rules without calling the tool; discovery still uses quota and does not confirm provider validation or delivery. The CLI never automatically retries writes.

Post reads support postTypes and dueAtPresence filters for stored native formats and scheduled-date presence. Reset the cursor when filters change. These filters do not enable additional publishing formats.

Named list_channels supports pages of 1–100, default 20, with afterId. Select smaller field sets for larger pages; normal complexity and work allowances apply. Format filters additionally include Google Business event, offer and whats_new, based on saved native metadata. These intentionally overlap the ordinary post bucket and do not enable new publishing formats.

Node getPost and contentItem return asset URLs, including static and animated previews. Node listPosts keeps its compact projection without assets; use an individual read or an explicit GraphQL selection. Node getPost includes isDraft but keeps a compact projection without publishing-method or manual-reminder state. Use named get_post or an explicit GraphQL query for those fields; the generic client and CLI can carry the new draft operations without changing the immutable SDK package.

Select response fields

Named CLI calls accept --fields 'id,text' and sibling groups such as --fields 'nodes.{id,text},pageInfo.endCursor'. Paths are relative to the named result. The server builds a smaller GraphQL selection and validates it before execution. Charges reflect that selection. Keep IDs and versions when tracking writes, and retain report basis, notes and coverage. all restores the tool’s standard selection, rather than every schema field. MCP named tools accept the same fields string. Channel pagination metadata remains available when the displayed fields omit IDs. Generic query commands use their explicit document.

CLI setup and agent guidance

socialblaze init writes local defaults; config path and config get --all inspect them. Environment credentials are recommended. Only explicit init --save-token persists a token in an unencrypted global file outside the current project. Repository configuration supports timezone and timeout only, and cannot supply a credential or redirect its origin. Config output redacts stored keys; local removal does not revoke the server key.

context --list lists the bundled agent topics; context prints the skill and reporting guidance offline. completion bash, zsh, fish or powershell prints a shell completion script. Use socialblaze install claude or install codex for an explicit offline managed skill installation; uninstall claude or uninstall codex reverses an unchanged installation. Customized or linked folders are preserved. Package installation and init do not install skills or change shell profiles. Suggestions cover static command groups. Version 0.1.5 fixes nested zsh completion. Static command suggestions are checked in actual offline bash, zsh ZLE and fish runtimes; PowerShell output is parser-checked. These checks do not exercise remote tools or authorize publishing.

Read the bundled agent skill. It preserves your authorization and distinguishes local record counts, observed ranking and incomplete provider history. Read its linked reporting reference for those workflows.

Need help with a specific request? Email [email protected] with the operation name, status and safe error code. Never include your key, refresh token or social-network credentials.