bookstack-api

A Go client library for the BookStack REST API.

Full API reference: https://demo.bookstackapp.com/api/docs

Installation

go get github.com/dimahum/bookstack-api

Requires Go 1.21 or later.

Authentication

BookStack uses token-based authentication. Generate a token in your BookStack instance under Profile → API Tokens, then pass the token ID and secret to NewClient.

Quick start

import bookstack "github.com/dimahum/bookstack-api"

client := bookstack.NewClient(
    "https://your-bookstack.example.com",
    "your-token-id",
    "your-token-secret",
)

Usage

Books

// List books (first 10, newest first)
resp, err := client.ListBooks(&bookstack.ListOptions{
    Count: 10,
    Sort:  "-created_at",
})

// Create a book
book, err := client.CreateBook(&bookstack.CreateBookRequest{
    Name:        "My Book",
    Description: "A great book",
    Tags: []bookstack.Tag{{Name: "team", Value: "engineering"}},
})

// Get a book by ID
book, err := client.GetBook(42)

// Update a book
book, err := client.UpdateBook(42, &bookstack.UpdateBookRequest{
    Name: "My Book (revised)",
})

// Delete a book
err := client.DeleteBook(42)

Chapters

chapter, err := client.CreateChapter(&bookstack.CreateChapterRequest{
    BookID: 42,
    Name:   "Introduction",
})

chapter, err := client.GetChapter(chapter.ID)

_, err = client.UpdateChapter(chapter.ID, &bookstack.UpdateChapterRequest{
    Name: "Getting Started",
})

err = client.DeleteChapter(chapter.ID)

Pages

// Create a page with HTML content (inside a chapter)
page, err := client.CreatePage(&bookstack.CreatePageRequest{
    ChapterID: 10,
    Name:      "Hello World",
    HTML:      "<h1>Hello</h1><p>World</p>",
})

// Or create a page with Markdown content directly in a book
page, err := client.CreatePage(&bookstack.CreatePageRequest{
    BookID:   42,
    Name:     "Hello Markdown",
    Markdown: "# Hello\n\nWorld",
})

page, err := client.GetPage(page.ID)

_, err = client.UpdatePage(page.ID, &bookstack.UpdatePageRequest{
    Name: "Hello World (v2)",
})

err = client.DeletePage(page.ID)

Bookshelves

shelf, err := client.CreateShelf(&bookstack.CreateShelfRequest{
    Name:  "Engineering",
    Books: []int{42, 43}, // book IDs to include
})

shelf, err := client.GetShelf(shelf.ID)

_, err = client.UpdateShelf(shelf.ID, &bookstack.UpdateShelfRequest{
    Name: "Engineering (archived)",
})

err = client.DeleteShelf(shelf.ID)

Search

results, err := client.Search(&bookstack.SearchOptions{
    Query: "kubernetes deployment",
    Page:  1,
    Count: 20,
})

for _, item := range results.Data {
    fmt.Printf("[%s] %s – %s\n", item.Type, item.Name, item.URL)
}

BookStack's advanced search syntax is supported in the Query field, for example:

Syntax	Meaning
[is:page]	Only return pages
[created_by:me]	Content created by the current user
{exact phrase}	Exact phrase match
tag:version=2	Items with a specific tag value

Attachments

// Create a link attachment on a page
att, err := client.CreateAttachment(&bookstack.CreateAttachmentRequest{
    Name:       "Official Docs",
    UploadedTo: page.ID,
    Link:       "https://demo.bookstackapp.com/api/docs",
})

att, err := client.GetAttachment(att.ID)

_, err = client.UpdateAttachment(att.ID, &bookstack.UpdateAttachmentRequest{
    Name: "API Docs",
})

err = client.DeleteAttachment(att.ID)

Users

users, err := client.ListUsers(nil)

user, err := client.CreateUser(&bookstack.CreateUserRequest{
    Name:     "Jane Doe",
    Email:    "jane@example.com",
    Password: "s3cur3p@ss",
    Roles:    []int{2}, // role IDs
})

user, err := client.GetUser(user.ID)

_, err = client.UpdateUser(user.ID, &bookstack.UpdateUserRequest{
    Name: "Jane Smith",
})

// Delete user and migrate their content ownership to user ID 1
err = client.DeleteUser(user.ID, 1)

Pagination & filtering

Every list method accepts a *ListOptions parameter:

opts := &bookstack.ListOptions{
    Count:  50,            // items per page (max 500)
    Offset: 50,            // skip first 50 results
    Sort:   "-updated_at", // sort field; prefix "-" for descending
    Filter: map[string]string{
        "name:like": "%go%",          // name contains "go"
        "created_by": "5",            // created by user 5
    },
}
resp, err := client.ListBooks(opts)
fmt.Printf("%d / %d books\n", len(resp.Data), resp.Total)

Running the example program

export BOOKSTACK_URL=https://your-bookstack.example.com
export BOOKSTACK_TOKEN_ID=your-token-id
export BOOKSTACK_TOKEN_SECRET=your-token-secret
go run ./examples/bookstack/

Running the tests

go test ./...

License

MIT