HackMD User Notes API
Operations related to a user's personal notes.
Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/hackmd:hackmd-user-notes-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Calls without X-API-Key need no key. Calls with it need a paid plan — get a key.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: HackMD Open User Notes API
version: 1.0.0
description: HackMD OpenAPI
license:
name: UNLICENSED
contact:
name: HackMD Team
email: support@hackmd.io
servers:
- url: /v1
description: API Server
tags:
- name: User Notes
description: Operations related to a user's personal notes.
paths:
/notes:
get:
operationId: ListNotes
responses:
'200':
description: Ok
content:
application/json:
schema:
items:
$ref: '#/components/schemas/NoteType'
type: array
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRequestErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'429':
description: Rate limit or workspace quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiServerErrorResponse'
description: List all notes for the current user
tags:
- User Notes
security:
- token: []
parameters: []
summary: List notes
x-summary-source: derived
post:
operationId: CreateNote
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SingleNote'
'207':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/CreateNoteMultiStatusResponse'
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiBadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiValidationError'
'429':
description: Rate limit or workspace quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiServerErrorResponse'
description: Create a new note for the current user
tags:
- User Notes
security:
- token: []
parameters: []
requestBody:
description: The note content or a JSON object with note properties.
required: false
content:
application/json:
schema:
anyOf:
- properties:
origin:
type: string
parentFolderId:
type: string
permalink:
type: string
noteFeatures:
$ref: '#/components/schemas/ApiNoteFeatures'
suggestEditPermission:
$ref: '#/components/schemas/SuggestEditPermissionType'
commentPermission:
$ref: '#/components/schemas/CommentPermissionType'
writePermission:
$ref: '#/components/schemas/NotePermissionRole'
readPermission:
$ref: '#/components/schemas/NotePermissionRole'
content:
type: string
description:
type: string
tags:
items:
type: string
type: array
title:
type: string
type: object
- type: string
description: The note content or a JSON object with note properties.
summary: Create note
x-summary-source: derived
/notes/{noteId}:
get:
operationId: GetNote
responses:
'200':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/SingleNote'
headers:
ETag:
schema:
type: string
required: true
'304':
description: ''
headers:
ETag:
schema:
type: string
required: true
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRequestErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'429':
description: Rate limit or workspace quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitErrorResponse'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiServerErrorResponse'
description: Get a single note for the current user (or team note if accessible)
tags:
- User Notes
security:
- token: []
parameters:
- description: The ID of the note to retrieve.
in: path
name: noteId
required: true
schema:
type: string
- description: Return 304 when this ETag matches the current note.
in: header
name: If-None-Match
required: false
schema:
type: string
summary: Get note
x-summary-source: derived
delete:
operationId: DeleteNote
responses:
'204':
description: No content
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiBadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'429':
description: Rate limit or workspace quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitErrorResponse'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiServerErrorResponse'
description: Delete a note for the current user
tags:
- User Notes
security:
- token: []
parameters:
- description: The ID of the note to delete.
in: path
name: noteId
required: true
schema:
type: string
summary: Delete note
x-summary-source: derived
patch:
operationId: UpdateNote
responses:
'202':
description: ''
'400':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiBadRequestResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'404':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'409':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'422':
description: Validation failed
content:
application/json:
schema:
$ref: '#/components/schemas/ApiValidationError'
'429':
description: Rate limit or workspace quota exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRateLimitErrorResponse'
'500':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiServerErrorResponse'
description: Update a note's content or permissions for the current user
tags:
- User Notes
security:
- token: []
parameters:
- description: The ID of the note to update.
in: path
name: noteId
required: true
schema:
type: string
requestBody:
description: The properties to update on the note. Omit description to leave it unchanged, use a string (including an empty string) to set it, or null to remove its metadata.
required: true
content:
application/json:
schema:
properties:
parentFolderId:
type:
- string
- 'null'
permalink:
type: string
writePermission:
$ref: '#/components/schemas/NotePermissionRole'
readPermission:
$ref: '#/components/schemas/NotePermissionRole'
content:
type: string
description:
type:
- string
- 'null'
tags:
items:
type: string
type: array
title:
type: string
type: object
description: The properties to update on the note. Omit description to leave it unchanged, use a string (including an empty string) to set it, or null to remove its metadata.
summary: Update note
x-summary-source: derived
/notes/{noteId}/images:
post:
operationId: UploadNoteImage
responses:
'201':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/NoteImageUploadResponse'
'400':
description: Bad Request
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRequestErrorResponse'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/ApiErrorResponse'
'403':
description: Forbidden
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ApiErrorResponse'
- $ref: '#/components/schemas/ApiRequestErrorResponse'
'413':
description: Payload Too Large
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRequestErrorResponse'
'415':
description: Unsupported Media Type
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRequestErrorResponse'
'422':
description: ''
content:
application/json:
schema:
$ref: '#/components/schemas/ApiRequestErrorResponse'
'429':
description: Too Many Requests
content:
application/json:
schema:
anyOf:
- $ref: '#/components/schemas/ApiRequestErrorResponse'
- $ref: '#/components/schemas/ApiRateLimitErrorResponse'
'500':
description: Internal Server Error
content:
application/json:
schema:
$ref: '#/components/schemas/ApiServerErrorResponse'
description: Upload an image for a note.
tags:
- User Notes
security:
- token: []
parameters:
- in: path
name: noteId
required: true
schema:
type: string
requestBody:
required: true
content:
multipart/form-data:
schema:
type: object
properties:
image:
type: string
format: binary
required:
- image
summary: Upload note image
x-summary-source: derived
components:
schemas:
ApiValidationError:
properties:
message:
type: string
enum:
- Validation Failed
details:
$ref: '#/components/schemas/Record_string.ApiValidationFieldError_'
required:
- message
- details
type: object
additionalProperties: false
SingleNote:
properties:
folderPaths:
items:
$ref: '#/components/schemas/FolderPath'
type: array
writePermission:
$ref: '#/components/schemas/NotePermissionRole'
readPermission:
$ref: '#/components/schemas/NotePermissionRole'
shortId:
type: string
publishLink:
type: string
permalink:
type:
- string
- 'null'
teamPath:
type:
- string
- 'null'
userPath:
type:
- string
- 'null'
publishedAt:
type:
- number
- 'null'
format: double
publishType:
$ref: '#/components/schemas/NotePublishType'
lastChangeUser:
allOf:
- $ref: '#/components/schemas/SimpleUserProfile'
tagsUpdatedAt:
type:
- number
- 'null'
format: double
titleUpdatedAt:
type:
- number
- 'null'
format: double
createdAt:
type: number
format: double
lastChangedAt:
type: number
format: double
description:
type: string
tags:
items:
type: string
type: array
title:
type: string
id:
type: string
content:
type: string
required:
- writePermission
- readPermission
- shortId
- publishLink
- permalink
- teamPath
- userPath
- publishedAt
- publishType
- lastChangeUser
- tagsUpdatedAt
- titleUpdatedAt
- createdAt
- lastChangedAt
- description
- tags
- title
- id
- content
type: object
additionalProperties: false
NotePermissionRole:
enum:
- owner
- signed_in
- guest
type: string
CommentPermissionType:
enum:
- disabled
- forbidden
- owners
- signed_in_users
- everyone
type: string
CreateNoteMultiStatusResponse:
properties:
note:
$ref: '#/components/schemas/SingleNote'
error:
type: string
required:
- note
- error
type: object
additionalProperties: false
ApiErrorResponse:
properties:
error:
type: string
required:
- error
type: object
additionalProperties: false
ApiRateLimitErrorResponse:
anyOf:
- $ref: '#/components/schemas/ApiErrorResponse'
- $ref: '#/components/schemas/ApiQuotaErrorResponse'
ApiValidationFieldError:
properties:
message:
type: string
value: {}
required:
- message
type: object
additionalProperties: false
SuggestEditPermissionType:
enum:
- disabled
- forbidden
- owners
- signed_in_users
type: string
ApiRequestErrorResponse:
properties:
message:
type: string
required:
- message
type: object
additionalProperties: false
ApiQuotaErrorResponse:
properties:
error:
properties:
upgradeUrl:
type: string
helpUrl:
type: string
message:
type: string
code:
type: string
enum:
- quota_exceeded
required:
- upgradeUrl
- helpUrl
- message
- code
type: object
required:
- error
type: object
additionalProperties: false
FolderPath:
properties:
id:
type: string
name:
type: string
icon:
type:
- string
- 'null'
color:
type:
- string
- 'null'
parentId:
type:
- string
- 'null'
clientId:
type: string
required:
- id
- name
- icon
- color
- parentId
- clientId
type: object
additionalProperties: false
ApiNoteFeatures:
properties:
emoji-reply:
type: string
enum:
- disabled
- signed_in_users
citation:
type: string
enum:
- disabled
- signed_in_users
type: object
additionalProperties: false
SimpleUserProfile:
properties:
name:
type: string
userPath:
type: string
photo:
type: string
biography:
type:
- string
- 'null'
required:
- name
- userPath
- photo
- biography
type: object
additionalProperties: false
Record_string.ApiValidationFieldError_:
properties: {}
additionalProperties:
$ref: '#/components/schemas/ApiValidationFieldError'
type: object
description: Construct a type with a set of properties K of type T
NoteImageUploadResponse:
properties:
data:
properties:
link:
type: string
required:
- link
type: object
required:
- data
type: object
additionalProperties: false
ApiBadRequestResponse:
anyOf:
- $ref: '#/components/schemas/ApiErrorResponse'
- $ref: '#/components/schemas/ApiRequestErrorResponse'
ApiServerErrorResponse:
anyOf:
- $ref: '#/components/schemas/ApiErrorResponse'
- $ref: '#/components/schemas/ApiRequestErrorResponse'
NoteType:
properties:
folderPaths:
items:
$ref: '#/components/schemas/FolderPath'
type: array
writePermission:
$ref: '#/components/schemas/NotePermissionRole'
readPermission:
$ref: '#/components/schemas/NotePermissionRole'
shortId:
type: string
publishLink:
type: string
permalink:
type:
- string
- 'null'
teamPath:
type:
- string
- 'null'
userPath:
type:
- string
- 'null'
publishedAt:
type:
- number
- 'null'
format: double
publishType:
$ref: '#/components/schemas/NotePublishType'
lastChangeUser:
allOf:
- $ref: '#/components/schemas/SimpleUserProfile'
tagsUpdatedAt:
type:
- number
- 'null'
format: double
titleUpdatedAt:
type:
- number
- 'null'
format: double
createdAt:
type: number
format: double
lastChangedAt:
type: number
format: double
description:
type: string
tags:
items:
type: string
type: array
title:
type: string
id:
type: string
required:
- writePermission
- readPermission
- shortId
- publishLink
- permalink
- teamPath
- userPath
- publishedAt
- publishType
- lastChangeUser
- tagsUpdatedAt
- titleUpdatedAt
- createdAt
- lastChangedAt
- description
- tags
- title
- id
type: object
NotePublishType:
enum:
- edit
- view
- slide
- book
type: string
securitySchemes:
token:
type: http
scheme: bearer
x-provenance:
method: harvested
publisher: HackMD
source: https://api.hackmd.io/v1/docs/swagger.json
note: split by refine-openapis from the provider's own published document, verified by fetch (openapi/_original/*.fetch.json);
stamped by stamp-openapi-provenance.py (roadmap#793)