# MCP-first setup and current MVP

Public developer page: https://socialblaze.ai/api/. Member documentation: /developer-docs. Standalone system status: https://socialblaze.ai/status/. Roadmap: https://socialblaze.ai/roadmap/.
Remote developer MCP endpoint: https://backend.socialblaze.ai/api/developer/mcp. In a compatible client use OAuth browser sign-in/consent; no developer API key is required for that OAuth flow. In a Bearer-capable client use a separate scoped key created in the developer console, with selected channels and actions. Never place keys in prompts, URLs, client-side source or logs. Begin with get_account/list_channels; named tools do not require the user to write GraphQL. Custom-client support is not marketplace listing. OAuth consent displays the scopes requested by the client, not per-scope selection controls. Select channels explicitly. If the client requests posts:publish, approval requires publishing opt-in; a read-only connection requires a request without publishing scopes. Analytics permission is separate. Keep each returned channel destination as a separate post; never select one representative per channel or deduplicate shared article links.
Claude OAuth setup: open https://claude.ai/customize/connectors, choose Add > Add custom connector, name it SocialBlaze, enter the MCP endpoint above and continue. Review detected authentication settings; choose Sign in now and OAuth client Register automatically (SocialBlaze uses automatic registration, not Claude’s published identity). Sign in to SocialBlaze, review requested permissions and select channels, then finish with Add. No API key is required. In a new chat use + > Connectors to enable SocialBlaze. If the server is already connected, use its existing entry under Yours instead of creating a duplicate. Workspace administrators may need to add the connector first. Current official instructions: https://support.claude.com/en/articles/11175166-get-started-with-custom-connectors-using-remote-mcp.
A connected channel is missing in my AI: first check that the channel is unlocked and accessible in SocialBlaze. Reconnect SocialBlaze from the AI app, review requested permissions and select the missing channel. Adding or unlocking a social channel does not add it to an existing MCP grant; refresh preserves its channel selection. Keep the existing connection until reconnection works. Do not reconnect Instagram/Facebook merely to change MCP channel selection. With analytics permission, a visible channel with no available saved report is a separate data-availability issue; reconnecting does not collect or refresh reports.
Current MVP guides cover authorized reads, drafts, safe future edits, schedules/queues and existing stored analytics. Accepted is not delivered. Missing metrics are unavailable, not zero; provider refresh is a separate explicit operation. 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. They do not publish.
The status view separates core login/connections/publishing/analytics/settings, API/MCP and all twelve native networks. Missing or stale health evidence must display unknown; capability is not uptime. No fabricated incident history or percentages. Roadmap labels live/in progress/planned have no invented ETA. Ideas/tags/community/ads/X and Substack Notes are not advertised as forthcoming release requirements.

# SocialBlaze developer API

Existing draft promotion: promoteContentItemDraft and named promote_content_item_draft accept posts:[ContentVariantInput!] for an existing integration-owned, unsubmitted channel-less plain draft. Supply its current content-item version and stable requestKey. Each entry needs channelId and explicit text, with its own optional media/options/mode/dueAt/source/requestApproval. Empty text requires media. Original source text/media stay saved; omitted entry media is empty, never implicitly inherited. This form preserves the original contentItemId and saves every destination atomically. Do not mix posts with channelIds or top-level mode/dueAt/channelOptions/requestApproval. The existing uniform channelIds form is unchanged. Each ContentVariantInput entry accepts nullable aiAssisted: false remains false, null or omission records unknown, and changed entry text never inherits the original draft declaration. Each entry also accepts saveToDraft and publishingMethod: automatic|reminder. saveToDraft:true saves an unarmed channel-bound draft with drafts:write; it does not require a fresh publishing login or create a schedule/device reminder. Explicit null saveToDraft or publishingMethod is rejected. Mode/date on a saved entry is inert and not retained as reusable scheduling intent. Review-only entries need drafts:write+posts:review; automatic entries need posts:publish, subject to native team approval. Exact replay uses current access and returns the same result without new imports; changed input/key conflicts and a new promotion of an already-submitted draft are rejected. Canonical deleteContentItem cleans the complete group. Automatic URL shortening support is workflow-specific; settings are never silently disabled. The basic text profile is Facebook, Bluesky, LinkedIn, Threads, Tumblr, Google Business Profile, Mastodon and WordPress. Native-limited images/carousels also support Instagram and Pinterest. Single-video services are YouTube/TikTok/Facebook/LinkedIn/Instagram/Threads/Bluesky/Pinterest/Tumblr/Mastodon; one LinkedIn PDF uses its native document workflow. Supported formats still depend on the operation and native validation. Uniform scheduled promotion supports the implemented channel-option catalog, including native metadata, explicit privacy/consent, guarded preview/audio/cover observations and structured Facebook/LinkedIn mentions; unknown options and unsupported combinations are rejected. Review roles follow current native team/channel policy, recipient formats and feature permissions rather than granting publication. Manager client-approval review requires the existing native recipient-string format; Provisioned-team content-scheduler review also supports client-approval channels under the current native team/channel recipient policy; callers cannot choose recipients. Unsupported legacy role combinations remain rejected. Heterogeneous groups may combine saved, automatic and manual-reminder entries from the basic native text/media catalog. Each entry may use the implemented native channel-option catalog, subject to its publishing kind and native validators, including supported metadata, previews and structured mentions. Automatic Instagram audio uses guarded catalog observations; saved/manual audio stays inert without catalog lookup or publishing OAuth until a later automatic/native action. Required YouTube privacy/madeForKids and TikTok privacy/consent choices remain explicit; unknown options and unsupported combinations are rejected. Each unsaved entry chooses publishNow, schedule, addToQueue or prioritize, with native limits and current permissions. Automatic queue/priority reserves native schedules; manual queue/priority retains native reminder cadence/moves and requires a current device/configuration. Saving automatic/reminder intent remains inert: no schedule, device requirement or publishing-login requirement until explicit arming. Saved review remains unarmed after approval. Same-ID arming and native website share/reschedule/standalone clone support the closed stored text/media/choice catalog, including explicit native video/privacy/consent, Facebook/Instagram Story/Reel subtypes, LinkedIn PDF and TikTok photo choices. Stories require the native single-media/no-first-comment profile; Reels require video. Existing structured Facebook/LinkedIn mentions follow actual caption transformations; existing approved Instagram audio uses guarded native catalog authority. Opaque legacy SQL mention metadata must be resolved into supported structured choices. A new same-ID armed review may prepare its supported stored media/choices under review permissions; its schedule stays inactive, and it creates no publication certificate or dispatch. Original approved material is proved before a known selected-connector transformation; arbitrary approved text is never adopted. Existing creator-owned persisted UTM selections retain native factory/model ordering and original parameter semantics, including disabled-shortening factory conversion; there is no new public UTM selector. Metadata URLs stay literal, outside caption/title shortening. Native website flows use native permissions and the original author's settings, without borrowing API credentials. Explicit arm revalidates current publishing access/login/media/policy and a fresh mode/date. Shortening acceptance is not provider delivery.

Saved destination lifecycle: read the destination post ID/latest version, then call armDestinationDraft(id,version,requestKey,publishingMethod?,mode?,dueAt?,requestApproval?) or named arm_destination_draft(postId,...). It returns id/version/deleted, not a network delivery receipt. Public mode values are publishNow, schedule, addToQueue, prioritize. Omitted mode uses schedule when dueAt is supplied, otherwise queue. Choose a fresh mode/date at arm time. Omitted publishingMethod inherits the saved method (legacy automatic fallback); explicit null is invalid. Automatic arm rechecks posts:publish, native permissions, OAuth health, media and policy. A manual arm requires drafts:write+posts:publish, current signed-in mobile device/config and review permission where required, but not publishing OAuth; publishNow queues due-now manual finishing, never automatic network publication. Saved reminder intent is inert until armed.

Saved draft review: saveToDraft:true+requestApproval:true requires a channel approval policy plus drafts:write+posts:review. A pending signed saved review remains isDraft:true/dueAt:null and creates no schedule. Approval stays unarmed; explicitly arm its unchanged approved version. Changed content requires fresh review. Explicitly armed automatic review instead suspends its schedule until approval. Named edit_post(draft:true) edits safe saved destinations. Read allowedActions and current versions; group/post versions differ. deleteContentItem/delete_content_item is canonical group cleanup; draft-only callers can discover it, while armed groups recheck publishing permission and pending review requires withdrawal. Claimed/uncertain delivery cannot be blindly deleted. Named create/promote defaults include isDraft, publishingMethod and manualReminder{state,providerDeliveryConfirmed}; get_post or generic GraphQL can read fuller state. SDK0.1.14 getPost keeps its compact projection, so use generic GraphQL/MCP for manual state; the immutable SDK is unchanged. Mixed saved/scheduled/reminder groups remain atomic and retain per-destination actions.

Composer-source tracking: createDraft/createPost/createThread and each createContentItemVariants entry accept nullable source, a caller-declared label limited locally to 250 characters. Matching named MCP creation tools include review posts. A thread shares its label across entries; variants may carry distinct labels. Creation omission/null means unknown. Named get_post and Node getPost include provenance; ordinary lists also include it. Lists with saved metrics omit provenance and animated-preview metadata within the unchanged query budget; read an individual post for both together. updatePost/updateDraft and named edit_post also accept source. Read post.provenance.composerSource/composerSourceBasis. Omission preserves, null clears; recorded provenance.source/sourceBasis and trusted ai_origin creation transport stay unchanged. This label does not authorize anything or prove authorship.

Whole-thread attachment edits: updateContentItem.threadEntries and named edit_content_item accept complete ordered existing entries with text and optional images, video, clearMedia and supported link choices. Omitted attachments are preserved; images:[] or clearMedia:true removes them. Use the current group version and stable requestKey. All destinations must be unattempted, unpublished and more than two minutes in the future. Imports run outside SQL and saving is atomic. Keep the existing entry count; resizing and combined media/scheduling edits remain unsupported. The eight-attachment request cap and normal provider/plan validation still apply.

Implementation preview. Read the deployed schema and granted scopes before issuing operations. This is SocialBlaze's own contract, not a drop-in Buffer endpoint. Ideas, snippets, planning notes and tags are not supported platform concepts.

LinkedIn bounded reports: usable observed rows can be returned with partial coverage after the traversal cap or a non-advancing valid cursor. Totals describe only the observed subset. Read enumerationComplete, basis and note; do not interpret an empty observed period as an exact account-wide zero. Malformed or identity-changing pagination remains an error.

Publishing-method conversion: updatePost(publishingMethod:automatic|reminder) and named edit_post switch one safe future post while retaining its ID. Supply current version and stable requestKey; drafts:write plus posts:publish are required. Only a single future automatic schedule or unnotified queued reminder with no attempts/review/thread membership qualifies. An active signed-in mobile push device is required for reminders. Scheduling, media, plan and current account access are revalidated atomically. This does not confirm provider delivery.

## Links
- Documentation: https://wp.socialblaze.ai/developer-docs
- Signed-in developer console: https://wp.socialblaze.ai/developers
- GraphQL schema: https://wp.socialblaze.ai/developer/schema.graphql
- GraphQL endpoint: https://backend.socialblaze.ai/api/developer/graphql
- Remote MCP endpoint: https://backend.socialblaze.ai/api/developer/mcp
- OAuth discovery: https://backend.socialblaze.ai/.well-known/oauth-authorization-server/api/developer
- Support: admin@socialblaze.ai

## Authentication and boundaries
Send Authorization: Bearer with a scoped developer key or an endpoint-bound developer OAuth access token. Existing website session and interactive AI tokens are separate. Keep secrets on a trusted server, never public browser code, URLs, logs or source control. Customers select permitted channels and can revoke an app. Keys do not multiply workspace quotas.

Custom HTTP clients should include an identifying User-Agent such as SocialBlazeDeveloperClient/0.1 (+https://socialblaze.ai/api), plus Accept: application/json and Content-Type: application/json. Generic or absent signatures can be rejected by Cloudflare before API authentication. Credentials belong only in Authorization, never in User-Agent or a URL.

Scopes: accounts:read, posts:read, content:read, drafts:write, posts:publish, posts:review, library:read, library:write, analytics:read. content:read is a separate optional workspace-content discovery permission and also requires posts:read; it is not added to existing grants. Automatic publication requires explicit posts:publish consent and native team/plan permission. posts:review never grants publication. OAuth uses authorization-code/S256 PKCE, exact registered callbacks, one-use codes, rotating refresh tokens and audience-bound resources.

## Posting workflow
1. Read channels and configuration; use only authorized channel IDs.
2. Create a draft with createDraft, or use createDraftFromLibraryItem with a current library version.
3. Use createPost or submitDraft only for the user's intended mode: publishNow, schedule, addToQueue or prioritize. Explicit schedule needs a future dueAt. Never silently choose TikTok privacy/consent or YouTube made-for-kids settings.
4. Accepted is not delivered. Read every returned post ID and status, publishingState, failure and publishedUrl.
5. Retry a write only with the SAME requestKey and unchanged inputs. A timeout or PUBLISHING_UNCONFIRMED is not permission to publish another copy.
6. Read the latest version before edits, moves, cancellations or approval requests. Imminent, in-flight, delivered and ambiguous posts are protected.

CreatePost(requestApproval:true) or requestPostApproval uses the native review flow with suspended schedules. withdrawPostApproval returns an unpublished review post to a draft only when native approval permissions permit it.
For an integration-owned plain single-channel draft whose channel requires approval, updatePost(approvalChange:request) atomically edits the draft and requests native review; approvalChange:revert returns it to an unscheduled draft. Named MCP edit_post accepts these choices without requiring text. Supply drafts:write and posts:review, a current version and a stable requestKey. Attachments and content options may be edited in the same request. These review edits cannot schedule or publish. Native approval alone never publishes this review draft; explicitly submit the unchanged approved draft afterward. Changing approved content requires review again.

CreateThread supports ordered Bluesky, Mastodon and Threads chains: 2-25 entries, eight attachments total, at most 100 destination posts. Replies require confirmed parent IDs/generations. Reschedule/delete a root to change/cancel the complete safe future chain. Update thread content groups with ordered threadEntries, not a single caption copied to every reply.

## Media and templates
Use direct public HTTPS files. Standard image-post limits: Facebook/Instagram/Tumblr/WordPress 10; LinkedIn/Threads 20; TikTok 35; Bluesky/Mastodon/Google Business Profile 4; Pinterest 1; YouTube 0. JPEG/PNG/WebP images are limited to 8 MB each. A shared post must fit every selected destination. Multi-post groups and threads retain eight attachments total per request. Reels require one video; automatic Stories require one image or video. Alternatively attach one MP4/MOV video (50 MB), or one titled LinkedIn PDF (20 MB; provider page-count requirements apply). Source bytes are checked; private addresses and unsafe redirects are refused. Current channel capabilities determine valid formats and post types.

Library operations use the account's actual content library: libraryItems, libraryItem, createLibraryItem, updateLibraryItem, deleteLibraryItem and createDraftFromLibraryItem. Preserve current versions. Reuse text/image/video/PDF templates; each selected destination must support the attachment. Removing attachments/templates does not delete shared stored files.

## Reports
Ordinary channelReport, postPerformance, rankedPosts and aggregatedPostMetrics reads use existing SocialBlaze website data and saved snapshots only. A read never contacts a provider, creates a report job or refreshes missing data. Use storedChannelAnalytics / get_stored_channel_analytics for original native sections, available stored date ranges and source/freshness metadata. Native labels and measurement bases are retained; recordUpdatedAt is not per-metric collection time. Missing data is unavailable, never zero. Publishing-token expiry alone does not block an otherwise authorized historical read. Optional post/posts and named get_post/list_posts includeMetrics:true requires both posts:read and analytics:read plus explicit metricSnapshots pins (channelId, reportId, startDate, endDate). This reads saved snapshots only: no provider requests, report jobs or refresh-budget charge. Preserve metricsState, metricsErrorCode, metricsUpdatedAt and each metric status/basis; missing or unavailable data stays null. Stored history can be stale; preserve the associated report's stale and freshness indicators instead of treating it as newly collected. Omit includeMetrics for ordinary reads. Normal work/complexity limits still apply. Preserve report IDs, complete/status/basis and unknown freshness. Content-bound native snapshots can change when stored data changes; start a new read instead of reusing an old cursor on a different snapshot. Date ranges are up to 365 days within the account's real plan history. Coverage differs by provider.

Provider collection is separately explicit: refreshChannelReport (GraphQL mutation) / refresh_channel_report (MCP). Run it only after an explicit request to collect new provider data. It may require current provider analytics permission and consumes the separate refresh budget. If queued, poll channelReport with the returned report ID and exact dates. Stored readers never sign in, reconnect accounts or call this operation automatically.

Use publishingActivity for retained local record counts, not exact historical submissions or provider-only history. Each destination and thread entry counts separately. Counts include retained soft-deleted automatic posts, exclude drafts and manual reminders, and group by original creation date in the requested timezone. currentlyDelivered is current status among that creation cohort.

Use rankedPosts with an explicit metric and lifetime or period_total basis. Preserve unit, comparisonBasis, coverage and excluded counts. Rates use percentage units and cannot be summed or ranked across different known formulas. LinkedIn unique reach cannot be summed across posts. Facebook likes are distinct from total reactions when available. A partial snapshot may rank observed posts but does not establish the best post across unavailable history or prove that its copy caused the result.

## Limits and errors
Workspace work units: 60 per UTC minute, 500 per day, 7500 per month. Reads scale with validated complexity; mutations incur additional work. Imported media: 100 MB/day, 1 GB/month; report refreshes: 20/day, 500/month; API-origin posts: 25/channel/day. These preview caps are separate from website posting and provider limits.

Inspect GraphQL errors even with HTTP 200. 401 means invalid/expired/revoked credentials; 403 means permission denied; 409 means stale/conflicting/unsafe state; 422 includes validation guidance; 429 includes Retry-After. Do not expose provider exceptions, credentials or database details. Signed cursors must be reset when filters, sorting or selected access change.

## MCP
Discover the current scoped tool catalog. Named tools cover account/channel/post reads, post/thread creation, edits/deletion/moves, native review/withdrawal, templates and metrics. Generic query/mutation tools and schema resources use the same permissions and budgets. Configure a custom remote connection in a compatible client; marketplace listing or support for every vendor-specific configuration syntax is not implied.

## Instagram audio (experimental)
Use instagramAudioCatalog, searchInstagramAudioCatalog, searchInstagramAudio, trendingInstagramAudio and instagramAudio with accounts:read and a selected Facebook-Login Instagram channel. Query types are music/originalSound. Responses preserve completeness, failedAudioTypes and safe errorCode; previews expire. Do not treat an unavailable catalog as an empty successful one.
For an Instagram single-video Reel, channelOptions may contain audioId, audioVolume and videoVolume (1-100). The selected track is checked before submission. createDraft accepts selected-channel options; post.channelOptions returns safe stored choices. Submission preserves those choices unless an explicit channel option entry replaces them. No audio is downloaded by SocialBlaze.

## Explicit link cards
Channel options accept linkUrl for standard Facebook, LinkedIn, Bluesky and Threads posts without other attachments. LinkedIn/Bluesky optionally accept linkTitle (200 chars), linkDescription (1000 chars) and protected linkThumbnailUrl. Facebook/Threads use the destination preview and reject custom title/description overrides. HTTPS only, no embedded credentials; no server scraping. Future updatePost.channelOptions can edit supported card fields; null linkUrl clears the card. Scheduled attachment replacement cannot silently discard a card. See protected-preview limits below.

Manual reminders: createPost accepts publishingMethod:reminder for up to 50 distinct channels with an active signed-in mobile push device. Manual queue and priority are separate from automatic schedules. Read manualReminder.state/dueAt; use changeReminder to reschedule/cancel/markPosted with a stable requestKey and current version. Notification acceptance and human confirmation never prove network delivery. Multi-channel reminders share imported media, are atomic and appear as one content item; deleting the item cancels its pending reminders. Approval reminders require requestApproval:true, posts:review plus explicit posts:publish consent, and the native team/client approval plan features. They wait for valid native approval, never run through automatic publishing, and are canceled if approval is withdrawn or becomes stale. Personal keys and authenticated app registrations are limited to 20 creations per UTC day, including revoked entries.

Video channel options: thumbnailOffset in milliseconds for one Instagram/TikTok/Pinterest video, inside its finite positive duration; Instagram Reels also accept shareToFeed, including false. A safe future updatePost can edit the cover on an existing tenant-owned MP4/MOV import or replace its video and choose the cover together. Arbitrary external videos are not eligible for cover-only edits; Stories reject cover/feed options. Omitted media and scheduling preserve the asset and time. Draft channelOptions edits preserve omitted fields; an empty list resets choices. Future updatePost.channelOptions supports validated network metadata, including cards, YouTube choices, Mastodon warnings and GBP business posts; unsupported combinations are rejected. Pinterest destinationUrl edits update the native destination and saved options; explicit null clears both. Null linkUrl clears card metadata. Use the latest version and reuse requestKey after an uncertain response. Read current saved options and capabilities before editing.
Typed outcomes: every mutation has a try-prefixed variant. Always select __typename, success result, and MutationError {code httpStatus message fields {field message} retryAfterSeconds}. Inspect both typed data outcomes and top-level errors; HTTP 200 alone is not success.

YouTube channel options: privacy and madeForKids are required for publishing. Optional embeddable, license (youtube or creativeCommon), notifySubscribers and isAiGenerated preserve explicit false. Future updatePost can change these metadata fields while retaining the imported video. isAiGenerated sets YouTube containsSyntheticMedia disclosure. Subscriber notifications are a Google upload query option, independent of public statistics visibility.

Approval reminders: createPost(publishingMethod: reminder, requestApproval: true) requires drafts:write, posts:review and explicitly consented posts:publish. Native team approval releases the reminder; it never enables automatic publishing. Withdrawal cancels it. A changed approval version cancels delivery. YouTube categoryId uses provider IDs from configuration.youtubeCategories, not internal website category row IDs.

Account/workspace metadata: account.organizations returns actual member totals, selected workspace ownership and native plan limits. Channel destinationId is the provider identifier; url/icon are safe public profile/network resources. GraphQL channels(first,afterId) and MCP list_channels(first,afterId) support bounded pages; MCP _meta.pagination includes nextAfterId and hasMore.
Post/library assets expose stored mimeType, nullable when unknown. Reads do not fetch media. Structured Facebook Page and LinkedIn mentions use channelOptions.mentions with Unicode code-point start/length offsets and matching text/entity. post.annotations returns safe readonly mentions and literal links; never assume byte or UTF-16 offsets. Invalid/stale ranges require correction before submitting.

Mastodon spoilerText is a content warning; warning plus prepared caption share the configured instance allowance. Warning text counts literally in graphemes; reserved URL and remote mention rules apply only to the caption. Read maxTextLength, textLimitsBasis, textLimitsMetadataAvailable and charactersReservedPerUrl to distinguish instance metadata from conservative configured fallback. Public metadata reads use only the operator-configured instance, with bounded cached requests and a 20000-character application safety cap. Instagram/YouTube isAiGenerated supports explicit AI disclosure. Instagram sets it on the parent container only. Threads link cards are supported; Facebook/Threads use the website preview.
Image/document thumbnailUrl is protected-imported as a SocialBlaze preview, capped at 1 MiB. LinkedIn/Bluesky linkThumbnailUrl is a custom provider card preview, capped at 1,000,000 bytes and eight distinct previews per request. Supply linkUrl when changing a preview, save draft changes before submitting, and use null to clear. Read configuration/channel capabilities; other networks reject custom link previews.

Instagram feed/Reel and Threads locationId is a provider public-place ID; locationName is your optional label. Instagram carousel children never receive the parent tag; automatic Stories reject it. Threads topic allows up to 50 graphemes without & or a period. Null clears saved fields.
post.allowedActions is non-authorizing guidance for safe local draft/future edits and cancellation, including connection ownership and publication fences. It is not an exhaustive list of every publishing/reminder/review tool. Always read the current version and handle a mutation refusing a stale state.

Instagram stickerFields {music products text topics other} are manual-reminder finishing instructions, up to 2,000 characters per field. They appear with copy controls on the signed-in reminder page. Automatic publishing and other reminder networks reject populated fields. They never automatically create stickers or select licensed music.

## Instagram image mentions and media dimensions

images[].userTags accepts up to twenty unique public handles per image, without @, with numeric normalized x/y coordinates from 0 to 1. Applies to Instagram feed images and each carousel child, not the carousel parent or automatic Stories. Remove positioned mentions before submitting an automatic Story. Other destinations reject positioned mentions. These are provider mentions, not internal content tags. Library images retain userTags when reused. Asset width/height are measured once on the bounded local import; absent legacy or unmeasurable dimensions remain null. Reading media never downloads files to guess dimensions.

## Atomic channel variants and named MCP tools

createContentItemVariants(requestKey,title,posts) / create_content_item_variants accepts distinct channel entries with independent text/title/media/channelOptions/mode/dueAt/requestApproval. Maximum 25 destinations and eight attachments total; existing shared media/work/plan limits apply. Same attachments import once. Failure rolls back every destination and new upload. hasChannelVariants identifies the group; campaign and destination titles are independent. Read individual post versions for individual edits; group text/media edits apply everywhere intentionally. Acceptance is not delivery.

Named MCP group tools include list_content_items, get_content_item, create_content_item_draft, edit_content_item_draft, delete_content_item_draft, promote_content_item_draft, edit_content_item, delete_content_item, add_post_to_content_item and remove_post_from_content_item. get_publishing_configuration and get_channel return actual supported network/media requirements. get_channel_report accepts first/after; preserve reportId, dates and channelId across pages of one snapshot. Never reuse a cursor with another snapshot or bypass quota.

## Stored format and scheduled-date filters

GraphQL posts and MCP list_posts accept postTypes (post, reel, story, carousel, short, thread) and dueAtPresence (present or absent). These read stored native formats, not permission to publish additional formats on a network. Thread entries are threads; missing legacy formats are standard posts. Date presence matches returned dueAt: earliest active schedule, then the legacy post date. Empty postTypes matches nothing. Clear after when filters change. Invalid GraphQL variables are client errors, not transient server failures.

## CLI

Use socialblaze account, channels, posts list/get/create/update/move, drafts create, tools list/describe/call, schema list/describe or doctor. tools call NAME accepts every tool granted to the credential. Inputs use --json JSON, --file FILE or --stdin; --fields projects response fields. --dry-run checks advertised basic schema rules without invoking the tool; discovery still uses quota and does not validate provider/business outcomes. Write requestKey is caller-owned, and uncertain writes are never automatically retried. Environment credentials are recommended; explicit init --save-token can persist a token as described below. Exit codes: 2 invalid input, 3 unauthorized, 4 quota, 5 conflict, 1 other error. Downloaded client0.1.7 includes init/config, completion generation and explicit offline managed agent-skill install/uninstall.

## Google Business post metadata

channelOptions.businessPost accepts type standard/event/offer, action, actionUrl, title, startDate, startTime, endDate, endTime, couponCode, redeemUrl and terms. Events/offers require title (58 characters maximum) and YYYY-MM-DD dates; HH:mm times are both supplied or both omitted for local 00:00:00–23:59:59. Event calendar fields are not publication dueAt. Standard/events support BOOK/ORDER/SHOP/LEARN_MORE/SIGN_UP/CALL. Non-CALL actions need HTTPS actionUrl; CALL rejects a URL. Offers reject action buttons and accept couponCode (58), redeemUrl (HTTPS) and terms (5000). No credential-bearing URLs or cross-network metadata. Omitted metadata survives future edits; a provided object replaces it; null resets. Automatic publishing only, not manual reminders. Read saved post.channelOptions.businessPost and capability businessPostOptions. Existing 1500-character text and image-only limits remain. Recurrence and live provider acceptance are not implied. Reference: https://developers.google.com/my-business/reference/rest/v4/accounts.locations.localPosts

## First comment limits

First comments use UTF-16 units, with Facebook 5000, Instagram 2200, LinkedIn 1250 and Threads 500. Non-BMP emoji count as two units. Read maxFirstCommentLength and firstCommentLengthUnit from channel capabilities/configuration. Drafts, per-channel variants and scheduled edits retain text without truncation. Unassigned drafts can store up to 5000 characters; per-destination validation applies before submission. Unsupported networks and Stories reject populated comments, including the literal string 0. Native plan entitlement remains required. General caption counting and mobile-specific HTTP draft limits are separate.

## Content group filters
contentItems(status, sort) supports ContentItemStatus draftContent/postContent and up to two unique createdAt/updatedAt sort fields with asc/desc direction. ContentItem.status reflects submitted state. Cursors bind filters, order and selected-channel access. Discovery defaults to integration-owned groups. Explicit discovery:workspace on contentItems or contentItem requires separately granted content:read together with posts:read; existing credentials are not expanded automatically. This opts into native workspace/draft visibility and the selected-channel grant. Groups containing inaccessible destinations are excluded rather than exposing their shared text/assets. managedByCurrentIntegration records creator/connection ownership, not a permission grant: cross-integration GROUP mutations remain blocked, and individual post operations retain independent authorization. Cursors also bind discovery; reset them when it changes. MCP list_content_items/get_content_item and SDK0.1.7 contentItems/contentItem accept the same explicit option. No planning dates or expanded permissions are added.

## Local activity, explicit ranking and work pricing
publishingActivity / get_publishing_activity counts retained local automatic post records by original creation date in calendar dates/timezone. Includes only aggregate counts for soft-deleted records; no deleted text is exposed. Destination and thread entries count separately. Original draft creation can precede submission, so this is not exact submission-date or delivery-date history. currentlyDelivered is current status, not delivery timing. Explain basis/countUnit/note with summaries.
rankedPosts / rank_posts requires explicit metric and metricBasis lifetime/period_total. Preserve per-network service and complete/partial/queued/unavailable coverage. Unknown metrics and different bases are excluded, real zero retained. Use report pins for stable comparisons. Observed performance is not causal copy quality. Entirely unavailable sources are unavailable, not ready/empty history.
Work pricing uses the selected operation and reachable fragments: ceil(complexity/25), minimum1, plus2 for mutations. Configuration exposes complexityPerWorkUnit/mutationWorkUnits. Headers X-RateLimit-Charged-Work-Units and X-RateLimit-Cost-Basis and MCP _meta expose charges. Limits60/minute500/day7500/month remain shared; no key multiplication or quota resets. Provider refresh/media/native publishing budgets remain independent. Cached reads cost local work without creating extra refresh reservations.
Caption rules: most services UTF16; LinkedIn recognized HTTP(S) URLs24units; Instagram logical newlines2units. Facebook5000,Instagram2196,Pinterest/YouTube titles100. GBPnative1500. Mastodon uses official graphemes, configured-instance maxCharacters/reserved URL metadata and remote mention suffix rules; content warnings remain literal. Metadata fallback is explicitly labeled, not a successful server read. Bluesky counts compact visible URL labels and publishes full destinations in UTF-8 byte-indexed facets; saved raw captions retain original URLs. Text is never silently truncated. These provider-specific rules are not identical to every Buffer guide's counting description.

Template metadata and visibility: libraryItems accepts visibility private/internal. LibraryItem returns nullable description/emoji and non-null visibility. Create/update accept description (1000 chars), emoji (32 chars), visibility private/internal; null clears description/emoji, omission preserves them. Default/legacy visibility remains internal (workspace shared), unlike Buffer's private default. Only creators may make a template private; private access is creator-only across developer/native/mobile paths. There is no public curated catalog. Existing native library, plan/role rules and workspace allowance remain. Native edits retain metadata. Every write needs requestKey and edits need latest version.
Thread entries can carry linkUrl; Bluesky supports title/description/protected thumbnail URL and Threads uses its destination preview. These per-entry cards reject Mastodon and other attachments, share protected imports, and preserve parent-delivery safety. Acceptance is not delivery. One owned two-entry Bluesky chain has provider-verified root/parent IDs, independent cards and exact cleanup; this does not verify Threads reply cards or every format combination.

CLI setup is available in the downloaded Node0.1.7 package: init/config for explicit local defaults, context / context --list for offline agent guidance, completion bash/zsh/fish/powershell for generated scripts. Explicit socialblaze install claude or install codex installs the managed bundled skill into ~/.claude/skills/socialblaze-api or ~/.agents/skills/socialblaze-api; uninstall claude/codex removes only an unchanged managed installation. Customized, unowned or linked content is preserved; concurrent setup is refused. Package installation and init never install skills or change shell profiles automatically. These offline commands neither grant account access nor authorize publishing. Environment credentials are recommended; only explicit init --save-token persists an environment credential to an unencrypted global file outside the project. Repository config cannot supply credentials or origins; timezone/timeout may be overridden. Config output and request errors redact stored keys. See package README for actual precedence and limitations; Version0.1.5 fixes nested zsh completion; static command suggestions were checked in actual network-disabled bash, zsh ZLE and fish runtimes, with PowerShell parser coverage. These checks do not certify arbitrary shell setups, remote tools or hosted-client behavior.

Recorded provenance and native state: post.provenance returns source/sourceBasis and nullable caller-declared aiAssisted/aiAssistanceBasis. createDraft/createPost/updateDraft/updatePost and named edit_post accept aiAssisted and preserve explicit false; null clears it, omission preserves the existing declaration. This does not change creation transport or infer authorship. An AI client request does not prove AI authored its text. Provider video disclosure is separate. account.preferences exposes nullable stored firstDayOfWeekCode/dateFormatCode/timeFormat, not inferred values. Channel queuePaused, workspacePublishingPaused and credentialsExpired describe separate native states; a pause is not credential expiry.

Channel discovery: named list_channels accepts first from 1 to 100 (default 20) and afterId. For larger pages, select only needed fields, for example id,name,service,timezone,postingTimes.{dayOfWeek,time}. Normal complexity and workspace work allowances still apply. Channel createdAt/updatedAt are nullable UTC timestamps; organizationId identifies the known native workspace and isLocked reflects the native lock flag. These fields do not expose inaccessible channels. Account avatar is a safe stored HTTPS picture or null, never a provider fetch.

Optional ranking metrics: viewers is a unique-per-post LinkedIn video count and is never summed across posts. totalTimeWatched is measured in minutes, converted from LinkedIn's documented milliseconds; it is not an average. These are lifetime organization-video statistics and depend on provider access and availability. Instagram follows is a media-attributed count for eligible feed posts and Stories, not Reels and not net account follower growth. Unavailable values remain null; optional enrichment failures do not become zero. Keep each report's basis, notes and coverage with the result. No Instagram watch-time unit is inferred.

Google Business Profile format discovery: postTypes additionally accepts event, offer and whats_new. These inspect the saved native businessPost type; they overlap the existing post bucket intentionally. Missing metadata is standard, while malformed or unknown metadata is not silently classified as standard. Format filters do not grant publishing support or prove delivery.

Automatic addToQueue/prioritize use configured posting times when available. For an empty queue without configured times, the developer API uses an editable five-minute fallback; it does not change native website queue behavior. Read dueAt and current version before edits/cancellation. A queued or processing local status alone does not prove a provider request occurred.

TikTok: photo caption4000 UTF16/title90, video2200. isAiGenerated is video disclosure; preserve explicitfalse. Developer publish_id acceptance staysprocessing until a verifiedcallback OR boundedproviderstatusread confirmscompletion on the SAME originalattempt; no newpublication/retry and no fabricatedpublicURL. Analytics lists publicvideosonly: complete=false even enumerationComplete=true; photos/privatevideos excluded. Preserve basis/note/enumerationComplete through aggregate and ranked channel coverage.

tiktokPostingChoices(channelId) / get_tiktok_posting_choices / SDK.tiktokPostingChoices(channelId): explicit accounts:read provider read for selected current unlocked TikTok channel; privacy choices/restrictions/duration only, cached up to60seconds,6uncachedreads/minute/channel. Never infer audience or consent; publication revalidates current choices.

Format rules: configuration.services.contentRules / channel.capabilities.contentRules describe automatic local per-format attachment/caption/title/MIME/byte/required-choice constraints. Not current provider permission or delivery. CLI --fields and named MCP fields accept bounded dot paths and sibling groups; server builds minimal validated GraphQL selection. all restores tool default only. Preserve write IDs/versions and report basis/coverage/notes. Generic query uses supplied document. No permission/quota bypass.

recordedCommitEvents separately counts retained native committed attempts by acknowledgement date. Acceptance may precede delivery; never call these delivery totals. Preserve commitEventBasis, commitEventCountUnit, commitEventNote and commitEventHistoryComplete=false. Aggregate metricsUpdatedAt is latest known contributing timestamp; oldestMetricsUpdatedAt is oldest and null if any ready source timestamp is unknown.

Zapier MCP Client editors may flatten channelIds arrays into strings. Strict named tools reject strings. Use execute_mutation with one GraphQL mutation string containing a literal channelIds array when this editor cannot preserve an array. Keep a stable requestKey and inspect structured errors.
Retain createPost/createThread.contentItemId. A destination deletion may preserve its source draft; remove a complete local group through versioned deleteContentItem and verify group/source/destination absence. Never deletePost a submitted channel-less source.

Images may include separate animatedThumbnail: a protected public GIF/WebP preview up to 1 MiB, accounted independently from thumbnailUrl. It never replaces the original publisher image. Post and library assets expose animatedThumbnail plus isAnimated, which stays null until animation is measured. A URL or extension is not animation proof. Node0.1.14 getPost/contentItem include assets; compact listPosts does not. Matching named image creation/edit inputs support the preview; ordinary named reads include it, while metrics-list projections omit it under the existing complexity limit.

updatePost(saveToDraft:true) can return an owner-managed, unattempted automatic destination with one schedule more than two minutes away to draft on the same ID, preserving its group and attachments. Use current version/stable requestKey and both posts:publish+drafts:write. This is timing-only: edit content afterward, then explicitly rearm. Review/reminder/thread/provider-attempt states retain dedicated paths.

Performance and ranked rows expose optional publicationDate/publicationTimeBasis. A stored native calendar day with unknown timezone retains publishedAt:null and native_calendar_day_timezone_unknown basis; never fabricate midnight UTC or an exact ordering within that day. Preserve each network post separately; do not deduplicate by linked article unless requested.

posts/list_posts and Node0.1.14 post reads support publishedAfter/publishedBefore and publishedAt sorting. Default descending record-ID order matches the native website feed within currently authorized selected channels; a limited grant does not expose every workspace channel. publishedAt is nullable and based only on eligible native recorded delivery evidence; preserve publishedAtBasis. Creation, edits, due dates and acceptance timestamps never substitute for unknown publication time. Unknowns sort last, so do not claim complete chronological last-ten coverage from a partially known set. Keep each network post ID/channel/URL; do not group by article. Reset cursors when changing filters/sort.


publishedActivity / get_published_activity / Node publishedActivity counts retained currently-delivered destination records by known eligible native recorded delivery time in the requested calendar range/timezone. Same timestamp rules as nullable post.publishedAt; no created/edited/planned/acknowledgement fallback. One network destination/thread record each, not unique articles or republication events. Preserve rangeStartUtc/rangeEndUtcExclusive, basis/countUnit/note, complete:false and includesSoftDeleted:true. unknownTimeExcluded covers ALL selected retained currently-delivered records with unknown times, not an inferred unknown monthly population. Unsupported channel counts remain null. Purged/overwritten/provider-only history prevents complete publication history. This is distinct from original-creation-cohort publishingActivity and acknowledgement recordedCommitEvents; no provider collection. CLI uses tools call get_published_activity with exact dates/timezone and granted channelIds.


publishedAtBasis=native_terminal_delivery_observed means the first local confirmation of an audited terminal response for the same physical post/destination/external object, not an independently verified original provider publication instant. Preserve the basis and monthly count note. Existing-object edits retain the first observation; clones need their own proof. Unknown history is not backfilled; upload/processing/acceptance acknowledgements do not create this proof. SDK0.1.14 declarations include this additional basis alongside native_recorded_delivery_time and null; runtime request methods are unchanged.