shiori/docs/API.md

This is a brief explanation of Shiori's API. For more examples you can import this collection in Postman.

• Auth
  • Log in
  • Log out
• Bookmarks
  • Get bookmarks
  • Add bookmark
  • Edit bookmark
  • Delete bookmark
• Tags
  • Get tags
  • Rename tag
• Accounts
  • List accounts
  • Create account
  • Edit account
  • Delete accounts

Auth

Log in

Most actions require a session id. For that, you'll need to log in using your username and password.

Request info	Value
Endpoint	/api/login
Method	POST

Body:

{
	"username": "shiori",
	"password": "gopher",
	"remember": 1,
	"owner": true
}

It will return your session ID in a JSON:

{
    "session": "YOUR_SESSION_ID",
    "account": {
        "id": 1,
        "username": "shiori",
        "owner": true
    }
}

Log out

Log out of a session ID.

Request info	Value
Endpoint	/api/logout
Method	POST
X-Session-Id Header	sessionId

Bookmarks

Get bookmarks

Gets the last 30 bookmarks (last page).

Request info	Value
Endpoint	/api/bookmarks
Method	GET
X-Session-Id Header	sessionId

Returns:

{
    "bookmarks": [
        {
            "id": 825,
            "url": "https://interesting_cool_article.com",
            "title": "Cool Interesting Article",
            "excerpt": "An interesting and cool article indeed!",
            "author": "",
            "public": 0,
            "modified": "2020-12-06 00:00:00",
            "imageURL": "",
            "hasContent": true,
            "hasArchive": true,
            "tags": [
                {
                    "id": 7,
                    "name": "TAG"
                }
            ],
            "createArchive": false
        },
    ],
    "maxPage": 19,
    "page": 1
}

Add bookmark

Add a bookmark. For some reason, Shiori ignores the provided title and excerpt, and instead fetches them automatically. Note the tag format, a regular JSON list will result in an error.

Request info	Value
Endpoint	/api/bookmarks
Method	POST
X-Session-Id Header	sessionId

Body:

{
	"url": "https://interesting_cool_article.com",
	"createArchive": true,
	"public": 1,
	"tags": [{"name": "Interesting"}, {"name": "Cool"}],
	"title": "Cool Interesting Article",
	"excerpt": "An interesting and cool article indeed!"
}

Returns:

{
    "id": 827,
    "url": "https://interesting_cool_article.com",
    "title": "TITLE",
    "excerpt": "EXCERPT",
    "author": "AUTHOR",
    "public": 1,
    "modified": "DATE",
    "html": "HTML",
    "imageURL": "/bookmark/827/thumb",
    "hasContent": false,
    "hasArchive": true,
    "tags": [
        {
             "name": "Interesting"
        },
        {
             "name": "Cool"
        }
    ],
    "createArchive": true
}

Edit bookmark

Modifies a bookmark, by ID.

Request info	Value
Endpoint	/api/bookmarks
Method	PUT
X-Session-Id Header	sessionId

Body:

{
    "id": 3,
    "url": "https://interesting_cool_article.com",
    "title": "Cool Interesting Article",
    "excerpt": "An interesting and cool article indeed!",
    "author": "AUTHOR",
    "public": 1,
    "modified": "2019-09-22 00:00:00",
    "imageURL": "/bookmark/3/thumb",
    "hasContent": false,
    "hasArchive": false,
    "tags": [],
    "createArchive": false
}

After providing the ID, provide the modified fields. The syntax is the same as adding.

Delete bookmark

Deletes a list of bookmarks, by their IDs.

Request info	Value
Endpoint	/api/bookmarks
Method	DEL
X-Session-Id Header	sessionId

Body:

[1, 2, 3]

Tags

Get tags

Gets the list of tags, their IDs and the number of entries that have those tags.

Request info	Value
Endpoint	/api/tags
Method	GET
X-Session-Id Header	sessionId

Returns:

[
    {
        "id": 1,
        "name": "Cool",
        "nBookmarks": 1
    },
    {
        "id": 2,
        "name": "Interesting",
        "nBookmarks": 1
    }

Rename tag

Renames a tag, provided its ID.

Request info	Value
Endpoint	/api/tags
Method	PUT
X-Session-Id Header	sessionId

Body:

{
    "id": 1,
    "name": "TAG_NEW_NAME"
}

Accounts

List accounts

Gets the list of all user accounts, their IDs, and whether or not they are owners.

Request info	Value
Endpoint	/api/accounts
Method	GET
X-Session-Id Header	sessionId

Returns:

[
    {
        "id": 1,
        "username": "shiori",
        "owner": true
    }
]

Create account

Creates a new user.

Request info	Value
Endpoint	/api/accounts
Method	POST
X-Session-Id Header	sessionId
Body:

{
	"username": "shiori2",
	"password": "gopher",
	"owner": false
}

Edit account

Changes an account's password or owner status.

Request info	Value
Endpoint	/api/accounts
Method	PUT
X-Session-Id Header	sessionId
Body:

{
	"username": "shiori",
	"oldPassword": "gopher",
	"newPassword": "gopher",
	"owner": true
}

Delete accounts

Deletes a list of users.

Request info	Value
Endpoint	/api/accounts
Method	DEL
X-Session-Id Header	sessionId

Body:

["shiori", "shiori2"]