TypeScript client

import { OctosparkClient } from '@octospark/sdk'

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

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "title": "<string>",
  "workflowStatusId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "text": "<string>",
  "assetIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "media": [
    {
      "assetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "mimeType": "<string>",
      "displayName": "<string>",
      "thumbnailPath": "<string>",
      "width": 123,
      "height": 123,
      "thumbnailUrl": "<string>",
      "fileUrl": "<string>",
      "previewUrlsExpireAt": "<string>"
    }
  ],
  "assetTags": [
    "<string>"
  ],
  "userTags": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "colour": "<string>"
    }
  ],
  "assignees": [
    {
      "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "email": "<string>"
    }
  ],
  "contentPayloadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "latestScheduledPost": {
    "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>"
  },
  "scheduledDestinationAccountIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "draftDestinationAccountIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "agentRunId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "substantialHumanRewrite": true,
  "postInput": {
    "kind": "atomic",
    "text": "<string>",
    "attachments": [
      {
        "kind": "media",
        "asset": {
          "assetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "mimeType": "<string>",
          "byteSize": 123,
          "width": 123,
          "height": 123,
          "durationSeconds": 123,
          "thumbnailUrl": "<string>",
          "altText": "<string>"
        },
        "altText": "<string>"
      }
    ]
  },
  "postPublishActions": {
    "firstComment": {
      "text": "<string>",
      "mediaIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "engagementCommentTrigger": {
      "likeThreshold": 2,
      "windowHours": 360,
      "comment": {
        "text": "<string>",
        "mediaIds": [
          "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        ]
      }
    },
    "repostAfter": {
      "offsetDays": 15,
      "text": "<string>"
    },
    "recurrenceIntervalDays": 183,
    "recurrenceEndsAt": "<string>"
  },
  "scheduledDestinations": [
    {
      "scheduledPostId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "text": "<string>",
      "platformSettings": {}
    }
  ],
  "publishActions": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scheduledPostId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "triggerConfig": "<unknown>",
      "payload": "<unknown>",
      "createdAt": "<string>",
      "parentPlatformPostId": "<string>",
      "scheduledFor": "<string>",
      "deadline": "<string>",
      "executedAt": "<string>",
      "platformResultId": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>"
      },
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "accountDisplayName": "<string>",
      "accountProfileImageUrl": "<string>",
      "summary": {
        "text": "<string>",
        "mediaCount": 123
      }
    }
  ],
  "captionWarnings": [
    {
      "severity": "warning",
      "message": "<string>",
      "fixable": true,
      "provider": "instagram",
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
    }
  ]
}

Posts

Create post

Create a draft post and atomically persist its content, workflow status, assignees, and user tags. Nothing is published by this call: the post stays in draft until you call schedulePost or postNow with target social accounts. The response carries captionWarnings (never blocking) for each destination channel: dense captions with no blank line, links in the body on first-comment channels, scattered hashtags, em dashes, missing utm parameters and stale dates. Fix them with updatePost (captions.formatCaption spaces a caption without changing words) before scheduling. Send an Idempotency-Key header so an ambiguous retry replays the original create; reusing the key with a different payload is rejected.

POST

teams

{teamId}

posts

TypeScript client

import { OctosparkClient } from '@octospark/sdk'

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

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

{
  "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "teamId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "title": "<string>",
  "workflowStatusId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "text": "<string>",
  "assetIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "media": [
    {
      "assetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "mimeType": "<string>",
      "displayName": "<string>",
      "thumbnailPath": "<string>",
      "width": 123,
      "height": 123,
      "thumbnailUrl": "<string>",
      "fileUrl": "<string>",
      "previewUrlsExpireAt": "<string>"
    }
  ],
  "assetTags": [
    "<string>"
  ],
  "userTags": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "colour": "<string>"
    }
  ],
  "assignees": [
    {
      "userId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "name": "<string>",
      "email": "<string>"
    }
  ],
  "contentPayloadId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "latestScheduledPost": {
    "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>"
  },
  "scheduledDestinationAccountIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "draftDestinationAccountIds": [
    "3c90c3cc-0d44-4b50-8888-8dd25736052a"
  ],
  "createdAt": "<string>",
  "updatedAt": "<string>",
  "agentRunId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "substantialHumanRewrite": true,
  "postInput": {
    "kind": "atomic",
    "text": "<string>",
    "attachments": [
      {
        "kind": "media",
        "asset": {
          "assetId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
          "mimeType": "<string>",
          "byteSize": 123,
          "width": 123,
          "height": 123,
          "durationSeconds": 123,
          "thumbnailUrl": "<string>",
          "altText": "<string>"
        },
        "altText": "<string>"
      }
    ]
  },
  "postPublishActions": {
    "firstComment": {
      "text": "<string>",
      "mediaIds": [
        "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      ]
    },
    "engagementCommentTrigger": {
      "likeThreshold": 2,
      "windowHours": 360,
      "comment": {
        "text": "<string>",
        "mediaIds": [
          "3c90c3cc-0d44-4b50-8888-8dd25736052a"
        ]
      }
    },
    "repostAfter": {
      "offsetDays": 15,
      "text": "<string>"
    },
    "recurrenceIntervalDays": 183,
    "recurrenceEndsAt": "<string>"
  },
  "scheduledDestinations": [
    {
      "scheduledPostId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "text": "<string>",
      "platformSettings": {}
    }
  ],
  "publishActions": [
    {
      "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "scheduledPostId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "triggerConfig": "<unknown>",
      "payload": "<unknown>",
      "createdAt": "<string>",
      "parentPlatformPostId": "<string>",
      "scheduledFor": "<string>",
      "deadline": "<string>",
      "executedAt": "<string>",
      "platformResultId": "<string>",
      "error": {
        "code": "<string>",
        "message": "<string>"
      },
      "socialAccountId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "accountDisplayName": "<string>",
      "accountProfileImageUrl": "<string>",
      "summary": {
        "text": "<string>",
        "mediaCount": 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.

Body

application/json

title

string | null

Internal display title for the post; null clears it. Not published to the platform.

Example:

"June launch teaser"

postType

enum<string>

Content format of the post; defaults to text_post.

Available options:

text_post,

text_image,

text_video,

carousel

Example:

"text_post"

text

string

Body text of the post; for thread posts use postInput instead.

Example:

"Shipping day! Here is what is new in v1."

postInput

object

Structured content: an atomic post (text plus optional media/link attachments) or a thread of 2 or more atomic posts. Takes precedence over text.

Option 1
Option 2

Show child attributes

assetIds

string<uuid>[]

UUIDs of previously uploaded media assets to attach to the post.

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"]

postPublishActions

object

Saved after-publish automations (first comment, engagement-triggered comment, repost, recurrence) applied when the post is scheduled or published.

Show child attributes

draftDestinationAccountIds

string<uuid>[]

UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.

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"]

workflowStatusId

string<uuid>

Team-owned content workflow status to assign atomically with the post save.

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}$

assigneeUserIds

string<uuid>[]

Full replacement set of team-member user ids assigned to the post. Empty clears every assignee.

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}$

userTagSelections

object[]

Full replacement set of existing or inline-created user tags. Empty clears every user-tag assignment.

Option 1
Option 2

Show child attributes

sourceIds

string<uuid>[]

Content source UUIDs this post was generated from. Records post-from-source provenance that drives each source's usedCount (deduplicated per post; every id must belong to the team or the create is rejected). When generating posts from sources, pass the ids of the sources actually used so least-used source rotation stays accurate.

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"]

Response

Success

string<uuid>

required

UUID of the post.

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:

"3c9d8e7f-6a5b-4c3d-9e2f-1a0b9c8d7e6f"

teamId

string<uuid>

required

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}$

postType

enum<string>

required

Content format of a post: text_post (text only), text_image, text_video, or carousel (2+ photos).

Available options:

text_post,

text_image,

text_video,

carousel

Examples:

"text_post"

"text_image"

artifactKind

enum<string> | null

required

Available options:

slideshow,

image_meme,

green_screen_meme

title

string | null

required

status

enum<string>

required

Editorial status of a post: idea, proposed_render, draft, approved, rejected, archived, or deleted.

Available options:

idea,

proposed_render,

draft,

in_review,

approved,

rejected,

archived,

deleted

Examples:

"draft"

"approved"

workflowStatusId

string<uuid>

required

Workspace-defined content workflow status currently assigned to the post.

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}$

text

string

required

assetIds

string<uuid>[]

required

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}$

media

object[]

required

Display metadata (mime type, name, thumbnail path) for the post's media, in the same order as assetIds. Empty for text-only posts.

Show child attributes

assetTags

string[]

required

Deduped, sorted union of the post's non-deleted assets' AI tags; empty for text-only posts.

Example:

["launch", "product"]

userTags

object[]

required

User/agent-assigned registry tags (id, name, colour) on the post; distinct from AI-derived assetTags. Empty when no tags are assigned.

Show child attributes

assignees

object[]

required

Team members assigned to the post (userId plus display name/email), in assignment order. Empty when unassigned. Set via the setPostAssignees endpoint.

Show child attributes

contentPayloadId

string<uuid>

required

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}$

latestScheduledPost

object

required

Show child attributes

scheduledDestinationAccountIds

string<uuid>[]

required

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}$

draftDestinationAccountIds

string<uuid>[]

required

UUIDs of the social accounts selected for this draft. Empty clears the saved selection and duplicates are rejected.

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"]

saveDestination

enum<string>

required

Available options:

queue,

drafts

saveMessage

enum<string>

required

Available options:

Saved to Queue,

Saved to Drafts

createdAt

string

required

updatedAt

string

required

agentRunId

string<uuid> | null

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}$

substantialHumanRewrite

boolean

postInput

object

Option 1
Option 2

Show child attributes

postPublishActions

object

Show child attributes

scheduledDestinations

object[]

The newest non-cancelled scheduled leg per social account, with the text and platformSettings that leg publishes. Empty for posts that were never scheduled.

Show child attributes

publishActions

object[]

Follow-up actions (first comments, reposts, ...) for every leg of the post, oldest first; the same rows listPostPublishActions returns.

Show child attributes

captionWarnings

object[]

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

Show child attributes

List posts Get post