---
title: User Notes API
description:
tags: developer portal
---

{%hackmd bXqUSiOGTLuFjPgSJ74wxQ %}

# User Notes API

[toc]

## 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"                    
                }

:::info
### :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.

1. If there's a H1 header in the "content" field, then it will be used as the title of the note to be created.
2. 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.
3. If the "content" field is not included, then either look for the "title" field or create the note as "Untitled" when it is absent.
:::

:::info
### :bulb: Notes on the permission field

1. When creating or updating the note's permission, both `readPermission` and `writePermission` field must be provided at the same time.
2. `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`