Grimoire Integration API (0.2.3)

Download OpenAPI specification:Download

To authorize, pass your user's credentials in a POST request to /api/auth to receive the token.

Then use it as the Authorization header value, prefixed with Bearer (separated by space).

Example request with proper header:

curl --request GET \ 
     --url http://[GRIMOIRE_URL]/api/bookmarks \ 
     --header 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c'

Authenticate user

Authenticate with your user credentials.

Authorizations:

basicAuth

Request Body schema: application/json

User credentials

username	string User's username or email
password	string User's password

Responses

Request samples

Payload

Content type

application/json

{"username": "string",
"password": "string"
}

Response samples

200
400
500

Content type

application/json

{"success": true,
"token": "string"
}

Create a new quick bookmark

Create a new quick bookmark. This endpoint is intended to be used by bookmarklet or as a fallback for browser extension.

Authorizations:

basicAuth

query Parameters

url

required

string

The base64 encoded URL to bookmark.

Responses

Response samples

201
400
401
500

Content type

application/json

{"bookmark": {"id": "string",
"url": "string",
"title": "string",
"icon": "string",
"icon_url": "string",
"main_image": "string",
"main_image_url": "string",
"category": {"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
},
"tags": [{"id": "string",
"name": "string",
"slug": "string",
"owner": "string",
"created": "string",
"updated": "string"
}
],
"note": "string",
"author": "string",
"description": "string",
"domain": "string",
"content_type": "string",
"content_text": "string",
"content_html": "string",
"created": "string",
"updated": "string",
"importance": 0,
"flagged": "string",
"opened_last": "string",
"opened_times": 0,
"read": "string",
"owner": "string",
"screenshot": "string"
}
}

Retrieve a list of bookmarks

Authorizations:

basicAuth

query Parameters

ids	string Examples: ids=id1,id2,id3 Comma separated bookmark IDs to retrieve

Responses

Response samples

200
401
500

Content type

application/json

{"bookmarks": [{"id": "string",
"url": "string",
"title": "string",
"icon": "string",
"icon_url": "string",
"main_image": "string",
"main_image_url": "string",
"category": {"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
},
"tags": [{"id": "string",
"name": "string",
"slug": "string",
"owner": "string",
"created": "string",
"updated": "string"
}
],
"note": "string",
"author": "string",
"description": "string",
"domain": "string",
"content_type": "string",
"content_text": "string",
"content_html": "string",
"created": "string",
"updated": "string",
"importance": 0,
"flagged": "string",
"opened_last": "string",
"opened_times": 0,
"read": "string",
"owner": "string",
"screenshot": "string"
}
]
}

Create a new bookmark

Create a new bookmark with the given data.

Authorizations:

basicAuth

Request Body schema: application/json

Bookmark details

url	string Bookmark URL
title	string Bookmark title
description	string Bookmark description
author	string Bookmark author
content_text	string Bookmark content text
content_html	string Bookmark content HTML
content_type	string Bookmark content type
content_published_date	string Bookmark content published date
note	string Bookmark note
icon_url	string Bookmark icon URL
icon	string Bookmark icon, mainly used by web extension (data URL)
main_image_url	string Bookmark main image URL
importance	integer Bookmark importance
flagged	boolean Bookmark flagged
category	string Bookmark category ID
tags	Array of strings (TagCreateDto)
screenshot	string Screenshot of bookmarked page, mainly used by web extension (data URL, max 300kb)

Responses

Request samples

Payload

Content type

application/json

{"url": "string",
"title": "string",
"description": "string",
"author": "string",
"content_text": "string",
"content_html": "string",
"content_type": "string",
"content_published_date": "string",
"note": "string",
"icon_url": "string",
"icon": "string",
"main_image_url": "string",
"importance": 0,
"flagged": true,
"category": "string",
"tags": ["string"
],
"screenshot": "string"
}

Response samples

201
400
401
500

Content type

application/json

{"bookmark": {"id": "string",
"url": "string",
"title": "string",
"icon": "string",
"icon_url": "string",
"main_image": "string",
"main_image_url": "string",
"category": {"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
},
"tags": [{"id": "string",
"name": "string",
"slug": "string",
"owner": "string",
"created": "string",
"updated": "string"
}
],
"note": "string",
"author": "string",
"description": "string",
"domain": "string",
"content_type": "string",
"content_text": "string",
"content_html": "string",
"created": "string",
"updated": "string",
"importance": 0,
"flagged": "string",
"opened_last": "string",
"opened_times": 0,
"read": "string",
"owner": "string",
"screenshot": "string"
}
}

Update a bookmark

Update a bookmark with the given data.

Authorizations:

basicAuth

Request Body schema: application/json

Bookmark details

id	string Bookmark ID
url	string Bookmark URL
title	string Bookmark title
description	string Bookmark description
author	string Bookmark author
content_text	string Bookmark content text
content_html	string Bookmark content HTML
content_type	string Bookmark content type
content_published_date	string Bookmark content published date
note	string Bookmark note
icon_url	string Bookmark icon URL
main_image_url	string Bookmark main image URL
importance	integer Bookmark importance
flagged	boolean Bookmark flagged
category	string Bookmark category ID
tags	Array of strings (TagCreateDto)
screenshot	string Screenshot of bookmarked page, mainly used by web extension (data URL, max 300kb)

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"url": "string",
"title": "string",
"description": "string",
"author": "string",
"content_text": "string",
"content_html": "string",
"content_type": "string",
"content_published_date": "string",
"note": "string",
"icon_url": "string",
"main_image_url": "string",
"importance": 0,
"flagged": true,
"category": "string",
"tags": ["string"
],
"screenshot": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"bookmark": {"id": "string",
"url": "string",
"title": "string",
"icon": "string",
"icon_url": "string",
"main_image": "string",
"main_image_url": "string",
"category": {"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
},
"tags": [{"id": "string",
"name": "string",
"slug": "string",
"owner": "string",
"created": "string",
"updated": "string"
}
],
"note": "string",
"author": "string",
"description": "string",
"domain": "string",
"content_type": "string",
"content_text": "string",
"content_html": "string",
"created": "string",
"updated": "string",
"importance": 0,
"flagged": "string",
"opened_last": "string",
"opened_times": 0,
"read": "string",
"owner": "string",
"screenshot": "string"
}
}

Delete a bookmark

Delete a bookmark with the given ID.

Authorizations:

basicAuth

query Parameters

id

required

string

The bookmark ID to delete.

Responses

Response samples

200
400
401
404
500

Content type

application/json

{"success": true
}

Retrieve all User categories

Authorizations:

basicAuth

Responses

Response samples

200
401
500

Content type

application/json

{"categories": [{"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
}
]
}

Create a new category

Create a new category with the given data.

Authorizations:

basicAuth

Request Body schema: application/json

Category details

name	string Category name
description	string Category description
color	string Category color as hex value
icon	string Category icon
public	boolean Category public
archived	boolean Category archived
parent	string Category parent ID

Responses

Request samples

Payload

Content type

application/json

{"name": "string",
"description": "string",
"color": "string",
"icon": "string",
"public": true,
"archived": true,
"parent": "string"
}

Response samples

201
400
401
403
500

Content type

application/json

{"category": {"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
}
}

Update a category

Update a category with the given data.

Authorizations:

basicAuth

Request Body schema: application/json

Category details

id	string Category ID
name	string Category name
description	string Category description
color	string Category color as hex value
icon	string Category icon
public	boolean Category public
archived	boolean Category archived
parent	string Category parent ID

Responses

Request samples

Payload

Content type

application/json

{"id": "string",
"name": "string",
"description": "string",
"color": "string",
"icon": "string",
"public": true,
"archived": true,
"parent": "string"
}

Response samples

200
400
401
404
500

Content type

application/json

{"category": {"id": "string",
"name": "string",
"slug": "string",
"initial": true,
"description": "string",
"color": "string",
"icon": "string",
"owner": "string",
"created": "string",
"updated": "string",
"public": "string",
"archived": "string",
"parent": "string"
}
}

Retrieve all User tags

Authorizations:

basicAuth

Responses

Response samples

200
401
500

Content type

application/json

{"tags": [{"id": "string",
"name": "string",
"slug": "string",
"owner": "string",
"created": "string",
"updated": "string"
}
]
}

Create a new tag

Create a new tag with the given data.

Authorizations:

basicAuth

Request Body schema: application/json

Tag details

string (TagCreateDto)

Bookmark tag

Responses

Request samples

Payload

Content type

application/json

"string"

Response samples

201
400
401
403
500

Content type

application/json

{"tag": {"id": "string",
"name": "string",
"slug": "string",
"owner": "string",
"created": "string",
"updated": "string"
}
}