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-Keyheader (kept 24 hours per caller). - Changes answer with a
CareChannel-Audit-Eventheader: pass it toundo_actionto reverse an undoable change (list_audit_eventsmarks them). The typed client hands it, with the operation's name, toonAuditEvent; MCP results carry it as_meta["carechannel/audit_event_id"]. - Lists are cursor-paginated:
limit(default 25, max 100) andnext_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.
| Caller | Reads | Changes | Destructive |
|---|---|---|---|
| Team members and API keys | 600 | 300 | 60 |
| Customers | 300 | 30 | 10 |
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 /me | whoami | Show who I am |
GET /overview | get_workspace_overview | Get the workspace overview |
GET /filter-guide | get_filter_guide | Get the filter guide |
GET /boards | list_boards | List boards |
POST /posts/search | search_posts | Search posts |
POST /posts/count | count_posts | Count posts |
GET /me/ideas | list_my_activity | List my ideas |
GET /posts/{post} | get_post | Get a post |
GET /similar-posts | find_similar_posts | Find similar posts |
POST /posts | create_post | Create a post |
PATCH /posts/{post} | update_post | Edit a post |
DELETE /posts/{post} | delete_post | Delete a post |
POST /uploads | create_upload | Start a file upload |
PUT /posts/{post}/vote | vote_post | Vote for a post |
DELETE /posts/{post}/vote | unvote_post | Remove your vote |
GET /posts/{post}/comments | list_comments | List a post's comments |
POST /posts/{post}/comments | create_comment | Comment on a post |
PATCH /comments/{comment} | update_comment | Edit a comment |
DELETE /comments/{comment} | delete_comment | Delete a comment |
POST /posts/{post}/restore | restore_post | Restore a deleted post |
GET /notifications | list_notifications | List your notifications |
POST /notifications/read | mark_notifications_read | Mark notifications read |
GET /notifications/preferences | get_notification_preferences | Get your notification settings |
PATCH /notifications/preferences | save_notification_preferences | Change your notification settings |
PUT /follows | follow | Follow a post, board or category |
DELETE /follows | unfollow | Unfollow a post, board or category |
GET /email-preferences | get_email_preferences | Get your email settings |
PATCH /email-preferences | save_email_preferences | Change your email settings |
GET /roadmap | get_public_roadmap | Get the public roadmap |
GET /changelog | list_changelog_entries | List changelog entries |
GET /changelog/{entry} | get_changelog_entry | Get a changelog entry |
PUT /changelog-subscription | subscribe_changelog | Subscribe to the changelog |
DELETE /changelog-subscription | unsubscribe_changelog | Unsubscribe from the changelog |
GET /shared/{token} | get_shared_roadmap | Open a shared roadmap |
triage
GET /posts/{post}/voters | list_voters | List a post's voters |
POST /posts/{post}/status | change_post_status | Change a post's status |
GET /moderation/queue | list_moderation_queue | List posts awaiting review |
POST /posts/{post}/moderation | moderate_post | Approve or reject a post |
PUT /posts/{post}/owner | assign_post_owner | Assign a post's owner |
PUT /posts/{post}/eta | set_post_eta | Set a post's ETA |
POST /posts/{post}/tags | add_post_tags | Tag a post |
DELETE /posts/{post}/tags | remove_post_tags | Untag a post |
POST /posts/{post}/move | move_post | Move a post to another board |
POST /posts/{source}/merge | merge_posts | Merge duplicate posts |
DELETE /posts/{post}/merge | unmerge_post | Unmerge a post |
POST /posts/bulk | bulk_update_posts | Update many posts at once |
POST /posts/{post}/votes | add_vote_on_behalf | Vote for a customer |
PATCH /posts/{post}/votes/{user} | set_vote_priority | Set a vote's priority or note |
DELETE /posts/{post}/votes/{user} | remove_vote | Remove a customer's vote |
customers
POST /users/{user}/block | block_user | Block an end user |
DELETE /users/{user}/block | unblock_user | Unblock an end user |
GET /users | search_users | Search customers |
GET /users/{user} | get_user | Get a customer |
POST /users | save_user | Create or update a customer |
POST /users/merge | merge_users | Merge duplicate customers |
DELETE /users/{user} | delete_user | Delete a customer and their content |
GET /users/{user}/export | export_user_data | Export a customer's data |
GET /companies | search_companies | Search companies |
GET /companies/{company} | get_company | Get a company |
POST /companies | save_company | Create or update a company |
PUT /companies/{company}/users/{user} | link_user_company | Add a customer to a company |
DELETE /companies/{company}/users/{user} | unlink_user_company | Remove a customer from a company |
GET /segments | list_segments | List segments |
POST /segments/preview | preview_segment | Preview who is in a segment |
POST /segments | save_segment | Create or update a segment |
DELETE /segments/{segment} | delete_segment | Delete a segment |
planning
GET /views | list_views | List saved views |
GET /views/{view}/rows | run_view | Run a saved view |
POST /views | save_view | Create or update a saved view |
DELETE /views/{view} | delete_view | Delete a saved view |
POST /exports | export_data | Export a CSV |
GET /exports/{export} | get_export | Check an export |
GET /roadmaps | list_roadmaps | List roadmaps |
POST /roadmaps/{roadmap}/query | get_roadmap | Get a roadmap |
POST /roadmaps | save_roadmap | Create or update a roadmap |
DELETE /roadmaps/{roadmap} | delete_roadmap | Delete a roadmap |
POST /roadmaps/{roadmap}/posts | add_to_roadmap | Add posts to a roadmap |
POST /roadmaps/{roadmap}/posts/remove | remove_from_roadmap | Remove posts from a roadmap |
POST /roadmaps/{roadmap}/scoring | configure_scoring | Configure roadmap scoring |
POST /roadmaps/{roadmap}/values | set_factor_values | Set manual factor values |
POST /roadmaps/{roadmap}/rank | rank_roadmap_post | Rank a post on a roadmap |
GET /reports/{type} | get_report | Get a report |
POST /share-links | create_share_link | Share a roadmap view |
GET /share-links | list_share_links | List share links |
DELETE /share-links/{link} | revoke_share_link | Revoke a share link |
changelog
PUT /changelog | save_changelog_entry | Save a changelog entry |
POST /changelog/{entry}/publish | publish_changelog_entry | Publish a changelog entry |
POST /changelog/{entry}/unpublish | unpublish_changelog_entry | Unpublish a changelog entry |
DELETE /changelog/{entry} | delete_changelog_entry | Delete a changelog entry |
GET /changelog-labels | list_changelog_labels | List changelog labels |
PUT /changelog-labels | save_changelog_label | Save a changelog label |
DELETE /changelog-labels/{label} | delete_changelog_label | Delete a changelog label |
GET /changelog-subscribers | list_changelog_subscribers | List changelog subscribers |
admin
GET /members | list_members | List members |
POST /members/invitations | invite_member | Invite a member |
POST /members/invitations/{invitation}/resend | resend_invitation | Resend an invitation |
DELETE /members/invitations/{invitation} | revoke_invitation | Revoke an invitation |
PATCH /members/{member} | update_member_role | Change a member's role |
DELETE /members/{member} | remove_member | Remove a member |
POST /boards | save_board | Save a board |
DELETE /boards/{board} | delete_board | Delete a board |
POST /categories | save_category | Save a category |
DELETE /categories/{category} | delete_category | Delete a category |
POST /statuses | save_status | Save a status |
PUT /statuses/order | reorder_statuses | Reorder statuses |
DELETE /statuses/{status} | delete_status | Delete a status |
POST /tags | save_tag | Save a tag |
DELETE /tags/{tag} | delete_tag | Delete a tag |
GET /custom-fields | list_custom_fields | List custom fields |
POST /custom-fields | save_custom_field | Create or update a custom field |
DELETE /custom-fields/{field} | delete_custom_field | Delete a custom field |
GET /settings | get_workspace_settings | Get workspace settings |
PATCH /settings | update_workspace_settings | Update workspace settings |
POST /settings/domain/check | check_custom_domain | Check the custom domain |
GET /setup | get_setup_checklist | Get the setup checklist |
PATCH /setup | update_setup_checklist | Update the setup checklist |
audit
GET /audit-events | list_audit_events | List audit events |
GET /usage | get_usage | Get usage and performance |
POST /audit-events/{event}/undo | undo_action | Undo an action |