canonical: https://jentic.com/apis/huddlekit.com/huddlekit # Huddlekit API The Huddlekit API reads and writes the review comments a workspace leaves on websites, web apps, and uploaded documents. It lists a workspace's projects, web apps, and documents, returns the newest comments on any of them, adds new comments, and moves a comment through the open, in-review, in-progress, and resolved statuses. It also manages REST-hook webhook subscriptions for comment events, signed with HMAC-SHA256, and can render sample payloads from recent comments so you can map fields before a live event fires. Comment text cannot be edited and comments cannot be deleted through the API. ## For AI agents Read website, web app, and document review comments in a Huddlekit workspace, post new comments, change a comment's status to resolved or in-progress, and subscribe a URL to comment events. ## Scope Does not edit or delete comment text, create projects or upload documents, or manage workspace members and billing. Use for reading, posting, and triaging Huddlekit review comments and their webhooks only. ## Capabilities - List every website project, web app, and document in the workspace to find the parent_id a comment belongs to - Pull the newest comments on one project, web app, or document, up to 200 per call - Post a comment on a page path, a web app URL, a document page number, or a video timestamp - Move a comment between open, in-review, in-progress, and resolved - Subscribe an https URL to comment.created or comment.status_changed events and remove that subscription later - Render sample webhook payloads from recent comments to map fields before any event fires ## Use cases ### Agent triage of design review comments through Jentic A developer's coding agent pulls the open review comments on a website project through Jentic, fixes what it can in the codebase, and moves each handled comment to in-review. The agent finds the operations by intent, the Huddlekit key is injected by the developer's own Jentic One instance, and a rule can keep the agent on read and status-change calls only. Example prompt: Call GET /projects to find the website project named Marketing Site, call GET /comments with its id as parent_id, then for each comment fixed in the repo call PATCH `/comments/{id}` with status in-review ### Feed new comments into an issue tracker Send every new Huddlekit comment to a tracker or chat channel as it is created. Subscribing an https URL to comment.created events gives a REST-hook delivery signed with the X-Huddlekit-Signature header, and the sample payloads call shows the exact delivery shape so the receiving handler can be built and tested first. Example prompt: Call GET `/events/recent` with event comment.created and limit 3 to get sample payloads, then call POST /hooks with targetUrl https://hooks.example.dev/huddlekit and event_types comment.created ### Post QA findings as page comments A QA script or agent that finds a layout bug can leave the finding where the team already reviews work. POST /comments takes the parent_id, the surface, the comment text, and a page path such as /pricing for a website, a url for a web app, or a page_number for a document. Example prompt: Call POST /comments with the website project's parent_id, surface website, path /pricing, and text 'Primary button overlaps the footer at 375px width' ### Weekly feedback status report Summarise how much review feedback is still open across a workspace. The agent lists all projects, web apps, and documents, pulls the newest comments on each, and counts them by status so a team lead can see what is still open, in review, in progress, or resolved. Example prompt: Call GET /projects, then GET /comments for each parent_id with limit 200, and report the count of comments in each status: open, in-review, in-progress, and resolved ## Key endpoints | Method | Path | Description | | --- | --- | --- | | GET | `/projects` | List projects, web apps, and documents | | GET | `/comments` | List comments on one parent | | POST | `/comments` | Create a comment | | PATCH | `/comments/{id}` | Change a comment's status | | POST | `/hooks` | Subscribe a URL to comment events | | DELETE | `/hooks/{id}` | Unsubscribe a webhook | | GET | `/events/recent` | Get sample webhook payloads | | GET | `/me` | Check the key's workspace and scopes | ## Key resources - **Projects** — Website projects, web apps, and documents that comments attach to, each with an id and surface - **Comments** — Review comments that can be listed per parent, created, and moved between statuses - **Webhook subscriptions** — REST-hook subscriptions for comment events, created, listed, and deleted per API key - **Sample events** — Webhook payloads rendered from recent comments for testing a handler ## AI readiness This API is usable in Jentic One now. Its AI-readiness score against Jentic's framework shows where it stands today and where improvements would make it even easier for agents to use. - **Score:** 73 / 100 - **Maturity:** AI-Aware - **Dimensions:** - Foundational Compliance: 85 / 100 - Developer Experience & Jentic Compatibility: 71 / 100 - AI-Readiness & Agent Experience: 60 / 100 - Agent Usability: 94 / 100 - Security: 60 / 100 - AI Discoverability: 90 / 100 - **View full report:** https://jentic.com/apis/huddlekit.com/huddlekit/scorecard - **How the score is calculated:** https://docs.jentic.com/reference/api-readiness-framework/overview/ - **More about the dimensions:** https://docs.jentic.com/reference/api-readiness-framework/specification/#dimensional-model-overview ### Score it yourself Every API in the directory is allowlisted, so you can re-score it with no key required. - **Score your own API:** https://jentic.com/scorecard.md - **Scoring CLI agent skill:** https://github.com/jentic/jentic-api-scorecard/blob/main/skills/jentic-api-scorecard/SKILL.md ```sh npx @jentic/api-scorecard-cli score ``` ## Why Jentic - **Setup:** Wiring the Huddlekit API by hand means creating a workspace key with the right read or write scope, sending it as a bearer token, looking up each parent_id and surface before you can touch a comment, and backing off on 429 responses. Through Jentic you install once, import the Huddlekit API from the API Directory, store the key once, and your agent calls it. - **Permission scoping:** Huddlekit takes the project, web app, or document id as the parent_id query or body field rather than in the URL path, so rules bound which operations your agent may call, not which project. You choose the operations it may call, so posting comments or subscribing webhooks are not included unless you add them. - **Credential handling:** Your Huddlekit workspace key is stored once, encrypted, by your own Jentic One instance and injected at execution time. It never enters the agent's prompt, logs, or context. - **Discovery method:** Agents search Jentic by intent such as 'list feedback comments' or 'resolve a comment', and Jentic returns the matching Huddlekit operation with its input schema so the agent calls the right endpoint without browsing the reference docs. ## Related APIs - **BugHerd API** — Visual bug tracking with pinned website feedback and a task board - **Usersnap API** — User feedback and bug reporting widgets for web products - **Linear API** — Issue tracking for the engineering work that review comments turn into - **Jira API** — Issue and project tracking for teams that triage feedback in Jira ## FAQ ### What authentication does the Huddlekit API use? Per its OpenAPI spec, the Huddlekit API uses a workspace API key sent as a bearer token in the Authorization header, in the form hk_live_ followed by 64 hex characters. Keys carry a read scope for GET calls, a write scope for POST, PATCH, and DELETE calls, or both, and GET /me tells you which scopes a key has. Through Jentic the key is stored encrypted by your own Jentic One instance and never handed to the agent. ### Can I edit or delete comments with the Huddlekit API? No. The spec states that status is the only field PATCH `/comments/{id}` can change: sending text returns 400, and there is no delete operation for comments. You can create comments with POST /comments and move them between open, in-review, in-progress, and resolved. ### What are the rate limits for the Huddlekit API? Huddlekit's OpenAPI spec states that limits are counted per API key, per endpoint group, and separately for reads and writes: up to 200 reads and 30 writes a minute. Going over returns 429 with a Retry-After header in seconds, and refused calls count toward the limit too. ### Does the Huddlekit API need a paid plan? According to the spec, every call except DELETE `/hooks/{id}` requires an active or trialing Team subscription, and a past-due payment fails the check with a 403 that lists requiredPlans. Deleting a webhook is deliberately not plan-gated so automations can always be switched off. ### How do I resolve a Huddlekit comment through Jentic? Search Jentic for 'resolve a review comment' to get PATCH `/comments/{id}`, then call it with the comment id and status resolved, passing surface when the comment is on a web app or document. To run it on your own infrastructure, install Jentic One from its GitHub repo, add the Huddlekit API from the directory, and store your key once. ### Is there a Huddlekit MCP server? You don't need an MCP server to give your agent Huddlekit. Jentic connects it directly from the API Directory: import it, store your workspace key once, and your agent calls the operations you allow, without another server's tool definitions sitting in its context. ### Can I limit what my agent is allowed to do with the Huddlekit API? Yes. For example, write a rule that allows only GET /projects, GET /comments, and PATCH `/comments/{id}`, so the agent can read feedback and change comment statuses but cannot post new comments or create webhook subscriptions. Every call it makes is logged by your Jentic One instance.