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