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. Stories on archived boards are omitted. Set boardId to limit the list to one board. A valid ID for an archived board still returns no stories.

Parameters

Param	Default	Description
boardId	-	Optional board ID (`brd…`). An invalid ID returns 400. Archived boards are excluded.
status	-	One of `draft`, `scheduled`, `published`, `expired`. An invalid value returns 400. `scheduled`, `published`, and `expired` match stories whose `Status` is `approved`.
approveStatus	-	One of `pending`, `rejected`, `approved`. An invalid value returns 400.
createdBy	-	Comma-separated user IDs. An unknown ID returns 400.
topicIds	-	Comma-separated topic IDs (for example `tpc000000000001`). An unknown ID returns 400.
tagIds	-	Comma-separated tag IDs (for example `0AF000000000001`). A well-formed unknown ID matches nothing.
isFeatured	-	`true` or `1` for featured stories, `false` or `0` for stories that are not featured. Omit to include both.
isRepost	-	`true` or `1` for repost stories, `false` or `0` for other stories. Omit to include both. When `boardId` is a board without LinkedIn, or the account does not have repost stories, `isRepost=true` returns no stories.
q	-	Partial match on title or description. Maximum 255 characters.
_page	0	The current page (zero-indexed).
_count	20	Items per page. Any integer from 1 to 100. A value outside that range returns 400.
_order	publishDate,0	Sort field and direction. Options: created, publishDate, expirationDate, shareCount, isFeatured. `0` = descending, `1` = ascending. Any other field or direction returns 400.

See Pagination for shared behavior. This endpoint defaults to 20 items per page, sorted by publishDate,0, and accepts any _count from 1 to 100.

status and approveStatus are independent and can be combined. status=draft matches Status draft. scheduled, published, and expired match Status approved, split by dates: publish date in the future, currently in the publish window, or past expiration. The response Status for those stories stays approved. approveStatus=pending and rejected match Status. approveStatus=approved means an approved workflow item exists, which is separate from status=published.

Example Request

curl -i "https://api.oktopost.com/v2/story?boardId=brd00000000000x&q=christmas&status=published&_count=20&_order=publishDate,0"

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": "approved",
            "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. Maximum 1024 characters. Recommended up to 60 characters.	√	-
description	The story description. Maximum 1024 characters. Recommended up to 140 characters.	√	-
campaignId	The Campaign Id	√	-
mediaIds	Comma separated Media Ids	-	-
link	The link associated with the story	-	-
messageIds	Comma separated Messag Ids	-	-
topicIds	Comma-separated list of topic IDs (e.g. `tpc000000000001,tpc000000000002`), obtained from the Topics endpoint (`GET /v2/board-topic`). These are topic IDs, not topic names.	Conditional	-
tagIds	Comma-separated list of tag IDs (e.g. `0AF000000000001,0AF000000000002`), obtained from the Tags endpoint (`GET /v2/tag`). These are tag IDs, not tag names. Unrecognized IDs are silently ignored.	-	-
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	-	-

If the target board (or the default board, when boardId is omitted) has topics configured, topicIds is required and every ID must be one of that board's topics. Otherwise the request fails with The story cannot be saved without Topics (none provided) or Provided Topics don't match Board existing topics (an ID does not belong to the board). If the board has no topics configured, topicIds is optional.

topicIds and tagIds are supplied as IDs on the request, but the story response (Get Story and Get Stories) returns Topics and Tags as names. Use the Topics (GET /v2/board-topic) and Tags (GET /v2/tag) endpoints to look up the IDs.

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.

topicIds and tagIds use the same format as Add Story. On update, omitting a field preserves the story's existing topics or tags, while providing it replaces the full set for that story. On a topic-enabled board, a valid topicIds set may still be required when boardId is passed (same validation as when creating a story).

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