canonical: https://jentic.com/apis/heartbeat.readme.io/heartbeat

# Heartbeat Readme Heartbeat API

This is the full Heartbeat community platform API as published through Heartbeat's developer documentation on heartbeat.readme.io. It covers the same v0 endpoints as the core spec - users, channels, threads, comments - and adds management surfaces for invitations, pending users, notifications, roles, and groups, plus broader CRUD coverage on every resource. Community operators use it to deeply integrate Heartbeat with internal systems, run governance workflows like role assignment and invitation tracking, and pull notification streams for external dashboards.

## For AI agents

Manage Heartbeat community users, invitations, roles, groups, channels, threads, and notifications through the full v0 REST surface, with bearer-authenticated calls.

## Scope

Does not handle billing, video conferencing, or analytics reporting - use for Heartbeat community member, invitation, role, group, channel, thread, and notification management only.

## Capabilities

- Manage member lifecycles end-to-end via /users, /pendingUser, and `/users/reactivate`
- Issue and track community invitations through /invitations and `/invitations/{invitationID}`
- Assign and inspect community roles through /roles and group membership through /groups
- Stream and acknowledge member notifications via /notifications
- Search the member directory by name or email via `/find/users`
- Manage threads, comments, and channel structure across the full /threads, /comments, and /channels surface

## Use cases

### Invitation Lifecycle Automation

Drive Heartbeat invitations from your CRM or onboarding tool. PUT /invitations to create an invitation when a customer signs a contract, GET /invitations to track which ones are still pending, and POST `/invitations/{invitationID}` to update or revoke them. This keeps community access aligned with your customer lifecycle without manual admin work in the Heartbeat dashboard.

Example prompt: PUT /invitations with the new customer's email, then GET /invitations to confirm the invitation appears as pending

### Role and Group Governance

Use /roles and /groups to programmatically grant moderators, course creators, or VIP members the right access. Combine with /users to bind specific members to roles, and audit by reading the same endpoints on a schedule. This makes role drift visible and recoverable instead of being buried in admin UI clicks.

Example prompt: GET /roles and /groups, then update group membership via PUT /groups for the moderator group with the latest moderator list

### Notification Stream Integration

Pipe member notifications from Heartbeat into your internal dashboards by polling /notifications. This lets you display unread mentions and replies in another tool - for example, a customer success workspace - alongside other signals about a member. Acknowledge or mark notifications read through the same surface to keep state consistent.

Example prompt: GET /notifications for a userID, filter unread, and surface them in an internal dashboard

### AI Agent Community Governance via Jentic

A community-ops agent searches Jentic for 'invite a user to a community' and Jentic returns the Heartbeat /invitations operation. The agent issues invitations from CRM events, assigns roles based on customer tier, and revokes invitations on churn - all without holding the bearer token directly because Jentic securely stores it. This makes the full Heartbeat governance surface composable from a copilot.

Example prompt: Use Jentic search 'invite a user to a community' to load /invitations and execute with the new customer's email

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/users` | List members |
| POST | `/users` | Create a member |
| PUT | `/invitations` | Create an invitation |
| GET | `/invitations` | List invitations |
| POST | `/invitations/{invitationID}` | Update or revoke an invitation |
| GET | `/roles` | List community roles |
| GET | `/groups` | List community groups |
| GET | `/notifications` | Read notifications |

## Key resources

- **Users** — Full user lifecycle via /users, /pendingUser, `/users/reactivate`, and `/find/users`
- **Invitations** — Issue, list, update, and revoke invitations via /invitations and `/invitations/{invitationID}`
- **Roles** — List and inspect community roles via /roles
- **Groups** — List and update community groups via /groups
- **Notifications** — Read member notifications via /notifications
- **Channels** — Manage channel structure via the /channels endpoints
- **Threads and Comments** — Manage threads and comments via /threads and /comments

## Why Jentic

- **Setup:** Wiring Heartbeat by hand means minting a bearer token that grants full community read and write, including invitations and roles, and attaching the Authorization header on every call. Through Jentic you install once, import the Heartbeat API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** Heartbeat handles members and roles through request bodies on shared endpoints like /users, /roles, and /groups, so limit the agent to the operations it needs, such as inviting a user or listing roles. You choose the operations it may call, so changes like removing a member are not included unless you add them.
- **Credential handling:** Your Heartbeat bearer token is stored once, encrypted, by your own Jentic One instance and injected as the Authorization header at execution time. It never enters the agent's prompt, logs, or context.
- **Discovery method:** Agents search Jentic by intent such as 'invite a user to a community' or 'list community roles', and Jentic returns the matching /invitations, /roles, or /groups operation with its input schema so the agent calls the right endpoint without browsing the reference docs.

## Related APIs

- **Heartbeat API (Core)** — The heartbeat.chat spec covers the core 23 user/channel/thread endpoints; this spec adds invitations, roles, groups, and notifications
- **Circle API** — Circle is a direct competitor for membership-community platforms with similar invitation and member management
- **Slack API** — Slack runs internal team communication while Heartbeat hosts the external community

## FAQ

### What authentication does the Heartbeat API use?

The API uses HTTP Bearer authentication. Pass your Heartbeat token in the Authorization header on every call. Jentic stores the token in the vault and attaches it for each request.

### Can I issue community invitations through the API?

Yes. PUT /invitations to create one, GET /invitations to list pending invitations, and POST `/invitations/{invitationID}` to update or revoke. Invitation status flows through the same endpoints as the dashboard uses.

### How do I list community roles and groups?

GET /roles returns the available role definitions and GET /groups returns the configured groups. Use these alongside /users to assign members or audit access at scale.

### What are the rate limits for the Heartbeat API?

Heartbeat does not document a public per-account rate limit. For high-volume governance jobs, batch reads and back off on HTTP 429 - the bearer token is shared across all v0 endpoints, so a single throttled request affects the whole job.

### How do I invite a user through Jentic?

Search Jentic for 'invite a user to a community', load the PUT /invitations operation for heartbeat.readme.io, and execute with the new user's email. Jentic injects the bearer token from the vault.

### How does this API differ from heartbeat.chat?

Both specs target the same base URL (api.heartbeat.chat/v0). The heartbeat.chat spec covers the core 23 endpoints, while this spec - sourced from heartbeat.readme.io - covers the full 53 endpoints including invitations, roles, groups, and notifications. Use this one when you need governance and notification operations.

### Can I limit what my agent is allowed to do with the Heartbeat API?

Yes. Because you run Jentic One yourself, your own rules decide which Heartbeat operations and credentials the agent may use. Since Heartbeat drives members, roles, and groups through request bodies on shared endpoints like /users, /roles, and /groups, you scope the agent to just the operations it needs, such as PUT /invitations to invite a user or GET /roles to list roles. Destructive changes like removing a member are not available to the agent unless you explicitly add them.