API

Collections

List all collections
Create new collection
Retrieve collection details
Update collection details
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": [
    {
      "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"
    }
  ],
  "error": false,
  "errcode": 0,
  "errmsg": null,
  "status": 200,
  "count": 2,
  "previous": null,
  "next": "https://histre.com/api/v1/collections/?page=2"
}

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": {
    "windowId001": [
      {"url": "https://www.google.com/", "title": "Google"},
      {"url": "https://news.ycombinator.com/", "title": "Hacker News"}
    ]
  },
  "friendly_time": "Mar 2, 2021 07:58pm"
}

Request Headers

Content-Type: application/json
Authorization: Bearer

Response

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

{"url": "https://histre.com/collections/h6yyd5g9/tabs-at-mar-2-2021-0758pm/"}

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