Docs: REST API and typed client

REST API and typed client

Every operation is a REST route under https://ballot.jumpstartsolutions.co/api/v1/w/{workspace} (slug or ID). Its OpenAPI operationId is the MCP tool name, so search_posts is the same operation everywhere. The full document is at /api/v1/openapi.json.

Requests

  • Authenticate with an API key: Authorization: Bearer cc_sk_…. Public reads (boards, posts, roadmap, changelog) also work without one. See Authentication.
  • GET takes flat query parameters; other methods take a JSON body.
  • Creates accept an Idempotency-Key header (kept 24 hours per caller).
  • Changes answer with a CareChannel-Audit-Event header: pass it to undo_action to reverse an undoable change (list_audit_events marks them). The typed client hands it, with the operation's name, to onAuditEvent; MCP results carry it as _meta["carechannel/audit_event_id"].
  • Lists are cursor-paginated: limit (default 25, max 100) and next_cursor.
  • Errors are { "error": { "code", "message", "details" } }.

Rate limits

REST and MCP callers are limited per minute, per caller. Over a limit, REST answers 429 with Retry-After and MCP returns a rate_limited tool error that says how long to wait. Dry runs of destructive calls count as destructive calls.

CallerReadsChangesDestructive
Team members and API keys60030060
Customers3003010

Posting also has hourly limits for customers (10 posts and 30 comments per hour).

Typed client

@carechannel/client is generated from the same registry: one method per operation, typed inputs and outputs, and CareChannelApiError with the server's code.

import { createCareChannelClient } from "@carechannel/client";

const careChannel = createCareChannelClient({
  baseUrl: "https://ballot.jumpstartsolutions.co/api/v1",
  workspace: "acme",
  token: process.env.CARECHANNEL_API_KEY,
});

const { items } = await careChannel.search_posts({ board: "feature-requests", sort: "top" });
await careChannel.add_vote_on_behalf({
  post: items[0].id,
  user: { email: "jane@customer.example" },
  priority: "must_have",
});

Operations

core

GET /mewhoamiShow who I am
GET /overviewget_workspace_overviewGet the workspace overview
GET /filter-guideget_filter_guideGet the filter guide
GET /boardslist_boardsList boards
POST /posts/searchsearch_postsSearch posts
POST /posts/countcount_postsCount posts
GET /me/ideaslist_my_activityList my ideas
GET /posts/{post}get_postGet a post
GET /similar-postsfind_similar_postsFind similar posts
POST /postscreate_postCreate a post
PATCH /posts/{post}update_postEdit a post
DELETE /posts/{post}delete_postDelete a post
POST /uploadscreate_uploadStart a file upload
PUT /posts/{post}/votevote_postVote for a post
DELETE /posts/{post}/voteunvote_postRemove your vote
GET /posts/{post}/commentslist_commentsList a post's comments
POST /posts/{post}/commentscreate_commentComment on a post
PATCH /comments/{comment}update_commentEdit a comment
DELETE /comments/{comment}delete_commentDelete a comment
POST /posts/{post}/restorerestore_postRestore a deleted post
GET /notificationslist_notificationsList your notifications
POST /notifications/readmark_notifications_readMark notifications read
GET /notifications/preferencesget_notification_preferencesGet your notification settings
PATCH /notifications/preferencessave_notification_preferencesChange your notification settings
PUT /followsfollowFollow a post, board or category
DELETE /followsunfollowUnfollow a post, board or category
GET /email-preferencesget_email_preferencesGet your email settings
PATCH /email-preferencessave_email_preferencesChange your email settings
GET /roadmapget_public_roadmapGet the public roadmap
GET /changeloglist_changelog_entriesList changelog entries
GET /changelog/{entry}get_changelog_entryGet a changelog entry
PUT /changelog-subscriptionsubscribe_changelogSubscribe to the changelog
DELETE /changelog-subscriptionunsubscribe_changelogUnsubscribe from the changelog
GET /shared/{token}get_shared_roadmapOpen a shared roadmap

triage

GET /posts/{post}/voterslist_votersList a post's voters
POST /posts/{post}/statuschange_post_statusChange a post's status
GET /moderation/queuelist_moderation_queueList posts awaiting review
POST /posts/{post}/moderationmoderate_postApprove or reject a post
PUT /posts/{post}/ownerassign_post_ownerAssign a post's owner
PUT /posts/{post}/etaset_post_etaSet a post's ETA
POST /posts/{post}/tagsadd_post_tagsTag a post
DELETE /posts/{post}/tagsremove_post_tagsUntag a post
POST /posts/{post}/movemove_postMove a post to another board
POST /posts/{source}/mergemerge_postsMerge duplicate posts
DELETE /posts/{post}/mergeunmerge_postUnmerge a post
POST /posts/bulkbulk_update_postsUpdate many posts at once
POST /posts/{post}/votesadd_vote_on_behalfVote for a customer
PATCH /posts/{post}/votes/{user}set_vote_prioritySet a vote's priority or note
DELETE /posts/{post}/votes/{user}remove_voteRemove a customer's vote

customers

POST /users/{user}/blockblock_userBlock an end user
DELETE /users/{user}/blockunblock_userUnblock an end user
GET /userssearch_usersSearch customers
GET /users/{user}get_userGet a customer
POST /userssave_userCreate or update a customer
POST /users/mergemerge_usersMerge duplicate customers
DELETE /users/{user}delete_userDelete a customer and their content
GET /users/{user}/exportexport_user_dataExport a customer's data
GET /companiessearch_companiesSearch companies
GET /companies/{company}get_companyGet a company
POST /companiessave_companyCreate or update a company
PUT /companies/{company}/users/{user}link_user_companyAdd a customer to a company
DELETE /companies/{company}/users/{user}unlink_user_companyRemove a customer from a company
GET /segmentslist_segmentsList segments
POST /segments/previewpreview_segmentPreview who is in a segment
POST /segmentssave_segmentCreate or update a segment
DELETE /segments/{segment}delete_segmentDelete a segment

planning

GET /viewslist_viewsList saved views
GET /views/{view}/rowsrun_viewRun a saved view
POST /viewssave_viewCreate or update a saved view
DELETE /views/{view}delete_viewDelete a saved view
POST /exportsexport_dataExport a CSV
GET /exports/{export}get_exportCheck an export
GET /roadmapslist_roadmapsList roadmaps
POST /roadmaps/{roadmap}/queryget_roadmapGet a roadmap
POST /roadmapssave_roadmapCreate or update a roadmap
DELETE /roadmaps/{roadmap}delete_roadmapDelete a roadmap
POST /roadmaps/{roadmap}/postsadd_to_roadmapAdd posts to a roadmap
POST /roadmaps/{roadmap}/posts/removeremove_from_roadmapRemove posts from a roadmap
POST /roadmaps/{roadmap}/scoringconfigure_scoringConfigure roadmap scoring
POST /roadmaps/{roadmap}/valuesset_factor_valuesSet manual factor values
POST /roadmaps/{roadmap}/rankrank_roadmap_postRank a post on a roadmap
GET /reports/{type}get_reportGet a report
POST /share-linkscreate_share_linkShare a roadmap view
GET /share-linkslist_share_linksList share links
DELETE /share-links/{link}revoke_share_linkRevoke a share link

changelog

PUT /changelogsave_changelog_entrySave a changelog entry
POST /changelog/{entry}/publishpublish_changelog_entryPublish a changelog entry
POST /changelog/{entry}/unpublishunpublish_changelog_entryUnpublish a changelog entry
DELETE /changelog/{entry}delete_changelog_entryDelete a changelog entry
GET /changelog-labelslist_changelog_labelsList changelog labels
PUT /changelog-labelssave_changelog_labelSave a changelog label
DELETE /changelog-labels/{label}delete_changelog_labelDelete a changelog label
GET /changelog-subscriberslist_changelog_subscribersList changelog subscribers

admin

GET /memberslist_membersList members
POST /members/invitationsinvite_memberInvite a member
POST /members/invitations/{invitation}/resendresend_invitationResend an invitation
DELETE /members/invitations/{invitation}revoke_invitationRevoke an invitation
PATCH /members/{member}update_member_roleChange a member's role
DELETE /members/{member}remove_memberRemove a member
POST /boardssave_boardSave a board
DELETE /boards/{board}delete_boardDelete a board
POST /categoriessave_categorySave a category
DELETE /categories/{category}delete_categoryDelete a category
POST /statusessave_statusSave a status
PUT /statuses/orderreorder_statusesReorder statuses
DELETE /statuses/{status}delete_statusDelete a status
POST /tagssave_tagSave a tag
DELETE /tags/{tag}delete_tagDelete a tag
GET /custom-fieldslist_custom_fieldsList custom fields
POST /custom-fieldssave_custom_fieldCreate or update a custom field
DELETE /custom-fields/{field}delete_custom_fieldDelete a custom field
GET /settingsget_workspace_settingsGet workspace settings
PATCH /settingsupdate_workspace_settingsUpdate workspace settings
POST /settings/domain/checkcheck_custom_domainCheck the custom domain
GET /setupget_setup_checklistGet the setup checklist
PATCH /setupupdate_setup_checklistUpdate the setup checklist

audit

GET /audit-eventslist_audit_eventsList audit events
GET /usageget_usageGet usage and performance
POST /audit-events/{event}/undoundo_actionUndo an action