Headless API Documentation

1. Install

With Go installed, install the CLI from its public repository:

go install github.com/jonbaldie/bookbeam-cli@latest

Go installs the binary as bookbeam-cli in your Go bin directory. Rename it to bookbeam (or bookbeam.exe on Windows) and add that directory to your PATH to use the commands below.

2. Sign in

Start browser login, approve the displayed device code in BookBeam, then check your identity. The CLI saves the resulting token for subsequent commands.

bookbeam auth login
bookbeam whoami

3. Work with your books

Create a project, then replace 123 with its ID from the project list. Use the path to your own EPUB, MOBI, or PDF when uploading.

bookbeam projects create --title "My Book" --json
bookbeam projects list --json
bookbeam files upload 123 ./book.epub --json
bookbeam files list 123 --json
bookbeam links create 123 --title "Reader sample" --consent "Join my newsletter" --json
bookbeam links list 123 --json
bookbeam downloaders export 123 --output ./subscribers.csv

These commands call the project, file, signup link, and downloader endpoints below. The export command writes a CSV file to your chosen path.

4. Automate API requests

For scripts or CI, supply an existing personal access token through BOOKBEAM_TOKEN. Use your CI secret store for the value. The following shell examples use --json to return API responses for tools such as jq.

export BOOKBEAM_TOKEN="your-api-token"
bookbeam projects list --json
bookbeam metrics --json
bookbeam billing status --json

# Target a local BookBeam server with a token issued by that server
bookbeam --host http://localhost:8000 projects list --json

The default host is https://bookbeam.app. Override it with --host or BOOKBEAM_HOST, using the origin without /api/v1. Run bookbeam --help or bookbeam projects --help for more commands and flags.

Generate a new Bearer token.

curl -X POST https://bookbeam.app/api/v1/tokens \
  -H "Accept: application/json" \
  -H "Content-Type: application/json" \
  -d '{
    "email": "author@example.com",
    "password": "your-password",
    "name": "CLI Integration Token"
  }'

List active tokens for your account.

curl -X GET https://bookbeam.app/api/v1/tokens \
  -H "Authorization: Bearer $BOOKBEAM_TOKEN" \
  -H "Accept: application/json"

Revoke an active token by ID.

List all book projects for your active team.

curl -X GET https://bookbeam.app/api/v1/projects \
  -H "Authorization: Bearer $BOOKBEAM_TOKEN" \
  -H "Accept: application/json"

Create a new book project (supports multipart for cover image).

curl -X POST https://bookbeam.app/api/v1/projects \
  -H "Authorization: Bearer $BOOKBEAM_TOKEN" \
  -F "title=The Quantum Detective" \
  -F "description=Detective Jack Hunter investigates across realities." \
  -F "cover_image=@/path/to/cover.jpg"

Upload a new manuscript file (multipart/form-data).

curl -X POST https://bookbeam.app/api/v1/projects/1/files \
  -H "Authorization: Bearer $BOOKBEAM_TOKEN" \
  -F "file=@/path/to/novel.epub" \
  -F "format=epub"

Create a new giveaway signup link.

curl -X POST https://bookbeam.app/api/v1/projects/1/links \
  -H "Authorization: Bearer $BOOKBEAM_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Newsletter Giveaway",
    "opt_in_text": "Join my VIP reader newsletter for free bonus chapters"
  }'

Fetch public landing metadata (title, author, formats) for a campaign link.

curl -X GET https://bookbeam.app/api/v1/readers/links/sample-slug \
  -H "Accept: application/json"

Submit reader email to receive magic confirmation link.

curl -X POST https://bookbeam.app/api/v1/readers/links/sample-slug/signup \
  -H "Content-Type: application/json" \
  -d '{
    "email": "reader@example.com"
  }'