owned this note
owned this note
Published
Linked with GitHub
---
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:
```json
[
{
"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"
}
]
```
## Get a note
- `GET /notes/:noteId`
- URL Params:
- nodeId: string
- Success Response
- code: `200`
- body:
```json
{
"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"
}
```
## Create a note
- `POST /notes`
- Data Params
- body (optional) [application/json]
```script=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` |
- Success Response
- code: `201`
- body:
```json
{
"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"
}
```
:::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.
:::
## Update a note
- `PATCH /notes/:noteId`
- URL Params:
- nodeId: string
- Data Params:
- body (optional) [application/json]
```script=json
{
"content": "# Updated personal note",
"readPermission": "signed_in"
}
```
- Success Response
- code: 202
- body: Accepted
## Delete a note
- `DELETE /notes/:noteId`
- URL Params:
- nodeId: string
- Success Response
- code: 204
## Get a history of read notes
- `GET /history`
- Success Response
- code: 200
- body:
```json
[
{
"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"
},
{
"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"
}
]
```
## Upload attachments to a note (To be announced)
- `POST /notes/:noteId/upload`
- `file: xxx`
