TypeScript client

import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.social.postNow({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  postId: process.env.OCTOSPARK_POST_ID ?? "postId",
  body: {},
})

{
  "data": [
    {
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scheduledPost": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "contentItemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "scheduledAt": "<string>",
        "timezone": "Europe/London",
        "platformPostId": "<string>",
        "platformSettings": {},
        "publishResults": {},
        "providerPublishState": {
          "requiresPolling": true,
          "publishId": "<string>",
          "platformPostId": "<string>",
          "providerStatus": "<string>",
          "pollingReason": "<string>",
          "uploadProgress": {
            "nextByteStart": 123,
            "uploadSize": 123
          },
          "failureCode": "<string>"
        },
        "errorCode": "<string>",
        "errorMessage": "<string>",
        "workflowId": "<string>",
        "workflowRunId": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>"
      },
      "error": {
        "message": "<string>",
        "code": "<string>"
      },
      "linksMovedToFirstComment": [
        "<string>"
      ]
    }
  ],
  "outcome": {
    "totalCount": 123,
    "successCount": 123,
    "failureCount": 123
  },
  "captionWarnings": [
    {
      "severity": "warning",
      "message": "<string>",
      "fixable": true,
      "provider": "instagram",
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Posts

Post now

Publish a post immediately to one or more social accounts via socialAccountIds. The call handles each account separately and returns HTTP 200 with one result per account: each entry in data[] is either a scheduledPost or an error (including insufficient credits on costed providers, which reserve credits per account), plus an outcome summary (status, totalCount, successCount, failureCount). Always read the per-account results in the body rather than trusting the status code alone. Links move into a first comment on first_comment channels exactly as for schedulePost (opt out with autoMoveLinks=false), and captionWarnings lists the remaining caption-quality warnings per channel. Send an Idempotency-Key header so timed-out retries replay the original result instead of double-publishing; use schedulePost to publish at a future time instead.

POST

teams

{teamId}

posts

{postId}

post-now

TypeScript client

import { OctosparkClient } from '@octospark/sdk'

const client = new OctosparkClient({
  token: process.env.OCTOSPARK_TOKEN
})

const response = await client.social.postNow({
  teamId: process.env.OCTOSPARK_TEAM_ID ?? "teamId",
  postId: process.env.OCTOSPARK_POST_ID ?? "postId",
  body: {},
})

{
  "data": [
    {
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scheduledPost": {
        "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "contentItemId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "scheduledAt": "<string>",
        "timezone": "Europe/London",
        "platformPostId": "<string>",
        "platformSettings": {},
        "publishResults": {},
        "providerPublishState": {
          "requiresPolling": true,
          "publishId": "<string>",
          "platformPostId": "<string>",
          "providerStatus": "<string>",
          "pollingReason": "<string>",
          "uploadProgress": {
            "nextByteStart": 123,
            "uploadSize": 123
          },
          "failureCode": "<string>"
        },
        "errorCode": "<string>",
        "errorMessage": "<string>",
        "workflowId": "<string>",
        "workflowRunId": "<string>",
        "createdAt": "<string>",
        "updatedAt": "<string>"
      },
      "error": {
        "message": "<string>",
        "code": "<string>"
      },
      "linksMovedToFirstComment": [
        "<string>"
      ]
    }
  ],
  "outcome": {
    "totalCount": 123,
    "successCount": 123,
    "failureCount": 123
  },
  "captionWarnings": [
    {
      "severity": "warning",
      "message": "<string>",
      "fixable": true,
      "provider": "instagram",
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Authorizations

Authorization

string

header

required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Headers

idempotency-key

string

Optional. Reuse the same key (up to 200 characters) with the same request after a lost response to replay the original result instead of repeating the write.

Path Parameters

teamId

string

required

Team (workspace) id (UUID). Discover ids via the list teams endpoint or the agent context.

postId

string

required

Post id (UUID), as returned by the create post and list posts endpoints.

Body

application/json

UUIDs of the connected social accounts the post fans out to; at least one is required, duplicates are rejected, and each account gets its own per-account result.

Minimum array length: 1

a Universally Unique Identifier

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

Example:

["0a1b2c3d-4e5f-4a6b-8c7d-9e0f1a2b3c4d"]

expectedContentPayloadId

string<uuid>

Optimistic concurrency pin for the exact saved content payload this terminal delivery intent validated. The composer always supplies it.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$

platformSettings

object

Provider-specific publish settings. Each field applies to one provider (named in its description) and is ignored by accounts on other providers, so a single object can carry settings for every account the post targets. Unknown keys are rejected.

Show child attributes

Example:

{ "replySettings": "following" }

Per-account overrides of the shared platform settings, keyed by social account UUID; values merge over platformSettings for that account.

Show child attributes

overrideApproval

boolean

Records an internal approval for the current revision instead of waiting for client approval. Requires a signed-in human workspace admin (manage-level). Delegated API/MCP credentials and agent runs cannot create this approval. Automated publishing of already-approved posts remains supported without this option.

Example:

true

Per-account body-text overrides, keyed by social account UUID. An entry replaces the post's shared text for that account's leg only; accounts without an entry publish the shared text. Text-only: media attachments and platform settings are unaffected, and thread posts reject overrides. Entries must be non-blank.

Show child attributes

firstComment

object

Comment to post on the published post immediately after it goes live.

Show child attributes

engagementCommentTrigger

object

Comment to post once the published post reaches likeThreshold likes within windowHours (1 to 720 hours).

Show child attributes

repostAfter

object

Repost the published post offsetDays (1 to 30) after publish, either as a plain retweet or a quote (text required for quote mode).

Show child attributes

recurrenceIntervalDays

integer

Republish the post every N days (1 to 365) until recurrenceEndsAt.

Required range: 1 <= x <= 365

Example:

7

recurrenceEndsAt

string | null

ISO 8601 timestamp after which the recurrence stops; null means no end date.

Example:

"2026-09-01T00:00:00Z"

Per-account first comments, keyed by social account UUID. An entry replaces firstComment for that account's leg only.

Show child attributes

autoMoveLinks

boolean

Default true. For a channel whose link placement is first_comment, body URLs are moved into that channel's first comment (appended after a blank line to a first comment you already set, without repeating a URL it holds) and the caption says "link in the first comment" (or "first reply" on X and Threads). A link stays in the body when the first comment would pass the channel's comment limit. Pass false to publish the caption exactly as written.

Example:

false

Response

Success

data

object[]

required

One result entry per requested social account, in request order.

Show child attributes

outcome

object

required

Show child attributes

captionWarnings

object[]

Caption-quality warnings per destination channel (never blocking). Fix them before scheduling.

Show child attributes

Schedule post Move post to draft