User Notes API

User Notes API

Get a list of notes in the user's workspace

GET /notes

Success Response

code: 200

body:

    [
       {
          "id": "ehgwc6a8RXSmcSaRwIQ2jw",
          "title": "Personal note title",
          "tags": ["personal", "test"],
          "createdAt": 1643270371245,
          "publishType": "view",
          "publishedAt": null,
          "permalink": null,
          "shortId": "SysJb0yAY",
          "lastChangedAt": 1643270452413,
          "lastChangeUser": {
              "name": "James",
              "photo": "https://avatars.githubusercontent.com/u/26138990?s=96",
              "biography": null,
              "userPath": "AMQ36J15QgCZf46ThEFadg"
          },
          "userPath": "AMQ36J15QgCZf46ThEFadg",
          "teamPath": null,
          "readPermission": "guest",
          "writePermission": "signed_in",
          "publishLink": "https://hackmd.io/@username/permalink"
        }
     ]

Get a note

GET /notes/:noteId
URL Params:
- noteId: string

Success Response

code: 200

body:

    {
        "id": "ehgwc6a8RXSmcSaRwIQ2jw",
        "title": "Personal note title",
        "tags": [
            "Personal",
            "test"
        ],
        "createdAt": 1643270371245,
        "publishType": "view",
        "publishedAt": null,
        "permalink": null,
        "shortId": "SysJb0yAY",
        "content": "# Personal note title\n###### tags: `Personal` `test`",
        "lastChangedAt": 1644461594806,
        "lastChangeUser": {
            "name": "James",
            "photo": "https://avatars.githubusercontent.com/u/26138990?s=96",
            "biography": null,
            "userPath": "AMQ36J15QgCZf46ThEFadg"
        },
        "userPath": "AMQ36J15QgCZf46ThEFadg",
        "teamPath": null,
        "readPermission": "guest",
        "writePermission": "signed_in",
        "publishLink": "https://hackmd.io/@username/permalink"                
    }

Create a note

POST /notes

Data Params

body (optional) [application/json]

{
    "title": "New note",
    "content": "",
    "readPermission": "owner",
    "writePermission": "owner",
    "commentPermission": "everyone"
}

field	type	values
title	string
content	string
readPermission	string	`owner`, `signed_in`, `guest`
writePermission	string	`owner`, `signed_in`, `guest`
commentPermission	string	`disabled`, `forbidden`, `owners`, `signed_in_users`, `everyone`
permalink	string

Success Response

code: 201

body:

   {
       "id": "ppZ6pJ9iRFa7RHHUegcLiQ",
       "title": "New note",
       "tags": null,
       "createdAt": 1644461842833,
       "publishType": "view",
       "publishedAt": null,
       "permalink": null,
       "shortId": "HyiMJWMk9",
       "content": "test",
       "lastChangedAt": 1644461842832,
       "lastChangeUser": {
           "name": "James",
           "photo": "https://avatars.githubusercontent.com/u/26138990?s=96",
           "biography": null,
           "userPath": "AMQ36J15QgCZf46ThEFadg"
       },
       "userPath": "AMQ36J15QgCZf46ThEFadg",
       "teamPath": null,
       "readPermission": "owner",
       "writePermission": "owner",
       "publishLink": "https://hackmd.io/@username/permalink"                    
   }

:bulb: Notes on the `Title` field

As for now, the title of a note is derived from the content, thus the behavior of "title" field may need further explanation.

If there's a H1 header in the "content" field, then it will be used as the title of the note to be created.
If there's no H1 header in the "content" field, yet a title is assigned in YAML metadata section (---\ntitle: abc\n---), then it will be the title of the note.
If the "content" field is not included, then either look for the "title" field or create the note as "Untitled" when it is absent.

:bulb: Notes on the permission field

When creating or updating the note's permission, both readPermission and writePermission field must be provided at the same time.
writePermission must be stricter than readPermission field. For example, a signed_in user readable note, you can set owner or signed_in writable permission, but you can't set guest writable permission for that note.

Update a note

PATCH /notes/:noteId
URL Params:
- noteId: string
Data Params:

body (optional) [application/json]

  {
    "content": "# Updated personal note",
    "readPermission": "signed_in",
    "writePermission": "owner",
    "permalink": "note-permalink"
  }

field	type	values
content	string
readPermission	string	`owner`, `signed_in`, `guest`
writePermission	string	`owner`, `signed_in`, `guest`
permalink	string

Success Response
- code: 202
- body: Accepted

Delete a note

DELETE /notes/:noteId
URL Params:
- noteId: string
Success Response
- code: 204

Get a history of read notes

GET /history

Success Response

code: 200

body:

      [
        {
          "id": "0jJVr2b3T2eSkBnMib-inA",
          "title": "Team notes",
          "tags": [],
          "createdAt": 1644371283239,
          "publishType": "view",
          "publishedAt": 1644371283239,
          "permalink": null,
          "shortId": "SysUa9xJc",
          "lastChangedAt": 1644461300662,
          "lastChangeUser": {
              "name": "James",
              "photo": "https://avatars.githubusercontent.com/u/26138990?s=96",
              "biography": null,
              "userPath": "AMQ36J15QgCZf46ThEFadg"
          },
          "userPath": null,
          "teamPath": "CAT",
          "readPermission": "guest",
          "writePermission": "signed_in",
          "publishLink": "https://hackmd.io/@username/permalink"                  
      },
      {
          "id": "QpS6V2TCSbeKmNIS1LOrNQ",
          "title": "Untitled",
          "tags": null,
          "createdAt": 1644393142405,
          "publishType": "view",
          "publishedAt": null,
          "permalink": null,
          "shortId": "HJAnGgZyq",
          "lastChangedAt": 1644393142403,
          "lastChangeUser": {
              "name": "Ming-Hsiu Tsai",
              "photo": "https://avatars.githubusercontent.com/u/26138990?s=96",
              "biography": null,
              "userPath": "AMQ36J15QgCZf46ThEFadg"
          },
          "userPath": "AMQ36J15QgCZf46ThEFadg",
          "teamPath": null,
          "readPermission": "owner",
          "writePermission": "owner",
          "publishLink": "https://hackmd.io/@username/permalink"                
        }
      ]

Upload attachments to a note (To be announced)

POST /notes/:noteId/upload
file: xxx

User Notes API

Get a list of notes in the user's workspace

Get a note

Create a note

:bulb: Notes on the Title field

:bulb: Notes on the permission field

Update a note

Delete a note

Get a history of read notes

Upload attachments to a note (To be announced)

Read more

Policy

Getting started

Discord bot with HackMD

Team Notes API

:bulb: Notes on the `Title` field