API

Collections

Sections

List All Collections
Create a New Collection
Retrieve Collection Details
Update Collection Details
Delete a Collection
Save Browser Tabs / Windows as Collections
Follow a Collection
Unfollow a Collection
Add Notes to Collections
Remove Note from Collections

List All Collections

Description

Retrieves all collections for current user

URL

/api/v1/collections/

HTTP Method

GET

Path Parameters

None

Query Parameters

Note: This endpoint returns a paginated response, please see Pagination section under Overview of this API documentation.

Data Parameters

None

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 200
Content-Type: application/json
Schema/Example:

{
  "data": {
    "collections": [
      {
        "book_id": "hbjdifc5",
        "title": "Tabs at Sep 1, 2021 08:14pm",
        "description": "2 tabs from bloomberg.com, ycombinator.com",
        "slug": "tabs-at-sep-1-2021-0814pm",
        "created": "2021-09-01T12:14:38.526573Z",
        "modified": "2021-09-01T12:14:38.526595Z"
      },
      {
        "book_id": "5rj14xek",
        "title": "Vacation Ideas",
        "description": "Some links to share with my friends about our summer vacation plans",
        "slug": "vacation-2021",
        "created": "2021-09-01T12:14:02.485012Z",
        "modified": "2021-09-01T12:14:02.485033Z"
      }
    ],
    "count": 2,
    "previous": null,
    "next": "https://histre.com/api/v1/collections/?page=2"
  ],
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Note: This endpoint returns a paginated response, please see Pagination section under Overview of this API documentation.

Create a New Collection

Description

Creates a new collection for current user

URL

/api/v1/collections/

HTTP Method

POST

Path Parameters

None

Query Parameters

None

Data Parameters

title (String): the collection's title (required)
description (String): the collection's description (optional)

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 201
Content-Type: application/json
Schema/Example:

{
  "data": {
    "book_id": "7w84if4b",
    "title": "Collection created from API",
    "description": "Created from calling API endpoints",
    "slug": "collection-created-from-api"
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 201
}

Retrieve Collection Details

Description

Fetches details of collection with given ID for current user

URL

/api/v1/collections/{book_id}/

HTTP Method

GET

Path Parameters

book_id (String): the collection's ID (required)

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": {
    "book_id": "i1zpxqtz",
    "title": "First Public Collection of user",
    "description": "Public collection automatically created for user.",
    "slug": "first-public-collection-of-user",
    "created": "2021-08-28T02:29:25.510101Z",
    "modified": "2021-08-28T02:29:25.510122Z"
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Update Collection Details

Description

Updates some details of a collection with given ID

URL

/api/v1/collections/{book_id}/

HTTP Method

PATCH

Path Parameters

book_id (String): the collection's ID (required)

Query Parameters

None

Data Parameters

One or both of the following should be provided in the request body: - title (String): the new title of the collection - description (String): the new description of the collection

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 200
Content-Type: application/json
Schema/Example:

{
  "data": {
    "book_id": "7w84if4b",
    "title": "Updated by API endpoint",
    "description": "Description updated using API endpoint",
    "slug": "updated-by-api-endpoint"
  },
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200
}

Delete a Collection

Description

Deletes a collection with the given ID

URL

/api/v1/collections/{book_id}/

HTTP Method

DELETE

Path Parameters

book_id (String): the collection's ID (required)

Query Parameters

None

Data Parameters

None

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 204 no content

Save Browser Tabs / Windows as Collections

Description

Used by browser extension to save all open browser tabs or windows as collections

URL

/api/v1/collections/save_tabs_or_windows/

HTTP Method

POST

Path Parameters

None

Query Parameters

None

Data Parameters

See JSON schema/example below

{
  "items": {
    "831579573": [
      {
        "url": "https://news.ycombinator.com/",
        "title": "Hacker News",
        "tab_id": 831579574
      },
      {
        "url": "https://github.com/",
        "title": "GitHub: Let\u2019s build from here \u00b7 GitHub",
        "tab_id": 831579630
      }
    ]
  },
  "friendly_time": "Sep 22, 2023 04:48pm",
  "title": "Tabs at Sep 22, 2023 04:48pm"
}

Notes: - The top-level title field is optional and represents the user-provided title of the collection (or collections) to contain the saved tabs. - The field "831579573" under "items" is the window ID containing the tabs to be saved. A request can have multiple windows. Each window is saved in its own collection. - The tab_id field in each tab detail object is optional.

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 201
Content-Type: application/json
Schema/Example:

{
  "url": "https://histre.com/collections/wzv4z74j/tabs-at-sep-22-2023-0448pm/",
  "saved_tabs": [
    {
      "item_id": "8qwp0oat",
      "tab_id": 831579630,
      "note_modified": 1616143854
    },
    {
      "item_id": "0gwkfvfs",
      "tab_id": 831579574,
      "note_modified": 1689821984
    }
  ]
}

Notes: - If the saved tabs are all from a single browser window, the "url" field is the link to the collection containing the saved items. - If the saved tabs are from multiple browser windows, the "url" field is the link to the saved tabs collection list page. - The "note_ids" field is an array of objects that contain the note ID, tab ID, and other note details of the tabs that were successfully saved. This can be an empty array too.

Follow a Collection

Description

Lets the current user follow a public collection of another user

URL

/api/v1/collections/{book_id}/follow/

HTTP Method

POST

Path Parameters

book_id (String): the collection's ID (required)

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": {"total_followers": 1},
  "error": false,
  "errcode":0,
  "errmsg":null,
  "status":200
}

Unfollow a Collection

Description

Lets the current user unfollow a collection of another user

URL

/api/v1/collections/{book_id}/unfollow/

HTTP Method

POST

Path Parameters

book_id (String): the collection's ID (required)

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": {"total_followers": 1},
  "error": false,
  "errcode":0,
  "errmsg":null,
  "status":200
}

Add Notes to Collections

Description

Adds one or more notes to one or more collections

URL

/api/v1/collections/add_notes/

HTTP Method

POST

Path Parameters

None

Query Parameters

None

Data Parameters

url_item_item_ids (Array): one or more URL item IDs (required)
book_ids (Array): one or more collection IDs (required)

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 204 no content

Remove Note from Collections

Description

Removes note (URL item) with given ID from one or more collections with given IDs

URL

/api/v1/collections/remove_note/

HTTP Method

POST

Path Parameters

None

Query Parameters

None

Data Parameters

url_item_item_id (String): ID of URL item to remove (required)
book_ids (Array): one or more collection IDs from which the note will be removed (required, must have at least one ID)

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

Status Code: 204 no content