Create a post. Creates a feedback post on a board, with the workspace's default status. Call find_similar_posts first and prefer voting on a match. Body is Markdown. End users post as themselves on public boards with posting on; members may post anywhere, and with on_behalf_of record a customer's request (creating the customer if needed; blocked customers are refused). Pass idempotency_key so a retry doesn't post twice. Customers who follow the board or category are emailed once the post is approved (never for private boards); team members who follow the board are notified. A post held for review emails its author when the team approves it.
Toolset
core
Who can call it
OwnersManagersContributorsCustomersAPI keys
REST
POST /api/v1/w/{workspace}/posts
Behavior
changes dataaccepts idempotency_key
Input
Field
Type
Description
boardrequired
string
Board slug, name or ID.
category
string
A category on that board.
titlerequired
string
body
string
Markdown. Raw HTML is shown as text, not rendered. Default: "".
on_behalf_of
object
Team and service accounts only: the end user this post is from. Found by user_id, external_id or email, and created if missing.
attachment_ids
array of string
Uploads from create_upload whose files you've PUT, in display order (at most 10).
fields
object
Custom field values by key (list_custom_fields). Customers can set only the fields on the board's form; null clears a value.
idempotency_key
string
Retry-safe key. Repeating a call with the same key returns the first result.
Output
Field
Type
Description
idrequired
string
ID with prefix "pst_"
workspace_idrequired
string
ID with prefix "ws_"
slugrequired
string
titlerequired
string
boardrequired
object
categoryrequired
object or null
statusrequired
object
authorrequired
object
moderation_staterequired
one of: approved, pending, rejected, spam
Only approved posts are shown to end users other than the author.
ownerrequired
object or null
The responsible team member; null when unassigned, and always for end users.
etarequired
object or null
tagsrequired
array of object or null
Internal tags; null for end users, who never see tags.
merged_intorequired
object or null
Set when merged into another post: this one is read-only and redirects there.
vote_countrequired
integer
comment_countrequired
integer
Public comments and replies.
voted_by_yourequired
boolean or null
Whether you have voted on it; null unless you're an end user.
shipped_inrequired
object or null
The published changelog entry that announced it, if any.
followed_by_yourequired
boolean or null
Whether you follow it (follow / unfollow); null for API keys and visitors.
emailable_followersrequired
integer or null
How many customers a status change with notify emails: followers who can be emailed and keep post updates on. Team only (null for customers and visitors).
status_changed_atrequired
string (date-time)
last_activity_atrequired
string (date-time)
versionrequired
integer
created_atrequired
string (date-time)
updated_atrequired
string (date-time)
portal_urlrequired
string (uri)
admin_urlrequired
string (uri) or null
Admin inbox link; null for end users.
bodyrequired
string
Markdown, as written.
attachmentsrequired
array of object
In the order they were attached.
created_by_member_idrequired
string or null
The member who posted on the author's behalf; null otherwise or for end users.
fieldsrequired
object
Custom field values by key; customers see public fields only.
roadmapsrequired
array of object or null
Internal roadmaps it's on (team only; null for customers).
mrr_at_stakerequired
number or null
Summed MRR of the distinct companies of its voters (team only).