Skip Navigation Links

Posts

Endpoint Overview

GET /api/posts/v4/posts
Get Posts
POST /api/posts/v4/posts
Create a Post
GET /api/posts/v4/posts/bookmarks
Get posts bookmarked by the actor
POST /api/posts/v4/posts/bookmarks
Bookmark a Post
GET /api/posts/v4/posts/bookmarks/count
Get posts bookmark count for the actor
GET /api/posts/v4/posts/bookmarks/exist
Check whether the actor has any bookmarked posts
DELETE /api/posts/v4/posts/bookmarks/{post_id}
Remove a Post Bookmark
GET /api/posts/v4/posts/to-approve
Get Posts to Approve
GET /api/posts/v4/posts/{post_id}
Get a Post
PATCH /api/posts/v4/posts/{post_id}
Update a Post
POST /api/posts/v4/posts/{post_id}/move
Move a Post
POST /api/posts/v4/posts/{post_id}/reports
Report a Post
GET /api/posts/v4/posts/{post_id}/translate
Get a Post Auto-Translation
POST /api/posts/v4/posts/{post_id}/translate
Trigger a Post Auto-Translation

Get Posts

Requires authentication via bearer.

Get a paginated collection of posts the actor has access to. The result can be narrowed down by channel, status, highlight, newsfeed and date filters, ordered via sort, and enriched via embed in the same way as the single-post endpoint.

Query Params

channel_id string[]
author_id string

Only return posts authored by this user.

status string[]

A post status that can be used to filter the posts collection.

only_highlighted boolean

When true, only return posts that are currently highlighted.

only_newsfeed boolean

When true, only return posts from channels whose posts are shown on the newsfeed. Must not be combined with channel_id or only_schedulable_channels.

only_schedulable_channels boolean

When true, only return posts from channels in which the actor is allowed to create scheduled posts. When combined with channel_id, every requested channel must allow it, otherwise the request fails. Must not be combined with only_newsfeed.

date_from string

Only return posts whose relevant date is at or after this timestamp (inclusive) — the publication time for published posts, the scheduling time for scheduled posts. Must only be combined with the PUBLISHED and SCHEDULED statuses.

date_to string

Only return posts whose relevant date is at or before this timestamp (inclusive) — the publication time for published posts, the scheduling time for scheduled posts. Must only be combined with the PUBLISHED and SCHEDULED statuses, and must not be before date_from.

sort string[]
page_cursor string

A cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

embed string[]
target_language string

The language to return the post content in.

Post content:

  • *: content contains all content variants of the post, regardless of Accept-Language.
  • Omitted: content contains all manual translations of the post.
  • Matches the language of a manual translation: content contains only that translation (auto_translated: false).
  • No matching manual translation, but the language is supported for automatic translation: content contains a single automatically translated entry (auto_translated: true).
  • No matching manual translation and the language is not supported for automatic translation: content contains a single entry in the post's primary language.

Surveys: surveys always contains all surveys associated with the post. For each survey, the question and the choices.titles are returned:

  • In the requested language, if a matching manual translation exists (auto_translated: false).
  • Automatically translated, if no matching manual translation exists and the language is supported for automatic translation (auto_translated: true).
  • Otherwise, in the survey's primary language.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Create a Post

Requires authentication via bearer.

Create a new post in one or more channels.

Request Body

channel_ids string[]
external_id string

An arbitrary string referencing an external entity identifier.

author_id string

The user id of the author (default: current actor). If a user other than the current actor is specified, the current actor requires post-on-behalf permission. The author is kept only in channels they are a member of; otherwise that channel's post is authored by the current actor.

content object[]
settings object
send_push_notifications boolean

Whether the members of the channels are notified about the new post on their devices. When false, no push notifications are sent for the post or for the users mentioned in it. The author is still subscribed to the post and is notified about later comments and reactions.

The value is kept with the post, so a scheduled post or a post waiting for approval also stays silent when it is published later. It can be changed by updating the post.

send_realtime_updates boolean

Whether connected clients are informed about the new post in realtime. When false, the post only shows up in the feeds of connected clients on their next refresh. Useful for bulk imports of many posts.

The value is kept with the post, so a scheduled post or a post waiting for approval also dispatches no event when it is published later. It can be changed by updating the post.

status stringrequired

Requested status for a post when creating it. The server may automatically downgrade a PUBLISHED request into the APPROVAL when the target channel requires post approval and the actor lacks the approval permission.

scheduled_at string

The point in time when the post should be published. Required when status=SCHEDULED and must be omitted (or null) for any other status.

published_at string

The point in time the post should be marked as published at. Only allowed when status=PUBLISHED and must be in the past. Use this to backdate a post, for example when importing content that was originally published elsewhere. When omitted, the current time is used.

highlighted_until string

The point in time up to which the post should be highlighted.

livestream_id string

The unique identifier of an associated livestream.

mentioned_user_ids string[]
survey_ids string[]
header_attachments string[]

The unique identifier of the file to attach.

The file must be created and uploaded via the Files API and have status FINISHED before it can be attached.

standard_attachments string[]

The unique identifier of the file to attach.

The file must be created and uploaded via the Files API and have status FINISHED before it can be attached.

Response Body

201 Created

Error Codes

  • CHANNEL_NOT_FOUND
  • CHANNEL_ACCESS_DENIED
  • INVALID_SCHEDULED_AT
  • SCHEDULED_AT_REQUIRED
  • SCHEDULED_AT_NOT_ALLOWED
  • INVALID_PUBLISHED_AT
  • PUBLISHED_AT_NOT_ALLOWED
  • INVALID_HIGHLIGHTED_UNTIL
  • ATTACHMENT_NOT_FOUND
  • ATTACHMENT_LIMIT_EXCEEDED
  • LIVESTREAM_NOT_FOUND
  • LIVESTREAM_NOT_SUPPORTED_WITH_MULTIPLE_CHANNELS
  • INVALID_CONTENT
  • EXTERNAL_ID_ALREADY_EXISTS
  • INVALID_SURVEY_ID
  • POST_ON_BEHALF_NOT_ALLOWED

Get posts bookmarked by the actor

Requires authentication via bearer.

Get a list of posts that are bookmarked by the actor. Other filters can be used to narrow down the result set.

Query Params

channel_id string

Filter by channel ID.

sort string[]
page_cursor string

A cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

search_term string

To perform searches, provide a string value. The value should consist of one or more tokens, separated by white spaces or the | character. Each token represents a search criterion that must match case-insensitively in at least one searchable field. If multiple tokens are included, they are combined using the logical OR operator. This means that the results will include items where at least one of the tokens matches in any of the searchable fields.

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

target_language string

The language to return the post content in.

Post content:

  • *: content contains all content variants of the post, regardless of Accept-Language.
  • Omitted: content contains all manual translations of the post.
  • Matches the language of a manual translation: content contains only that translation (auto_translated: false).
  • No matching manual translation, but the language is supported for automatic translation: content contains a single automatically translated entry (auto_translated: true).
  • No matching manual translation and the language is not supported for automatic translation: content contains a single entry in the post's primary language.

Surveys: surveys always contains all surveys associated with the post. For each survey, the question and the choices.titles are returned:

  • In the requested language, if a matching manual translation exists (auto_translated: false).
  • Automatically translated, if no matching manual translation exists and the language is supported for automatic translation (auto_translated: true).
  • Otherwise, in the survey's primary language.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Bookmark a Post

Requires authentication via bearer.

Bookmark a post as the current user. Only published posts that the current user is allowed to see can be bookmarked. Bookmarking a post that is already bookmarked has no effect.

Request Body

post_id stringrequired

The ID of the post to bookmark.

Response Body

201 Created

Error Codes

  • POST_NOT_FOUND
  • POST_ACCESS_DENIED
  • POST_NOT_PUBLISHED
  • BOOKMARK_NOT_FOUND

Get posts bookmark count for the actor

Requires authentication via bearer.

Get the count for all bookmarks for the actor

Response Body

200 OK

Check whether the actor has any bookmarked posts

Requires authentication via bearer.

Returns whether the actor has at least one bookmarked post. Intended as a cheap existence check to gate UI affordances without fetching the bookmarks list or per-channel counts.

Query Params

channelId string

Response Body

200 OK

Remove a Post Bookmark

Requires authentication via bearer.

Remove the current user's bookmark from a post.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Response Body

204 No Content

Error Codes

  • POST_NOT_FOUND
  • POST_ACCESS_DENIED
  • POST_NOT_PUBLISHED
  • BOOKMARK_NOT_FOUND

Get Posts to Approve

Requires authentication via bearer.

Get a paginated collection of posts waiting for approval in channels where the actor is allowed to approve posts. The result can be ordered via sort and enriched via embed in the same way as the posts collection endpoint.

Query Params

sort string[]
page_cursor string

A cursor pointing to the first item to be contained in the response array. Refer to our general "pagination" concept for more information.

page_limit integer

The maximum number of items to be contained in the response array. Refer to our general "pagination" concept for more information.

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

embed string[]
target_language string

The language to return the post content in.

Post content:

  • *: content contains all content variants of the post, regardless of Accept-Language.
  • Omitted: content contains all manual translations of the post.
  • Matches the language of a manual translation: content contains only that translation (auto_translated: false).
  • No matching manual translation, but the language is supported for automatic translation: content contains a single automatically translated entry (auto_translated: true).
  • No matching manual translation and the language is not supported for automatic translation: content contains a single entry in the post's primary language.

Surveys: surveys always contains all surveys associated with the post. For each survey, the question and the choices.titles are returned:

  • In the requested language, if a matching manual translation exists (auto_translated: false).
  • Automatically translated, if no matching manual translation exists and the language is supported for automatic translation (auto_translated: true).
  • Otherwise, in the survey's primary language.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Get a Post

Requires authentication via bearer.

Get a post by its primary identifier.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Query Params

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

embed string[]
target_language string

The language to return the post content in.

Post content:

  • *: content contains all content variants of the post, regardless of Accept-Language.
  • Omitted: content contains all manual translations of the post.
  • Matches the language of a manual translation: content contains only that translation (auto_translated: false).
  • No matching manual translation, but the language is supported for automatic translation: content contains a single automatically translated entry (auto_translated: true).
  • No matching manual translation and the language is not supported for automatic translation: content contains a single entry in the post's primary language.

Surveys: surveys always contains all surveys associated with the post. For each survey, the question and the choices.titles are returned:

  • In the requested language, if a matching manual translation exists (auto_translated: false).
  • Automatically translated, if no matching manual translation exists and the language is supported for automatic translation (auto_translated: true).
  • Otherwise, in the survey's primary language.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Response Body

200 OK

Error Codes

  • POST_ACCESS_DENIED

Update a Post

Requires authentication via bearer.

Update an existing post by its primary identifier.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Query Params

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

embed string[]
target_language string

The language to return the post content in.

Post content:

  • *: content contains all content variants of the post, regardless of Accept-Language.
  • Omitted: content contains all manual translations of the post.
  • Matches the language of a manual translation: content contains only that translation (auto_translated: false).
  • No matching manual translation, but the language is supported for automatic translation: content contains a single automatically translated entry (auto_translated: true).
  • No matching manual translation and the language is not supported for automatic translation: content contains a single entry in the post's primary language.

Surveys: surveys always contains all surveys associated with the post. For each survey, the question and the choices.titles are returned:

  • In the requested language, if a matching manual translation exists (auto_translated: false).
  • Automatically translated, if no matching manual translation exists and the language is supported for automatic translation (auto_translated: true).
  • Otherwise, in the survey's primary language.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

external_id string

An arbitrary string referencing an external entity identifier.

author_id string

The user id of the author. If a user other than the current actor is specified, the current actor requires post-on-behalf permission.

status string

Requested status for a post when updating it. The server may automatically downgrade a PUBLISHED request into the APPROVAL when the target channel requires post approval and the actor lacks the approval permission.

PUBLISHED on a post waiting for approval approves the post. This requires the approval permission in the channel and must not be combined with any other change.

REJECTED rejects a post waiting for approval and is only valid for such posts. This requires the approval permission in the channel and must not be combined with any other change.

Publishing or scheduling a rejected post also requires the approval permission.

Once archived, a post is visible only to actors allowed to view archived posts; for all other actors — including the one who archived it — further requests return not found, so a 404 on an archive retry means the post is already archived. For actors who can view archived posts, requesting ARCHIVED again has no effect and any other status change is rejected with a conflict.

content object[]
settings object
send_push_notifications boolean

Changes whether push notifications are sent for the post. Omit it to keep the current value.

Effect by status of the post:

  • Scheduled or waiting for approval, once the post gets published:
    • true: the channel members and the mentioned users are notified.
    • false: nobody is notified.
  • Published:
    • true: users mentioned by this or later updates are notified.
    • false: users mentioned by this or later updates are not notified.
    • Users mentioned before this update are never notified afterwards.

Cannot be combined with approving a post.

send_realtime_updates boolean

Changes whether connected clients are informed in realtime when the post gets published. Omit it to keep the current value.

Effect by status of the post:

  • Scheduled or waiting for approval, once the post gets published:
    • true: the post shows up in the feeds of connected clients right away.
    • false: the post shows up in the feeds of connected clients on their next refresh.
  • Published: no effect.

This update itself is always sent to connected clients in realtime. Cannot be combined with approving a post.

scheduled_at string

The point in time when the post should be published. Required when status=SCHEDULED and must be omitted (or null) for any other status.

highlighted_until string

The point in time up to which the post should be highlighted.

livestream_id string

The unique identifier of an associated livestream.

mentioned_user_ids string[]
survey_ids string[]
header_attachments string[]

The unique identifier of the file to attach.

The file must be created and uploaded via the Files API and have status FINISHED before it can be attached.

standard_attachments string[]

The unique identifier of the file to attach.

The file must be created and uploaded via the Files API and have status FINISHED before it can be attached.

Response Body

200 OK

Error Codes

  • POST_NOT_FOUND
  • POST_ACCESS_DENIED
  • INVALID_STATUS_TRANSITION
  • INVALID_SCHEDULED_AT
  • SCHEDULED_AT_REQUIRED
  • ATTACHMENT_NOT_FOUND
  • ATTACHMENT_LIMIT_EXCEEDED
  • LIVESTREAM_NOT_FOUND
  • INVALID_CONTENT
  • EXTERNAL_ID_ALREADY_EXISTS
  • INVALID_SURVEY_ID
  • POST_ON_BEHALF_NOT_ALLOWED
  • ARCHIVE_WITH_OTHER_CHANGES_NOT_ALLOWED
  • APPROVE_WITH_OTHER_CHANGES_NOT_ALLOWED
  • REJECT_WITH_OTHER_CHANGES_NOT_ALLOWED

Move a Post

Requires authentication via bearer.

Move an existing post into another channel. The post is recreated in the target channel under a new identifier and the original post is deleted — the response contains the new post. Interactions are not transferred: the moved post starts without comments, reactions or notification subscriptions, and its surveys are recreated with all votes reset. Bookmarks of users who are members of the target channel follow the post to its new identifier; all other bookmarks are removed.

Further move semantics:

  • Mentions of users who are not members of the target channel are unlinked: the mention is replaced with the user's plain name and they are dropped from the post's mentions.
  • A highlight is removed.
  • A scheduled post stays scheduled when the actor may create scheduled posts in the target channel. Otherwise its schedule is removed and it enters the target channel like a published post, as described below; a move is never refused because the actor may not schedule there.
  • A published post or one waiting for approval enters the target channel's approval flow only when that channel requires approval and the actor lacks the approval permission there; in every other case it is published. The state the post had in the source channel does not carry over.
  • Moving another user's post keeps them as the author when they are a member of the target channel and the actor may post on their behalf there, which needs the post-on-behalf permission and a ghostwriter assignment. In every other case the actor becomes the author of the moved post; a move is never refused over the author.
  • The post keeps its comment and reaction settings, except that a setting enabled against the target channel's default falls back to that default when the actor lacks the permission to enable it there; a move is never refused over these settings. Disabled settings are always kept, also when the target channel enables them.
  • Members of the target channel are notified as for a newly created post, unless send_push_notifications is false.

Moving requires the permission to edit the post in its current channel and to create posts in the target channel. Posts with an associated livestream and posts in the DRAFT, REJECTED or ARCHIVED status cannot be moved.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Query Params

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

embed string[]
target_language string

The language to return the post content in.

Post content:

  • *: content contains all content variants of the post, regardless of Accept-Language.
  • Omitted: content contains all manual translations of the post.
  • Matches the language of a manual translation: content contains only that translation (auto_translated: false).
  • No matching manual translation, but the language is supported for automatic translation: content contains a single automatically translated entry (auto_translated: true).
  • No matching manual translation and the language is not supported for automatic translation: content contains a single entry in the post's primary language.

Surveys: surveys always contains all surveys associated with the post. For each survey, the question and the choices.titles are returned:

  • In the requested language, if a matching manual translation exists (auto_translated: false).
  • Automatically translated, if no matching manual translation exists and the language is supported for automatic translation (auto_translated: true).
  • Otherwise, in the survey's primary language.

Headers

Accept-Language string

The preferred language used when returning localized strings.

Request Body

channel_id stringrequired

The unique identifier of the channel to move the post to.

send_push_notifications boolean

Whether the members of the target channel are notified about the moved post on their devices, as for a newly created post. Has the same effect as send_push_notifications when creating a post.

send_realtime_updates boolean

Whether connected clients are informed in realtime about the post appearing in the target channel. Has the same effect as send_realtime_updates when creating a post. The removal of the original post from its channel is always dispatched in realtime.

Response Body

200 OK

Error Codes

  • POST_NOT_FOUND
  • POST_ACCESS_DENIED
  • CHANNEL_NOT_FOUND
  • CHANNEL_ACCESS_DENIED
  • POST_ALREADY_IN_CHANNEL
  • INVALID_POST_STATUS
  • LIVESTREAM_POST_NOT_SUPPORTED

Report a Post

Requires authentication via bearer.

Report a post.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Response Body

201 Created

Error Codes

  • POST_REPORT_ALREADY_EXISTS

Get a Post Auto-Translation

Requires authentication via bearer.

Get the automatic translation of a post for the requested target language.

The post property is only present when status is TRANSLATED. It contains the post with a single content entry in the requested language, analogous to getting the post with target_language. If no automatic translation was triggered for the target language before, status is NOT_REQUESTED.

A manually authored translation for the target language takes precedence over the automatic one (when the organisation has manual translations configured): it is served as TRANSLATED right away. This includes the post's source content when the target language matches the post's source language.

When the post carries a survey that is translated automatically, the status covers both the post content and the survey: it stays PENDING until both translations have completed and is FAILED when either of them failed.

FAILED is terminal: the automatic translation is not retried until the post content is updated.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Query Params

target_language stringrequired

The language to translate the post content into.

content_format string

Specifies which content format should be returned for FormattedContentOutput properties. If nothing is specified HTML will be used.

embed string[]

Response Body

200 OK

Error Codes

  • TARGET_LANGUAGE_NOT_SUPPORTED

Trigger a Post Auto-Translation

Requires authentication via bearer.

Trigger an automatic translation of the post's content into the requested target language. When the post carries a survey, its question and choice titles are translated as well.

The translation is processed asynchronously. Use the corresponding GET endpoint to poll for the result. Returns an error if the target language is not supported for automatic translation.

When the post already has a manually authored translation for the target language (and the organisation has manual translations configured), no automatic translation is triggered — the GET endpoint serves the manual translation directly.

A translation that previously failed is not retried. It stays FAILED until the post content is updated, which invalidates the stored translation, or until the translation is triggered again with force set to true.

Path Params

post_id stringrequired

The primary identifier of the post to access.

Request Body

target_language stringrequired

A locale representing a language and region.

force boolean

Invalidate the stored automatic translation for the target language and request a new one — for example to retry a translation that previously failed.

Response Body

202 Accepted

Error Codes

  • TARGET_LANGUAGE_NOT_SUPPORTED