Docs/Reference
API reference
A REST API over JSON for posts, comments, boards, statuses, members, user segments and webhooks. One key, one workspace.
Base URL
https://api.heedpost.com/v1/
One key, one workspace. The key names the workspace, so every request goes to the same host and there is no subdomain to configure.
Authentication
Send your key as a bearer token. Keys are made by an admin on Settings · API, webhooks and MCP in your workspace, and the secret is shown once.
curl https://api.heedpost.com/v1/posts \ -H "Authorization: Bearer hp_live_..."
A key acts as the person who made it. It can do what that admin can do, and anything it writes appears under their name. It stops working the day they leave the workspace or stop being an admin. There are no separate permissions to set up, and a revoked key stops working on its very next request.
Keys can't create other keys. When you revoke a key, nothing it made can keep working in its place.
Three kinds of key
You choose a key's kind when you make it, and it stays that way. The kind can only narrow what the key does below what its person can do, so it's a way to hand out less access, not more.
Read-onlyEvery GET on this API, and nothing else. No exceptions: since no read answers with a credential, there is nothing for one to carve out.
Read and writeEverything on this page. This is what a key was before kinds existed.
MCPThe MCP endpoint, and nothing on this REST API.
A key used in the wrong place gets a 403, not a 401. The key itself is fine and belongs to your workspace. It's being used somewhere its kind doesn't reach, and the error names the kind of key to make instead.
Errors
Every failure is JSON with a detail that is a sentence, not a code. The status is the useful part:
400The body is not JSON this API can read.
401The key is missing, malformed, revoked, or its person has left.
402Your plan does not reach this. The sentence names the tier that does.
403You are authenticated but not allowed to do this.
404No such thing, or nothing you can see.
409The workspace is in a state where this cannot be done. Usually fixable.
422The request is the wrong shape, or names something that does not exist.
429Too many requests. Slow down.
A filter with a typo is an error, not an empty list. An unknown status name returns a 404 and an unknown stage a 422, because to a sync job an empty list and a typo look the same.
Rate limits
Limits are counted per hour for the person your key acts as, not for the key or the address it calls from. Two keys made by one admin share one allowance, and a key made by someone else has its own. Calling from a new address doesn't add allowance, and sharing an address with another customer doesn't use up theirs.
1,000 requestsEverything on this API, reads included, and one MCP message counts as one request.
10 postsShared with the composer in the browser: a post is a post whoever filed it.
100 commentsThe same bucket the browser spends.
120 votesAdding only. Changing your mind costs nothing.
50 invitationsThis API only. A browser sends one at a time and a script sends a list, and what a spray of these spends is the sending reputation every workspace shares.
120 status movesThis limit applies to the API only. It's there to limit email: a move to a new stage emails every follower of that post.
Going over a limit returns a 429 with Retry-After in seconds. Wait that long instead of guessing. The window is fixed, so the header tells you exactly when it resets.
Pagination
List endpoints take limit and offset and answer with a page object carrying the total. The total is the number of matches, not the number on this page.
{ "items": [ ... ], "page": { "total": 148, "limit": 25, "offset": 0 } }Events and agents
Instead of polling, let webhooks tell you when something changes: 110 event types, signed and retried. An AI agent can use the same operations through the MCP server, where each one below is a tool.
Endpoints
27 operations. Their parameters, bodies and answers come from the API's own OpenAPI document, so they always match the API. Open one to see its parameters, body and a request you can paste.
posts
Posts are the requests people file on your boards. Comments, votes and statuses all belong to a post.
get/v1/postsList posts
Posts on this workspace's boards, newest first unless you choose another sort. Filter by board, status, kind or free text. Each item has every field of a post except body_html and demand.trend, which are left out to keep long lists small. Fetch a single post to get those two as well.
Parameters
boardstring | nullstring | null, in the query
statusstring | nullstring | null, in the query
kindstring | nullstring | null, in the query
qstring | nullstring | null, in the query
roadmapdefault falseboolean, in the query
user_segmentstring | nullstring | null, in the query
user_segment_labelstring | nullstring | null, in the query
value_mininteger | nullinteger | null, in the query
sortstring | nullstring | null, in the query
limitdefault 25integer, in the query
offsetdefault 0integer, in the query
Answers
200401403404422429
curl -X GET https://api.heedpost.com/v1/posts \ -H "Authorization: Bearer hp_live_..."
post/v1/postsCreate a post
File a post, as the person the key belongs to.
Body · PostIn
boardrequiredstring
titlerequiredstring
bodystringstring
is_privatebooleanboolean
tagsstring[]string[]
field_valuesobjectobject
Answers
200400401402403404409422429
curl -X POST https://api.heedpost.com/v1/posts \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"board": "…", "title": "…"}'get/v1/posts/{post_id}Get a post
One post in full, with its board, status, author, tags and demand.
Parameters
post_idrequiredstring, uuid, in the path
Answers
200401403404422429
curl -X GET https://api.heedpost.com/v1/posts/{post_id} \
-H "Authorization: Bearer hp_live_..."post/v1/posts/{post_id}/statusMove a post
Give a post one of the workspace's statuses, by name. Only admins can do this. A move to a new stage emails everyone who follows the post.
Parameters
post_idrequiredstring, uuid, in the path
Body · StatusIn
statusrequiredstring
reasonstringstring
Answers
200400401403404422429
curl -X POST https://api.heedpost.com/v1/posts/{post_id}/status \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"status": "…"}'post/v1/posts/{post_id}/voteVote on a post
Safe to repeat: voting twice still counts as one vote and sends one event.
Parameters
post_idrequiredstring, uuid, in the path
Answers
200401403404422429
curl -X POST https://api.heedpost.com/v1/posts/{post_id}/vote \
-H "Authorization: Bearer hp_live_..."delete/v1/posts/{post_id}/voteRemove a vote from a post
Take a vote back. It's safe to repeat. The person still follows the post, because following is separate, and they can stop following it on its own.
Parameters
post_idrequiredstring, uuid, in the path
Answers
200401403404422429
curl -X DELETE https://api.heedpost.com/v1/posts/{post_id}/vote \
-H "Authorization: Bearer hp_live_..."comments
The conversation under a post. When an admin moves a post and gives a reason, the reason appears here as a comment.
get/v1/posts/{post_id}/commentsList comments
Oldest first, in one flat list. A comment written while you page through is added at the end, so the pages you haven't read yet don't shift. On a reply, parent_id names the comment it answers.
Parameters
post_idrequiredstring, uuid, in the path
limitdefault 25integer, in the query
offsetdefault 0integer, in the query
Answers
200401403404422429
curl -X GET https://api.heedpost.com/v1/posts/{post_id}/comments \
-H "Authorization: Bearer hp_live_..."post/v1/posts/{post_id}/commentsAdd a comment
Reply on a post, as the person the key belongs to.
Parameters
post_idrequiredstring, uuid, in the path
Body · CommentIn
bodyrequiredstring
is_internalbooleanboolean
Answers
200400401403404409422429
curl -X POST https://api.heedpost.com/v1/posts/{post_id}/comments \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"body": "…"}'post/v1/posts/{post_id}/comments/{comment_id}/voteVote on a comment
Add a vote to a comment, as the person the key belongs to. Voting twice still counts as one vote.
Parameters
post_idrequiredstring, uuid, in the path
comment_idrequiredstring, uuid, in the path
Answers
200401403404422429
curl -X POST https://api.heedpost.com/v1/posts/{post_id}/comments/{comment_id}/vote \
-H "Authorization: Bearer hp_live_..."delete/v1/posts/{post_id}/comments/{comment_id}/voteRemove a vote from a comment
Take a comment vote back. It's safe to repeat. Voting on a comment doesn't follow anything, so there's nothing to unfollow.
Parameters
post_idrequiredstring, uuid, in the path
comment_idrequiredstring, uuid, in the path
Answers
200401403404422429
curl -X DELETE https://api.heedpost.com/v1/posts/{post_id}/comments/{comment_id}/vote \
-H "Authorization: Bearer hp_live_..."boards
Boards hold posts. Most workspaces have two or three, and each one is addressed by its slug.
get/v1/boardsList boards
Every board this key can see, in the workspace's own order.
Answers
200401403429
curl -X GET https://api.heedpost.com/v1/boards \ -H "Authorization: Bearer hp_live_..."
post/v1/boardsCreate a board
Make a board. The slug is its address, and every link to the board is built from it. Choose it here, and change it later with its own endpoint.
Body · BoardIn
slugrequiredstring
namerequiredstring
descriptionstringstring
visibility"public" | "private""public" | "private"
Answers
200400401402403409422429
curl -X POST https://api.heedpost.com/v1/boards \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"slug": "…", "name": "…"}'patch/v1/boards/{slug}Edit a board
Change a board's name, description, visibility and switches. Its address has an endpoint of its own.
Parameters
slugrequiredstring, in the path
Body · BoardPatch
namerequiredstring
descriptionstringstring
visibility"public" | "private""public" | "private"
accepts_postsbooleanboolean
on_roadmapbooleanboolean
closed_notestringstring
Answers
200400401402403404422429
curl -X PATCH https://api.heedpost.com/v1/boards/{slug} \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"name": "…"}'delete/v1/boards/{slug}Delete a board
Deleting a board hides it and its posts. Nothing is destroyed, and you can bring it back from Settings, under Deleted.
Parameters
slugrequiredstring, in the path
Answers
200401403404422429
curl -X DELETE https://api.heedpost.com/v1/boards/{slug} \
-H "Authorization: Bearer hp_live_..."put/v1/boards/{slug}/addressChange a board address
Give a board a new address. Every address it has had keeps working, so a link someone sent last year still opens the board.
Parameters
slugrequiredstring, in the path
Body · BoardAddressIn
addressrequiredstring
Answers
200400401403404409422429
curl -X PUT https://api.heedpost.com/v1/boards/{slug}/address \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"address": "…"}'vocabulary
Statuses and tags, in your workspace's own words. Each status has a name you chose and a stage we define, called its kind. Filter with ?status= for a name or ?kind= for a stage, and a wrong value in either returns an error, not an empty list. Tags are matched by name, and a tag that doesn't exist isn't created for you.
get/v1/statusesList statuses
Every current status, and the stage each belongs to. Read this first, so your client only sends ?status= names that exist.
Answers
200401403429
curl -X GET https://api.heedpost.com/v1/statuses \ -H "Authorization: Bearer hp_live_..."
get/v1/tagsList tags
Every current tag in the workspace, in alphabetical order.
Answers
200401403429
curl -X GET https://api.heedpost.com/v1/tags \ -H "Authorization: Bearer hp_live_..."
members
Everyone who has ever taken part in the workspace, which is mostly customers, not your team. Ask for ?role=admin,member to get just the team.
get/v1/membersList members
Everyone in this workspace, newest first.
Parameters
rolestring | nullstring | null, in the query
qstring | nullstring | null, in the query
limitdefault 25integer, in the query
offsetdefault 0integer, in the query
Answers
200401403422429
curl -X GET https://api.heedpost.com/v1/members \ -H "Authorization: Bearer hp_live_..."
post/v1/membersInvite a member
Invite someone by email. The answer is the pending invitation, without its link, which goes only to their inbox.
Body · MemberIn
emailrequiredstring, email
role"admin" | "member""admin" | "member"
Answers
200400401403422429
curl -X POST https://api.heedpost.com/v1/members \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"email": "…"}'patch/v1/members/{user_id}Promote or demote a member
Make someone an admin, or make an admin a member again. The last admin can't step down, and gets a 409. Promote someone else first.
Parameters
user_idrequiredstring, uuid, in the path
Body · RoleIn
rolerequired"admin" | "member"
Answers
200400401403404409422429
curl -X PATCH https://api.heedpost.com/v1/members/{user_id} \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"role": "admin"}'delete/v1/members/{user_id}Remove a member
Take someone off this workspace. Their posts, votes and comments stay, because those belong to them, not to their place on the team.
Parameters
user_idrequiredstring, uuid, in the path
Answers
204401403404409422429503
curl -X DELETE https://api.heedpost.com/v1/members/{user_id} \
-H "Authorization: Bearer hp_live_..."user segments
Who your customers are, and what each is worth to you. A segment is whatever unit you're paid by: a company with twelve people in it, or one subscriber or donor. Voters belong to segments, so a post shows how many separate segments asked for it and the weight behind them, not only a vote count. Every value is in minor units, like cents. These need a key that belongs to someone on your team. For any other key, demand on a post is null. You told us this about your customers, and it's never shown to anyone else.
get/v1/user-segmentsList user segments
Every user segment, largest first. Team keys only.
Parameters
qstring | nullstring | null, in the query
labelstring | nullstring | null, in the query
limitdefault 25integer, in the query
offsetdefault 0integer, in the query
Answers
200401402403422429
curl -X GET https://api.heedpost.com/v1/user-segments \ -H "Authorization: Bearer hp_live_..."
webhooks
The addresses we send events to. You see an endpoint's signing secret once, when you add it or rotate it, so keep it somewhere safe. An empty event list means every type except the high-volume ones, which you have to name. Nothing about a user segment is ever sent here.
get/v1/webhooksList webhooks
Every endpoint this workspace sends events to, and how its recent deliveries went.
Answers
200401403429
curl -X GET https://api.heedpost.com/v1/webhooks \ -H "Authorization: Bearer hp_live_..."
post/v1/webhooksAdd a webhook
Add an endpoint. The events you choose are sent to its URL, signed with a secret. The secret is in this answer only, and no later request shows it again.
Body · WebhookIn
urlrequiredstring
event_typesstring[]string[]
is_activebooleanboolean
Answers
200400401402403422429
curl -X POST https://api.heedpost.com/v1/webhooks \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"url": "…"}'put/v1/webhooks/{endpoint_id}Edit a webhook
Change an endpoint's URL or the events it wants. Send the whole set each time: a field you leave out is cleared, not kept.
Parameters
endpoint_idrequiredstring, uuid, in the path
Body · WebhookIn
urlrequiredstring
event_typesstring[]string[]
is_activebooleanboolean
Answers
200400401403404422429
curl -X PUT https://api.heedpost.com/v1/webhooks/{endpoint_id} \
-H "Authorization: Bearer hp_live_..." \
-H "Content-Type: application/json" \
-d '{"url": "…"}'delete/v1/webhooks/{endpoint_id}Remove a webhook
Unlike everything else on this API, removing an endpoint is permanent. It holds a signing secret, and a removed secret shouldn't stay stored. Its delivery log goes with it.
Parameters
endpoint_idrequiredstring, uuid, in the path
Answers
204401403404422429
curl -X DELETE https://api.heedpost.com/v1/webhooks/{endpoint_id} \
-H "Authorization: Bearer hp_live_..."post/v1/webhooks/{endpoint_id}/rotateRotate a webhook secret
Get a new signing secret. It's shown in this answer only, and the old one stops working at once.
Parameters
endpoint_idrequiredstring, uuid, in the path
Answers
200401403404422429
curl -X POST https://api.heedpost.com/v1/webhooks/{endpoint_id}/rotate \
-H "Authorization: Bearer hp_live_..."