API

Notes and Tags

Sections

Create / Update Notes

Description

Creates or updates one or more notes for the current user

URL

/api/v1/note/

HTTP Method

POST

Path Parameters

None

Query Parameters

  • append (String): Set this to the following values (optional):
    • always - This enables append without checking for duplicate notes.
    • dedupe - This enables appending notes but prevents duplicate text from being appended.
    • true - The same as always (kept for backward compatibility).
  • attrpriority (string): Determines how extracted or user-supplied attributes are handled in note append mode. Set this to any of the following (optional):
    • old - Values of existing fields are not updated.
    • new - Values of existing fields are replaced by newer values. This is the default behavior if this query parameter is not set.
  • notify (String): set this to false to disable notifying other users who have access to the collections the notes are added to (optional). Default is true.
# Example: this will enable append mode
/api/v1/note/?append=true

Data Parameters

See JSON schema/example below

[
  {
    "url": String,
    "title": String,
    "note": String,
    "book_ids": Array,
    "attrs": Object
  },
  ...
]

Notes: - url, book_ids, and attrs are optional. - If attrs is passed, it must be a non-empty Object containing key-value elements.

Request Headers

  • Content-Type: application/json
  • Authorization: Bearer

Response

  • Status Code: 200
  • Content-Type: application/json
  • Schema/Example:
{
  "data": {
    "item_id": "8wa15ojc"
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Retrieve a Note

Description

Retreives the note that a user has added for a given URL

URL

/api/v1/note/

HTTP Method

GET

Path Parameters

None

Query Parameters

  • url (String): the URL associated with the note to be retrieved (required)

Data Parameters

None

Request Headers

  • Content-Type: application/json
  • Authorization: Bearer

Response

  • Status Code: 200
  • Content-Type: application/json
  • Schema/Example:
{
  "data": {
    "item_id": "d78gn65y",
    "note": "Note text 1",
    "url": "http://www.example.com/page1",
    "title": "Title 1",
    "tags": [
      "tag1" ,
      "tag2"
    ],
    "highlights": [
      "Important content 1",
      "Important content 2"
    ],
    "access": "private",
    "attrs": {
      "field1": "value1",
      "field2": "value2",
      "field3": "value3"
    },
    "created": "2021-02-27T03:06:33.804000Z",
    "modified": "2021-09-18T11:12:53.477872Z"
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Note: attrs can be an empty object {}.

Retrieve a List of Notes

Description

Retreives all notes of a user

URL

api/v1/note/

HTTP Method

GET

Path Parameters

None

Query Parameters

None (except for pagination parameters)

Data Parameters

None

Request Headers

  • Content-Type: application/json
  • Authorization: Bearer

Response

  • Status Code: 200
  • Content-Type: application/json
  • Schema/Example:
{
  "data": {
    "notes": [
      {
        "item_id": "d78gn65y",
        "note": "Note text 1",
        "url": "http://www.example.com/page1",
        "title": "Title 1",
        "tags": [
          "tag1" ,
          "tag2"
        ],
        "highlights": [
          "Important content 1",
          "Important content 2"
        ],
        "created": "2021-02-27T03:06:33.804000Z",
        "modified": "2021-09-18T11:12:53.477872Z"
      },
      {
        "item_id": "5a9u6839",
        "note": "",
        "url": null,
        "title": "Title 2",
        "tags": [],
        "highlights": [],
        "created": "2021-02-27T03:06:33.804000Z",
        "modified": "2021-09-18T11:12:53.477872Z"
      },
      // Rest of notes here...
    ],
    "count": 1251,
    "next": "https://histre.com/api/v1/note/?page=2",
    "previous": null
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Delete a Note

Description

Deletes a note permanently from current user's account

URL

/api/v1/note/

HTTP Method

DELETE

Path Parameters

None

Query Parameters

None

Data Parameters

Either of the following should be provided as a query parameter:

  • url (String): the URL associated with the note to delete
  • note_id (String): UUID of note to delete (*not to be confused with item_id)

Request Headers

  • Content-Type: application/json
  • Authorization: Bearer

Response

  • Status Code: 200
  • Content-Type: application/json
  • Schema/Example:
{
  "data": {},
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Retrieve Tags

Description

Retrieves all tags saved by current user

URL

/api/v1/tag/

HTTP Method

GET

Path Parameters

None

Query Parameters

None

Data Parameters

None

Request Headers

  • Content-Type: application/json
  • Authorization: Bearer

Response

  • Status Code: 200
  • Content-Type: application/json
  • Schema/Example::
{
  "data": {
    "tags": [
      {
        "value": "arithmetic"
      },
      {
        "value": "chemistry"
      },
      {
        "value": "constants"
      },
      ...
    ]
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}
Selection