canonical: https://jentic.com/apis/hackmd.io/hackmd

# HackMD API

HackMD is a real-time collaborative Markdown editor used by engineering teams, researchers, and educators for shared notes, meeting minutes, and documentation. The API exposes operations to read the authenticated user's profile, manage personal notes, list note history, and manage notes that belong to a team. Agents can create, update, and delete notes programmatically, making HackMD a natural collaborative output target for AI writing and meeting-summary workflows.

## For AI agents

Read a HackMD user's profile, create and update personal or team notes in Markdown, and pull recent note history.

## Scope

Does not handle slide presentations, file attachments, or real-time chat - use for HackMD Markdown notes, history, and team workspaces only.

## Capabilities

- Get the authenticated user's HackMD profile, name, and email
- List, create, update, and delete personal notes in Markdown
- Retrieve a note by id with its full Markdown content and permissions
- Read recent edit history across the user's notes
- List the teams the user belongs to with role and team path
- Create, update, and delete notes that live inside a team workspace

## Use cases

### Meeting Summary to Shared Note

Convert a transcribed meeting recording into a Markdown summary and post it as a HackMD note that the team can edit collaboratively. The agent calls POST `/teams/{teamPath}/notes` with the rendered Markdown and read/write permissions, then shares the returned URL with the channel. HackMD handles real-time co-editing once humans take over.

Example prompt: POST `/teams/engineering/notes` with title 'Sprint Planning 2026-06-10' and a Markdown body summarising the transcript, returning the note URL.

### Documentation Pull-Then-Update

Maintain a runbook by pulling its current Markdown via GET `/notes/{noteId}`, asking an LLM to refresh it based on a recent incident, and writing it back via PATCH `/notes/{noteId}.` Useful for SRE teams keeping playbooks current without making humans hand-edit every time.

Example prompt: GET `/notes/{noteId}`, generate a refreshed Markdown body using the incident report, then PATCH `/notes/{noteId}` with the new content.

### Personal Note Capture from Chat

Listen to a chat channel for messages tagged for personal capture and create matching HackMD notes via POST /notes. The agent organises notes by topic in the title and dumps the full message context into the body. Knowledge workers use this to consolidate scattered chat into searchable Markdown.

Example prompt: POST /notes with a title from the message subject and a body containing the full thread Markdown, then return the new note id.

### Team Workspace Audit

List all teams the user belongs to and enumerate their notes for a content audit. The agent walks /teams to find team paths, then walks `/teams/{teamPath}/notes` to inspect titles, last-modified timestamps, and tag fields. Useful for cleaning up stale documentation in large organisations.

Example prompt: GET /teams, then for each team GET `/teams/{teamPath}/notes` and report any note unmodified for over 180 days.

### Agent Discovery Through Jentic

Agents discover HackMD operations by searching Jentic with intents like 'create a markdown note'. Jentic returns the matching POST /notes operation with its input schema. The bearer token is stored in the vault, never in the agent prompt.

Example prompt: Use Jentic search 'create a markdown note' to find POST /notes and execute it with title and content fields.

## Key endpoints

| Method | Path | Description |
| --- | --- | --- |
| GET | `/me` | Get the authenticated user's profile |
| GET | `/notes` | List the user's personal notes |
| POST | `/notes` | Create a new personal note |
| PATCH | `/notes/{noteId}` | Update a personal note's content |
| GET | `/history` | Read recent edit history |
| GET | `/teams` | List the user's teams |
| POST | `/teams/{teamPath}/notes` | Create a note inside a team workspace |

## Key resources

- **Me** — Read the authenticated user's profile
- **Notes** — List, create, retrieve, update, and delete personal notes
- **History** — Read recent edit activity across the user's notes
- **Teams** — List teams the user belongs to with role and path
- **Team notes** — List, create, retrieve, update, and delete notes inside a team workspace

## Why Jentic

- **Setup:** Wiring the HackMD API by hand means setting its bearer token on every call and building each note, history, and team request yourself. Through Jentic you install once, import the HackMD API from the API Directory, store the token once, and your agent calls it.
- **Permission scoping:** HackMD puts the team path in the URL (`/teams/{teamPath}/notes`), so a rule can pin your agent to one team workspace: it can create and list notes there and nothing else. You choose the operations it may call, so editing existing notes is not included unless you add it.
- **Credential handling:** Your HackMD bearer token 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 'create a markdown note' or 'list team notes', and Jentic returns the matching HackMD operation with its input schema so the agent calls the right endpoint without browsing the docs.

## Related APIs

- **Notion API** — Block-based collaborative workspace with databases and structured content.
- **GitHub API** — Markdown files in a Git repo with full version history.
- **Asana API** — Link HackMD meeting notes to Asana action items.

## FAQ

### What authentication does the HackMD API use?

HackMD uses Bearer token authentication. Generate a token from the HackMD account settings under API tokens and pass it as Authorization: Bearer <token>. Through Jentic, the token stays encrypted in the vault and is injected at execution time so the agent never sees the raw value.

### Can I create a Markdown note in a team workspace?

Yes. POST `/teams/{teamPath}/notes` with the title, content, readPermission, and writePermission fields creates the note inside the team. The teamPath is the slug shown in the team URL. The response returns the note id and shareable URL.

### How do I update an existing HackMD note?

PATCH `/notes/{noteId}` updates the note's content and metadata. Pass the full new Markdown body in the content field. For team-owned notes, use PATCH `/teams/{teamPath}/notes/{noteId}` instead. The endpoint requires write permission on the note.

### What rate limits apply to the HackMD API?

HackMD enforces per-token rate limits and returns 429 when exceeded. Public documentation lists a soft ceiling of around 100 requests per hour for read operations and a stricter limit for writes. Agents should respect 429 responses and back off.

### How do I post a meeting summary to HackMD through Jentic?

Run pip install jentic, then search 'create a markdown note in a team' to find POST `/teams/{teamPath}/notes.` Load the schema, fill in title, content, and team path, and execute. The full flow takes under five minutes once the team path is known.

### Can I see who edited a note recently?

GET /history returns recently edited notes for the authenticated user with last-changed timestamps, but the API does not expose a per-note revision diff. For collaborative authoring history, follow the note URL into HackMD's web UI which shows the full revision pane.

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

Yes. Because you run Jentic One yourself, your own rules decide which HackMD operations and credentials your agent may use. Since HackMD puts the team path in the URL such as `/teams/{teamPath}/notes`, you can pin the agent to a single team workspace and allow only the operations you pick, for example creating and listing notes there. Editing existing notes with PATCH `/notes/{noteId}` stays off unless you explicitly add it, and your bearer token is injected at execution time rather than exposed to the agent.