Stories

Stories are the recommended way to manage advocacy content. They replace the legacy Board Messages endpoint and provide enhanced functionality including multi-network support, rich media, and better content organization.

Stories are articles or media assets that you share with advocates on the advocacy board. Each story can include multiple messages tailored for different social networks, all sharing the same media assets. This allows advocates to easily share branded content across their personal social channels with network-optimized messaging.

Get Story

Get the data for a single story.

Example Request

curl -i https://api.oktopost.com/v2/story/0AS00000000000x

Example Result

{
	"Result": true,
	"Item":
	{
            "ID": "0AS00000000000x",
            "Created": "2022-12-13 17:22:52",
            "Modified": "2022-12-13 17:47:44",
            "AccountId": "0017ym7zlYsOsO7",
            "CreatedBy": "00A00000000000x",
            "ModifiedBy": "00A00000000000x",
            "BoardId": "brd00000000000x",
            "CampaignId": "002rfqmpadczzge",
            "PublishDate": "2022-12-19 14:00:00",
            "ExpirationDate": "2023-06-14 02:59:59",
            "IsFeatured": false,
            "Title": "🎅🏼 Christmas Rhymes about Oktopost",
            "Description": "A few Christmas rhymes to share around the holiday season :)",
            "ImageUrl": null,
            "LinkTitle": null,
            "LinkUrl": null,
            "LinkDescription": null,
            "LinkContent": null,
            "Type": "text",
            "Status": "draft",
            "ShareCount": 0,
            "AltTexts": null,
            "VideoTitle": null,
            "VideoPreview": null,
            "VideoSubtitle": null,
            "PreviewFrame": null,
            "WorkflowId": null,
            "Messages":
            [
                {
                    "Id": "00500000000000x",
                    "Network": "LinkedIn",
                    "Message": "'Twas the night before Christmas, and all through the land 🎅\nB2B marketers were bustling, with campaigns in hand\nThey used @Oktopost, the social media platform of choice\nTo share their content and give their brand a voice\n\nWith features like scheduling and analytics galore 🗓\nOktopost made it easy to connect and explore\nTheir platform helped marketers reach their goals\nAnd spread holiday cheer to B2B folk and trolls 🎄\n\nSo as we sit by the fire and sip our cocoa ☕\nWe thank Oktopost for making our work easier to show\nMerry Christmas to all, and to all a good night\nFrom Oktopost, the best B2B social media platform in sight! 🤗",
                    "Type": "text",
                    "Mentions":
                    [
                        {
                            "Id": "urn:li:organization:123456",
                            "Text": "Oktopost"
                        }
                    ],
                    "LinkTitle": "",
                    "LinkUrl": "",
                    "Description": "",
                    "ImageUrl": "",
                    "VideoPreview": "",
                    "VideoTitle": "",
                    "VideoSubtitle": "",
                    "Media": []
                }
            ],
            "Media":[],
            "Topics":
            [
                "Oktopost Content"
            ],
            "Tags":
            [
                "Thought Leadership",
                "Christmas"
            ]
        }
}

Get Stories

List stories in a board.

Example Request

curl -i https://api.oktopost.com/v2/story?boardId=brd00000000000x

Example Result

{
    "Result": true,
    "Total": 83,
    "Items":
    [
        {
            "ID": "0AS00000000000x",
            "Created": "2022-12-13 17:22:52",
            "Modified": "2022-12-13 17:47:44",
            "AccountId": "0017ym7zlYsOsO7",
            "CreatedBy": "00A00000000000x",
            "ModifiedBy": "00A00000000000x",
            "BoardId": "brd00000000000x",
            "CampaignId": "00200000000000x",
            "PublishDate": "2022-12-19 14:00:00",
            "ExpirationDate": "2023-06-14 02:59:59",
            "IsFeatured": false,
            "Title": "🎅🏼 Christmas Rhymes about Oktopost",
            "Description": "A few Christmas rhymes to share around the holiday season :)",
            "ImageUrl": null,
            "LinkTitle": null,
            "LinkUrl": null,
            "LinkDescription": null,
            "LinkContent": null, 
            "Type": "text",
            "Status": "draft",
            "ShareCount": 0,
            "AltTexts": null,
            "VideoTitle": null,
            "VideoPreview": null,
            "VideoSubtitle": null,
            "PreviewFrame": null,
            "WorkflowId": null,
            "Messages":
            [
                {
                    "Id": "00500000000000x",
                    "Network": "LinkedIn",
                    "Message": "'Twas the night before Christmas, and all through the land 🎅\nB2B marketers were bustling, with campaigns in hand\nThey used @Oktopost, the social media platform of choice\nTo share their content and give their brand a voice\n\nWith features like scheduling and analytics galore 🗓\nOktopost made it easy to connect and explore\nTheir platform helped marketers reach their goals\nAnd spread holiday cheer to B2B folk and trolls 🎄\n\nSo as we sit by the fire and sip our cocoa ☕\nWe thank Oktopost for making our work easier to show\nMerry Christmas to all, and to all a good night\nFrom Oktopost, the best B2B social media platform in sight! 🤗",
                    "Type": "text",
                    "Mentions":
                    [
                        {
                            "Id": "urn:li:organization:123456",
                            "Text": "Oktopost"
                        }
                    ],
                    "LinkTitle": "",
                    "LinkUrl": "",
                    "Description": "",
                    "ImageUrl": "",
                    "VideoPreview": "",
                    "VideoTitle": "",
                    "VideoSubtitle": "",
                    "Media": []
                }
            ],
            "Media":[],
            "Topics":
            [
                "Oktopost Content"
            ],
            "Tags":
            [
                "Thought Leadership",
                "Christmas"
            ]
        },
        ...
    ]
}

Add Story

Create a new Story in the board.

Parameters

Prop	Description	Required	Default
boardId	The Board Id	-	The oldest active board.
title	The story title	√	-
description	The story description	√	-
campaignId	The Campaign Id	√	-
mediaIds	Comma separated Media Ids	-	-
link	The link associated with the story	-	-
messageIds	Comma separated Messag Ids	-	-
topicIds	The topic ids related to this story	-	-
tagIds	The Tag ids related to this story	-	-
publishDatetime	Unix timestamp	-	Now
expirationDatetime	Unix timestamp	-	Based on the board’s default expiration date.
isDraft	Save the story as Draft	-	False
isFeatured	Mark the story as Featured	-	False
postlogId	The Postlog ID of a LinkedIn post to repost. When provided, the story is created as a repost (`type: post-attachment`). Title and description become optional and are auto-derived from the original post. The `link`, `mediaIds`, and `messageIds` parameters are ignored.	-	-
workflowId	Send the story to approval	-	-

Example Request

curl -i https://api.oktopost.com/v2/story -X POST \

	-d boardId="brd00000000000x" \
	-d title="🎅🏼 Christmas Rhymes about Oktopost" \
	-d description="A few Christmas rhymes to share around the holiday season :)" \
	-d campaignId="00200000000000x" \
	-d mediaIds="02600000000000x" \
	-d link="https://www.oktopost.com" \
	-d messageIds="005000000000001,005000000000002" \
	-d topicIds="tpc000000000001,tpc000000000002" \
	-d tagIds="0AF000000000001,0AF000000000002" \

Add Repost Story

Repost stories are LinkedIn-only. The postlogId must reference a successfully published LinkedIn post from your account. Passing a postlog ID from any other network returns a 400 error.

Create a story that advocates can reshare as a native LinkedIn repost. Instead of providing custom content, you supply the postlogId of an existing LinkedIn post. The story description is automatically derived from the original post's text, and the repost link is injected into advocate messages when they are generated.

When postlogId is provided:

title and description are optional (auto-derived from the original post)
link, mediaIds, and messageIds are ignored
Use generateMessages=true to automatically create advocate messages in the background

Example Request

curl -i https://api.oktopost.com/v2/story -X POST \
	-d boardId="brd00000000000x" \
	-d postlogId="00700000000000x" \
	-d generateMessages=true

Example Result

{
	"Result": true,
	"Item": {
		"ID": "0AS00000000000x",
		"Created": "2026-04-29 14:00:00",
		"Modified": "2026-04-29 14:00:00",
		"AccountId": "0017ym7zlYsOsO7",
		"CreatedBy": "00A00000000000x",
		"ModifiedBy": "00A00000000000x",
		"BoardId": "brd00000000000x",
		"CampaignId": "00200000000000x",
		"PublishDate": "2026-04-29 14:00:00",
		"ExpirationDate": "2026-10-29 02:59:59",
		"IsFeatured": false,
		"Title": null,
		"Description": "Excited to share our latest product update — faster dashboards, smarter analytics, and more. Check it out!",
		"PostlogId": "00700000000000x",
		"ImageUrl": null,
		"LinkTitle": null,
		"LinkUrl": null,
		"LinkDescription": null,
		"LinkContent": null,
		"Type": "post-attachment",
		"Status": "active",
		"ShareCount": 0,
		"AltTexts": null,
		"VideoTitle": null,
		"VideoPreview": null,
		"VideoSubtitle": null,
		"PreviewFrame": null,
		"WorkflowId": null,
		"Messages": [],
		"Media": [],
		"Topics": [],
		"Tags": []
	}
}

Edit Story

For repost stories, the repost association (PostlogId) is preserved automatically on update. You may optionally override the title and description; all other repost-specific fields remain unchanged.

Example Request

curl -i https://api.oktopost.com/v2/story/0AS00000000000x -X POST \
	-d boardId="brd00000000000x" \
	-d title="🎅🏼 Christmas Rhymes about Oktopost" \
	-d description="A few Christmas rhymes to share around the holiday season :)" \
	-d campaignId="00200000000000x" \
	-d mediaIds="02600000000000x" \
	-d link="https://www.oktopost.com" \
	-d messageIds="005000000000002" \
	-d topicIds="tpc000000000002" \
	-d tagIds="0AF000000000002" \

Delete Story

Example Request

curl -i https://api.oktopost.com/v2/story/0AS00000000000x -X DELETE

On this page