API reference

Build against your feedback loop.

The Hollahoop API is exposed through a hosted MCP JSON-RPC endpoint. Use one org-scoped token to let Cursor, Claude, Codex, internal scripts, or backend jobs read feedback, move roadmap work, publish Updates, and maintain docs.

Create API token MCP client setup

Token auth

Send Authorization: Bearer hh_live_… with every request. Tokens are created from your project workspace and scoped to that organisation.

MCP-native

Use the same endpoint from agents and code. Tool schemas are discoverable through tools/list, and execution happens through tools/call.

Read / write scopes

Each tool declares the permission it needs. Revoked tokens stop working immediately, and REST calls include rate-limit headers.

Endpoint

POST JSON-RPC 2.0 requests to the MCP endpoint. Browser GET requests redirect to the public MCP overview, while API clients should send JSON.

Base URL: https://hollahoop.app/mcp
Auth header: Authorization: Bearer hh_live_…
Content type: application/json

curl https://hollahoop.app/mcp \
  -H "Authorization: Bearer hh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'

REST mirror

Prefer plain HTTP? The same Bearer token works against the REST endpoints below. Bodies and responses match the MCP tool schemas one-to-one, so you can pick whichever surface fits your stack.

Rate limits are per API key: 120 read requests/minute and 30 write requests/minute. Responses include x-ratelimit-limit, x-ratelimit-remaining, and x-ratelimit-reset; 429 responses also include retry-after.

GET/api/v1/healthNo auth

Liveness probe used by /status and external monitors.

GET/api/v1/projectsBearer (read)

List projects under this token's organisation. Mirrors list_projects.

POST/api/v1/projectsBearer (write)

Create a project (boards, statuses, tags auto-seeded). Mirrors create_project.

GET/api/v1/projects/:project/postsBearer (read)

List feedback posts with board/status/sort pagination. Mirrors list_posts.

GET/api/v1/projects/:project/changelogBearer (read)

List Updates/changelog entries, including drafts unless filtered. Mirrors list_changelog.

Create a project via REST

curl -X POST https://hollahoop.app/api/v1/projects \
  -H "Authorization: Bearer hh_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "slug": "acme-feedback",
    "name": "Acme Feedback",
    "tagline": "What customers want next",
    "is_public": true
  }'

List roadmap posts via REST

curl "https://hollahoop.app/api/v1/projects/hollahoop/posts?status=planned&sort=top&limit=10" \
  -H "Authorization: Bearer hh_live_..."

List published Updates via REST

curl "https://hollahoop.app/api/v1/projects/hollahoop/changelog?status=published&limit=10" \
  -H "Authorization: Bearer hh_live_..."

Tool calls

Call a tool by name with a JSON object that matches its schema. Agents do this automatically; scripts can call the same endpoint directly.

List projects

{
  "jsonrpc": "2.0",
  "id": 2,
  "method": "tools/call",
  "params": {
    "name": "list_projects",
    "arguments": {}
  }
}

Publish an Update

{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "publish_changelog",
    "arguments": {
      "project": "hollahoop",
      "title": "New API docs",
      "body_md": "We added a public API reference.",
      "tag": "announcement"
    }
  }
}

Available tools

14 tools are currently exposed. Read tools can inspect data; write tools can create or mutate feedback, roadmap, Updates, and docs.

See MCP setup details →

Read

list_projects

List every project the API key can see (scoped to a single Hollahoop organisation).

list_boards

List feedback boards on a project (e.g. feature-requests, bugs, general).

list_statuses

List the post-status workflow for a project (Open / Planned / In progress / Shipped / Declined and any custom ones).

list_posts

List feedback posts on a project, optionally filtered by board and/or status. Default sort is by vote count.

get_post

Fetch a single post by id, including its comments.

list_changelog

List changelog / Updates entries for a project (drafts and published).

list_docs

List documentation pages for a project, grouped by section. Use the `visibility` filter to scope to public or internal pages.

Free-text search across posts, changelog entries, and docs for a project. ILIKE-based for now; pgvector semantic search is on the roadmap.

Write

create_project

Create a new project under this API key’s organisation. Returns the project plus the URL of its public board. Default boards, statuses, changelog tags, and docs section are auto-seeded.

create_post

Create a new feedback / roadmap post. Defaults to the feature-requests board and the project default status (Open).

update_post_status

Move a post on the roadmap by changing its status. Use this to accept feedback (open → planned), start work (planned → in_progress), or ship (in_progress → shipped).

comment_on_post

Add a comment (or reply, via parent_id) to a post. The author is the user who created this API key.

publish_changelog

Create a changelog / Updates entry. Set publish=false to leave it as a draft. Auto-derives a slug from the title if none is given. The optional `tag` becomes the pill on the public Updates feed.

upsert_doc_page

Create or update a documentation page (uniquely identified by project + slug). Body is Markdown. Pass visibility=internal to keep the page hidden from the public site.