API docs by Redocly

Hebban.nl API specification (2.5.0)

Download OpenAPI specification:

License: Proprietary

API documentation for the Hebban.nl project.

Changelog

See the changelog for the full API history.

Required Headers

Every API request must include:

  • Accept: application/json — Without this header, you'll receive 406 Not Acceptable.
  • X-API-TOKEN: <your-token> — All endpoints require a valid API token (see Authentication below).

Authentication

The API uses two authentication schemes:

  1. API Token (X-API-TOKEN header) — Required for all requests. Identifies your application.
  2. Bearer Token (JWT) — Required for user-specific endpoints (e.g., /me/*). Obtained via /auth/login or /auth/register.

Token lifecycle:

  • JWTs are long-lived tokens designed for mobile and web applications.
  • Tokens remain valid until explicitly revoked via /auth/logout.
  • Logout instantly invalidates all tokens for that user across all devices.
  • Use /auth/refresh to extend token lifetime if needed (rarely necessary).

Common pitfalls:

  • Forgetting the X-API-TOKEN header → 401 Unauthenticated
  • Missing Bearer token on /me/* endpoints → 401 Unauthenticated
  • Not calling /auth/logout when user signs out → Tokens remain valid

Request Correlation & Tracing

Track requests across logs and errors using the X-Request-Id header:

  • Optional: Send your own ULID (26 characters) to correlate requests.
  • Auto-generated: If omitted, the server generates one for you.
  • Validation: Invalid ULIDs return 400 Bad Request.
  • Response: Every response includes X-Request-Id in the header.
  • Errors: RFC 9457 error responses include the correlation ID in both the X-Request-Id header and the request_id field in the JSON body.

Error Responses (RFC 9457)

All errors follow the RFC 9457 Problem Details format with Content-Type: application/problem+json:

{
  "title": "Unauthenticated",
  "status": 401,
  "request_id": "01JCEXAMPLE123456789ABCDEF",
  "code": "auth.unauthenticated"
}

The code member is the stable, machine-readable identifier clients should switch on. title and detail are English framework defaults, sent to ease debugging. Do not show them to end users; map code to your own copy instead.

Every code the API can return is listed below. The code property of the Error schema is an enum of exactly this list, so a response carrying an undocumented code fails contract validation.

Status Code When
400 pagination.invalid_cursor The cursor query parameter could not be decoded
400 validation.invalid_request_id X-Request-Id was sent but is not a valid ULID
401 auth.unauthenticated Missing or invalid X-API-TOKEN header, or missing or invalid bearer token on a user endpoint
403 auth.forbidden Authenticated, but not allowed to perform this action
403 auth.email_not_verified The account's email address is not verified. Returned by write operations that contribute content: ratings, reading statuses, read entries, reviews, comments, likes, lists, adding or removing a book from a challenge, follows, campaign submissions. Login, every GET request, account set-up (profile, avatar, joining a challenge, setting a pledge), and account-lifecycle operations (logout, refresh, preferences, notifications, mutes, account deletion) stay available. Changing the email address with a code (/me/email/*) requires a verified address
403 auth.invalid_signature Signed URL carries an invalid or expired signature
404 http.not_found Route or resource does not exist
404 auth.user_not_found POST /auth/firebase/token only: the Firebase token is valid, but no account belongs to that identity and registering it would succeed — send the user to POST /auth/firebase/register. A token registration would refuse in turn (an address another account already holds, Firebase email/password sign-in, or no email address at all) answers 401 instead
406 http.not_acceptable Missing Accept: application/json header
409 auth.account_exists Email address was taken between code verification and registration completion, or between requesting and confirming an email change
409 campaign.closed Campaign has ended and no longer accepts submissions
409 challenge.join.conflict Already joined this challenge
409 challenge.read_only Challenge is read-only
409 rating.delete.conflict Rating cannot be deleted while a review exists
409 review.create.conflict A review for this work already exists
422 validation.failed Request failed validation; see errors for the fields
429 rate_limit.exceeded Rate limit exceeded; wait for Retry-After seconds
500 server.error Unexpected server error; report the request_id

On 422, each entry under errors carries its own code of the form validation.<rule>, named after the validation rule that failed (for example validation.email, validation.required, validation.max). Errors raised outside a validation rule carry validation.unknown. That per-field list is open and is not part of the enum above.

Rate Limiting

All API endpoints are rate limited. Limits are applied per consumer and are indicated via response headers:

  • X-RateLimit-Limit — Maximum requests allowed in the current window
  • X-RateLimit-Remaining — Requests remaining in the current window

Three tiers apply:

  • General — All API endpoints (default: 240 requests/minute)
  • Search — All /*/search endpoints have a stricter limit (default: 30 requests/minute)
  • Sync — /me/collections, /me/activity, /me/app-sync (default: 20 requests/minute)

When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header.

Pagination

List endpoints support pagination via query parameters:

  • page — Page number (default: 1)
  • per_page — Items per page (default: 15, max: 250)

Some endpoints use cursor-based pagination (e.g., /me/notifications) with a before timestamp parameter.

Idempotency

Some endpoints are idempotent and safe to retry:

  • DELETE operations return 204 No Content even if the resource was already deleted.
  • PUT operations (e.g., adding a work to a list) return 204 No Content if the work is already present.

This prevents errors when retrying failed requests or handling network issues.

Changing the email address

POST /me/email/start mails a one-time code to the new address (POST /me/email/resend-code sends a fresh one); POST /me/email/verify-code confirms it, after which the new address is on the account and verified. An account with a password (has_password in the profile) sends its current password with start. start and resend-code answer 202 whether or not the new address belongs to another account or is reserved (see below); such an address receives no mail, so tell a user who gets no code to check the address.

After a change the previous address may receive a notice with an undo link. POST /auth/email/revert takes the token from that link: it restores the previous address, signs the account out everywhere, removes its password and social sign-ins, and mails a password reset to the restored address. While the link is valid (72 hours by default) the previous address counts as in use everywhere, including for the account itself. email on PATCH /me is deprecated and will be removed once the site and app use the code flow.

Auth - Login

User login and authentication

Log in a user

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email>
password
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Auth - Register

User registration

Register a new user

Creates an account that still has to confirm its address. An address that is in use or reserved (see "Changing the email address" in the introduction) returns 422 on email.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
name
required
string
email
required
string <email>
password
required
string <password>
password_confirmation
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "email": "user@example.com",
  • "password": "pa$$word",
  • "password_confirmation": "pa$$word"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Start app registration (request an email verification code)

Begins the in-app registration flow by sending a one-time verification code to the email address. The response is identical whether the address is new or already registered (anti-enumeration); an already-registered address instead receives a "you already have an account" email with a password-reset link. A reserved address (see "Changing the email address" in the introduction) gets the same response and no mail. No account is created at this step.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Resend the registration verification code

Re-sends a fresh verification code, invalidating any previous one. The response is identical regardless of whether the address is already registered (anti-enumeration).

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Verify the registration code

Verifies the one-time code. On success returns a short-lived, single-use proof bound to the email, to be submitted at the completion step. The code is limited-use and locks out after too many incorrect attempts.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email> <= 255 characters
code
required
string

The one-time verification code sent to the email address.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "proof": "string",
  • "expires_at": "2030-01-01T00:00:00+00:00"
}

Validate registration fields (stateless)

Validates any subset of the registration fields against the exact rules applied at completion, for live per-field feedback. Stores nothing. A lone password is checked for strength only; send password_confirmation alongside it to also check that the two match.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
password
string <password>
password_confirmation
string <password>
name
string <= 255 characters
birthdate
string <date>

Responses

Request samples

Content type
application/json
{
  • "password": "pa$$word",
  • "password_confirmation": "pa$$word",
  • "name": "string",
  • "birthdate": "2019-08-24"
}

Response samples

Content type
application/json
{
  • "valid": true,
  • "fields": [
    ]
}

Complete app registration

Creates a complete, already-verified account in one step from the proof returned by verify-code. The email is taken from the proof, not the request body. Returns a JWT, like login; no verification-link email is sent. If the email was registered or reserved in the meantime (see "Changing the email address" in the introduction), returns 409.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
proof
required
string

The short-lived confirmation proof returned by verify-code. The email is derived from it.

password
required
string <password>
password_confirmation
required
string <password>
name
required
string <= 255 characters
birthdate
string <date>
terms
required
boolean

Acceptance of the terms and conditions. Must be true.

Value: true

Responses

Request samples

Content type
application/json
{
  • "proof": "string",
  • "password": "pa$$word",
  • "password_confirmation": "pa$$word",
  • "name": "string",
  • "birthdate": "2019-08-24",
  • "terms": true
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Auth - Password

Password reset and recovery

Send password reset email

Requests a password reset link for an email address.

This endpoint never reveals whether an account exists. A registered address, an unknown address, and an address that already requested a link moments ago all return the exact same 200 response. Only the submitted value is validated: a missing or syntactically invalid email still returns 422.

Consequences for clients:

  • Do not treat 200 as confirmation that an account was found.
  • Never show "no account with that email address" — that message would re-introduce the account enumeration this behaviour exists to prevent. Show a neutral "if this address is known to us, you'll receive an email".
  • A link is only actually sent for a registered address, and at most once per 60 seconds per address.

The endpoint is rate limited per email address, per IP, and by an overall ceiling; exceeding any of these returns 429.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "status": "We have emailed your password reset link."
}

Check if a password reset token is valid

Validates a password reset token without consuming it. Use this before showing the reset form to provide immediate feedback if the link has expired or is invalid.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email>
token
required
string

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "valid": true
}

Reset user password

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email>
token
required
string
password
required
string <password>
password_confirmation
required
string <password>

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "token": "string",
  • "password": "pa$$word",
  • "password_confirmation": "pa$$word"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Auth - Email

Email verification

Verify user email

Verifies a user's email address using a signed URL. No authentication required - the signed URL itself is proof of email ownership.

path Parameters
id
required
integer
hash
required
string
query Parameters
expires
required
integer

URL expiration timestamp

signature
required
string

Cryptographic signature for URL validation

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "message": "string"
}

Undo an email change from the notice sent to the previous address

Undoes an email change with the token from the undo notice; see "Changing the email address" in the introduction for what a revert does. No bearer token is needed, and one sent along is ignored. An invalid, expired or already used token returns 422 on token. If the previous address was taken by another account in the meantime, the response is 409 auth.account_exists and nothing changes. The endpoint has its own rate limit per client address instead of the shared per-application one.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
token
required
string

The revert token from the link in the notice sent to the previous address.

Responses

Request samples

Content type
application/json
{
  • "token": "string"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Resend email verification

Request a new email verification link. The X-API-TOKEN header is always required. email in the body is required unless the request carries a bearer token, in which case the token's user is used; when both are present, the body's email wins. The response is identical whether or not the address exists or is already verified, to prevent email enumeration. Rate limited per email address and per IP address.

Authorizations:
apiTokenAuth(apiTokenAuthbearerAuth)
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
optional
email
string <email> <= 255 characters

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "If your email is registered and unverified, a verification link has been sent."
}

Auth - Social

Social login (OAuth)

Log in with social provider (Apple, Google, or Firebase)

Validates a token from a social provider and returns a JWT.

  • apple / google: Direct token validation for web
  • firebase: Firebase ID token for mobile apps (supports Apple, Google, or email/password via Firebase)

A rejected firebase token separates its reasons. 404 with code auth.user_not_found means the token is valid, no account here belongs to that identity, and registering it would succeed — send the user on to POST /auth/firebase/register rather than show a login error. Everything else stays 401, including the cases registration would refuse in turn: a token that did not check out, an identity that matched an account it may not be linked to, an address another account already holds, Firebase email/password sign-in, and a token carrying no email address. Clients no longer have to verify the token themselves to tell these apart.

Authorizations:
apiTokenAuth
path Parameters
provider
required
string (SocialProvider)
Enum: "apple" "google" "firebase"

Social provider name

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
token
required
string

ID token from social provider (Apple or Google)

Responses

Request samples

Content type
application/json
{
  • "token": "eyJraWQiOiJXNldjT0tCIiwiYWxnIjoiUlMyNTYifQ..."
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Register with social provider

Register a new user using a social provider token.

Only social sign-up through Firebase is supported at the moment. Firebase email/password registration is not allowed.

The email is automatically verified since social providers verify emails.

The call is idempotent for the same Firebase identity: registering again with a token for an account that was already created this way returns that account with a fresh JWT (200) instead of an error, so a repeated or retried submit is harmless. 409 is reserved for a genuine conflict, where the address or provider id belongs to a different account, or the address is reserved (see "Changing the email address" in the introduction).

Authorizations:
apiTokenAuth
path Parameters
provider
required
string
Value: "firebase"

Social provider name

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
token
required
string

Firebase ID token from social provider (Apple or Google via Firebase)

name
string <= 255 characters

Optional name override. If not provided, name is derived from the provider or email.

Responses

Request samples

Content type
application/json
{
  • "token": "eyJraWQiOiJXNldjT0tCIiwiYWxnIjoiUlMyNTYifQ...",
  • "name": "John Doe"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Auth - Token

Token refresh and logout

Refresh the current JWT

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Logout the current user and revoke the active JWT

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Me - Profile

Current user profile

Get current user's full profile

Returns the authenticated user's own profile with private fields.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update current user's profile

Partially update the authenticated user's profile (PATCH semantics). Only provided fields will be updated.

Changing email here is deprecated; see "Changing the email address" in the introduction. Until the field is removed, a change here clears email_verified_at and sends a verification mail to the new address, so operations that contribute content return 403 auth.email_not_verified until it is confirmed; the previous address may receive an undo notice. An address that is in use or reserved, or the one the account can be restored to through an undo link, returns 422 on email.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
name
string <= 255 characters

User's display name

email
string <email> <= 255 characters
Deprecated

User's email address (must be unique). Deprecated: change the address with POST /me/email/start and POST /me/email/verify-code instead, which confirm the new address with a code first. This field will be removed once the site and app use that flow.

password
string <password> >= 8 characters

New password (requires password_confirmation)

password_confirmation
string <password> >= 8 characters

Password confirmation (required when password is provided)

null or Gender (string)

User's gender preference

null or string <= 15000 characters

User's biography or about text

null or string

User's birthdate in YYYY-MM-DD format (cannot be in the future)

profile_visibility
string (ProfileVisibility)
Enum: "public" "protected" "private"

User's profile visibility setting. Protected = visible to authenticated users.

Responses

Request samples

Content type
application/json
{
  • "name": "Jane Doe",
  • "email": "jane@example.com",
  • "password": "new-secure-password",
  • "password_confirmation": "new-secure-password",
  • "gender": { },
  • "biography": "I love reading books about history and science fiction.",
  • "birthdate": "1990-05-15",
  • "profile_visibility": "public"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete current user's account

Permanently deletes the authenticated user's account. The account is locked out immediately; data cleanup happens asynchronously.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Start an email change (request a confirmation code)

Mails a one-time code to the new address. See "Changing the email address" in the introduction. The account's current address, and the address it can be restored to through an undo link, return 422 on email; a missing or wrong password returns 422 on password. Requires a verified address (403 auth.email_not_verified otherwise); not available during impersonation (403 auth.forbidden).

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

The new email address. Must differ from the account's current address.

password
string <password>

The account's current password. Required when the profile's has_password is true; a missing or wrong password returns 422 on password. Omit it for accounts without a password.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "password": "pa$$word"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Resend the email change code

Sends a fresh code to the address of the pending change, replacing the previous one. For any other address, or when no change is pending, nothing is sent and the response is the same 202. Same 403 and 422 cases as start, except that no password is needed.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

The new email address to send a fresh code to.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com"
}

Response samples

Content type
application/json
{
  • "message": "string"
}

Confirm the email change with the code

Confirms the code. On success the new address replaces the current one, verified, and the updated profile is returned; the previous address may receive an undo notice (see the introduction). Same 403 cases, and the same 422 cases on email, as start. A wrong, expired or used code, or too many wrong attempts, returns 422 on code; a new code does not lift the block. If the new address was taken or reserved by another account in the meantime, the response is 409 auth.account_exists. In every failure the account keeps its current address.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
email
required
string <email> <= 255 characters

The new email address the code was sent to.

code
required
string <= 32 characters

The one-time code sent to the new address.

Responses

Request samples

Content type
application/json
{
  • "email": "user@example.com",
  • "code": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Me - Avatar

Profile avatar management

Upload or update current user's avatar

Upload a new avatar image for the authenticated user. If an avatar already exists, it will be replaced and the old file deleted.

Important: This endpoint requires multipart/form-data content type. Sending the file as a JSON string or base64-encoded body will be rejected.

Authorizations:
(apiTokenAuthbearerAuth)
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: multipart/form-data
required
avatar
required
string <binary>

Avatar image file (JPEG, PNG, or WebP, max 2048 KB / 2 MB)

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete current user's avatar

Remove the current user's avatar image

Authorizations:
(apiTokenAuthbearerAuth)
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Me - Preferences

User preferences and settings

Update user preferences

Update user preferences for the authenticated user. Supports 'ui' and 'notifications' namespaces. Values are merged with existing preferences (not replaced).

You can update one or both namespaces in a single request.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
object <= 50 properties

Client-side UI preferences. No key validation - clients can store any valid JSON structure (max 50 keys).

object

Profile visibility preferences. Only show_birthdate and show_gender are allowed.

object

Notification preferences. All properties are optional boolean values for each NotificationType.

Responses

Request samples

Content type
application/json
{
  • "ui": {
    },
  • "profile": {
    },
  • "notifications": {
    }
}

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Me - Activity

User activity and status

Current user compact status

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Current user activity lists

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

App sync data with timestamps

Returns user activity data with timestamps for app synchronization. Unlike /me/activity, this endpoint includes timestamps on all fields, making it suitable for syncing user state after login.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Me - Notifications

Notifications and notification settings

List user's notifications

Returns a paginated list of the authenticated user's notifications. Supports filtering by read status and cursor-based pagination.

Authorizations:
(apiTokenAuthbearerAuth)
query Parameters
per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

unread
integer
Enum: 0 1

Filter to only unread notifications. Use 1 for true or 0 for false.

before
string <date-time>

Return notifications created before this timestamp (RFC 3339 format)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Mark multiple notifications as read

Marks multiple notifications as read for the authenticated user. Can mark specific notifications by ID or all notifications (optionally filtered to unread only).

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
One of
all
required
boolean

Mark all notifications as read

unread_only
boolean

When 'all' is true, only mark unread notifications

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete multiple notifications

Deletes multiple notifications by ID for the authenticated user.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
ids
required
Array of strings <uuid> non-empty [ items <uuid > ]

Notification IDs to delete

Responses

Request samples

Content type
application/json
{
  • "ids": [
    ]
}

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Mark a notification as read

Idempotently marks a specific notification as read for the authenticated user. Returns 204 even if the notification doesn't exist, doesn't belong to the user, or is already read.

Authorizations:
apiTokenAuthbearerAuth
path Parameters
id
required
string <uuid>

Notification ID (UUID)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete a notification

Idempotently deletes a specific notification for the authenticated user. Returns 204 even if the notification doesn't exist or doesn't belong to the user.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
id
required
string <uuid>

Notification ID (UUID)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Get unread notification count

Returns the count of unread notifications for the authenticated user.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "count": 0
}

List notification mutes

Returns all notification mutes for the authenticated user.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create or update a notification mute

Creates or updates a notification mute for the authenticated user. If a mute already exists for the same subject_type, subject_id, and type combination, it will be updated.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
subject_type
required
string
Enum: "book_list" "campaign" "comment" "review"

Type of the subject to mute

subject_id
required
integer

ID of the subject to mute

null or string

Specific notification type to mute (null to mute all types for this subject)

null or string

When the mute should expire (null for indefinite, RFC 3339 format)

Responses

Request samples

Content type
application/json
{
  • "subject_type": "book_list",
  • "subject_id": 0,
  • "type": { },
  • "until": { }
}

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete a notification mute

Deletes a notification mute for the authenticated user. Idempotent - returns 204 even if the mute doesn't exist.

Authorizations:
apiTokenAuthbearerAuth
path Parameters
id
required
integer

The ID of the notification mute to delete

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Me - Following

Users and contributors I follow, and my followers

List who I follow

Lists users and contributors (authors) the authenticated user follows.

Authorizations:
(apiTokenAuthbearerAuth)
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List my followers

Lists users who follow the authenticated user (paginated).

Authorizations:
(apiTokenAuthbearerAuth)
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Me - Impersonation

Admin impersonation (assume token exchange and session revocation)

Exchange an assume token for an impersonation JWT

Exchanges a one-time assume token (generated by the CMS) for a short-lived impersonation JWT. The assume token is consumed atomically — it cannot be reused. The resulting JWT carries act and impersonation claims for audit traceability.

No Bearer token required — the assume token itself is the credential.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
token
required
string = 64 characters

The 64-character hex-encoded assume token

Responses

Request samples

Content type
application/json
{
  • "token": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4e5f6a1b2"
}

Response samples

Content type
application/json
{
  • "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  • "token_type": "Bearer",
  • "expires_in": 315360000,
  • "user": {
    }
}

Revoke an impersonation JWT

Blacklists the current impersonation JWT, ending the impersonation session. Only works with tokens that carry the impersonation claim.

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Users

User profiles and discovery

Search for users

Search for users with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "name" "followers_count"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "asc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

List users

Gets a paginated list of users.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific user profile

Gets a user profile by ID. Includes profile fields (biography, birthdate, gender) and visibility preferences. Email is never exposed in this endpoint.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a specific user by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string

The unique username/slug of the user

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a specific user by legacy slug (Hebban v1 username)

Used for redirecting old Hebban v1 URLs that use original username format (e.g., 'Hans Ramstijn-4759')

Authorizations:
apiTokenAuth
path Parameters
legacySlug
required
string

The original username from Hebban v1

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Users - Following

List who a user follows

Lists users and contributors (authors) the specified user follows.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer

User ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List a user's followers

Lists users who follow the specified user (paginated).

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer

User ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Contributors - Following

List a contributor's followers

Lists users who follow the specified contributor (paginated).

Authorizations:
apiTokenAuth
path Parameters
contributor_id
required
integer

Contributor ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Follows

User and contributor follows

Follow a user (idempotent)

Idempotently follows the specified user (singleton per follower/followable). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
user_id
required
integer

User ID to follow

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Unfollow a user

Deletes the current user's follow for the specified user (idempotent). Requires authentication. Returns 204 even if there is no follow to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
user_id
required
integer

User ID to unfollow

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Follow a contributor (idempotent)

Idempotently follows the specified contributor (singleton per follower/followable). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
contributor_id
required
integer

Contributor ID to follow

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Unfollow a contributor

Deletes the current user's follow for the specified contributor (idempotent). Requires authentication. Returns 204 even if there is no follow to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
contributor_id
required
integer

Contributor ID to unfollow

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Comments

Comments on reviews, articles, and events

List comments for a review

Lists comments for the review (default is nested with embedded children).

Authorizations:
apiTokenAuth
path Parameters
review_id
required
integer

Review ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 1000 ]
Default: 1000

The number of items per page (comments listing only).

nested
integer
Default: 1
Enum: 0 1

When true (1, default), returns top-level comments with embedded children. When false (0), returns a flat list of all comments (parents and replies) without embedded children.

sort_by
string
Default: "created_at"
Value: "created_at"

Field to sort comments by

sort_direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction (asc = oldest-first, desc = newest-first)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create a comment for a review

Creates a comment for the review. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
review_id
required
integer

Review ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
body
required
string

Comment text body

parent_id
integer or null

Optional parent comment ID (single-level threading)

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "parent_id": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List comments for an article

Lists comments for the article (default is nested with embedded children)

Authorizations:
apiTokenAuth
path Parameters
article_id
required
integer

Article ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 1000 ]
Default: 1000

The number of items per page (comments listing only).

nested
integer
Default: 1
Enum: 0 1

When true (1, default), returns top-level comments with embedded children. When false (0), returns a flat list of all comments (parents and replies) without embedded children.

sort_by
string
Default: "created_at"
Value: "created_at"

Field to sort comments by

sort_direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction (asc = oldest-first, desc = newest-first)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create a comment for an article

Creates a comment for the article. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
article_id
required
integer

Article ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
body
required
string

Comment text body

parent_id
integer or null

Optional parent comment ID (single-level threading)

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "parent_id": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List comments for a campaign post

Lists comments for the campaign post (default is nested with embedded children). Book club post comments nest up to three levels deep (a reply to a reply to a top-level comment) — the children field recurses accordingly. Returns 404 if the post doesn't exist or isn't live (draft and scheduled posts are indistinguishable from posts that don't exist).

Authorizations:
apiTokenAuth
path Parameters
campaign_post_id
required
integer

Campaign post ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 1000 ]
Default: 1000

The number of items per page (comments listing only).

nested
integer
Default: 1
Enum: 0 1

When true (1, default), returns top-level comments with embedded children. When false (0), returns a flat list of all comments (parents and replies) without embedded children.

sort_by
string
Default: "created_at"
Value: "created_at"

Field to sort comments by

sort_direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction (asc = oldest-first, desc = newest-first)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create a comment for a campaign post

Creates a comment for the campaign post. Requires authentication; any authenticated user may comment — a book club submission is not required.

When comments are closed for the post, this returns 422 for everyone, including coordinators and editors.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
campaign_post_id
required
integer

Campaign post ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
body
required
string

Comment text body

parent_id
integer or null

Optional parent comment ID (up to three levels of nesting for book club posts)

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "parent_id": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

List comments for an event

Lists comments for the event (default is nested with embedded children).

Authorizations:
apiTokenAuth
path Parameters
event_id
required
integer

Event ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 1000 ]
Default: 1000

The number of items per page (comments listing only).

nested
integer
Default: 1
Enum: 0 1

When true (1, default), returns top-level comments with embedded children. When false (0), returns a flat list of all comments (parents and replies) without embedded children.

sort_by
string
Default: "created_at"
Value: "created_at"

Field to sort comments by

sort_direction
string
Default: "asc"
Enum: "asc" "desc"

Sort direction (asc = oldest-first, desc = newest-first)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create a comment for an event

Creates a comment for the event. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
event_id
required
integer

Event ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
body
required
string

Comment text body

parent_id
integer or null

Optional parent comment ID (single-level threading)

Responses

Request samples

Content type
application/json
{
  • "body": "string",
  • "parent_id": 0
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a comment

Partially updates the comment body (PATCH semantics). Only the fields provided in the request body will be updated; not all comment fields need to be supplied. Requires authentication; only the author can update their own comment.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
comment_id
required
integer

Comment ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
body
required
string

New comment text body

Responses

Request samples

Content type
application/json
{
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a comment

Deletes a comment. Requires authentication; only the author can delete their own comment.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
comment_id
required
integer

Comment ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Likes

Likes on reviews, comments, and lists

Set current user's like for a review (idempotent)

Idempotently sets the current user's like for the review (singleton per user/review). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
review_id
required
integer

Review ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's like for a review

Deletes the current user's like for the review (idempotent). Requires authentication. Returns 204 even if there is no like to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
review_id
required
integer

Review ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Set current user's like for an article (idempotent)

Idempotently sets the current user's like for the article (singleton per user/article). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
article_id
required
integer

Article ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's like for an article

Deletes the current user's like for the article (idempotent). Requires authentication. Returns 204 even if there is no like to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
article_id
required
integer

Article ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Set current user's like for a list (idempotent)

Idempotently sets the current user's like for the list (singleton per user/list). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer

List ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's like for a list

Deletes the current user's like for the list (idempotent). Requires authentication. Returns 204 even if there is no like to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer

List ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Set current user's like for an event (idempotent)

Idempotently sets the current user's like for the event (singleton per user/event). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
event_id
required
integer

Event ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's like for an event

Deletes the current user's like for the event (idempotent). Requires authentication. Returns 204 even if there is no like to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
event_id
required
integer

Event ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Set current user's like for a comment (idempotent)

Idempotently sets the current user's like for the comment (singleton per user/comment). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
comment_id
required
integer

Comment ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's like for a comment

Deletes the current user's like for the comment (idempotent). Requires authentication. Returns 204 even if there is no like to delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
comment_id
required
integer

Comment ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Reviews - Mine

My reviews

List my reviews

Lists the authenticated user's reviews with pagination.

Authorizations:
(apiTokenAuthbearerAuth)
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Reviews - Users

User reviews

List a user's reviews

Lists published reviews created by a specific user with pagination.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer

User ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Reviews - Works

Work reviews

List published reviews

Lists published reviews with pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

contributor_id
Array of integers <= 10 items [ items >= 1 ]

Filter by contributor ID(s). Supports single or multiple contributors (OR logic).

Examples:

  • Single: ?contributor_id=123
  • Multiple (CSV): ?contributor_id=123,456
  • Multiple (array): ?contributor_id[]=123&contributor_id[]=456

Maximum 10 contributor IDs per request.

contributor_role
string^(?:A01|A12|A13|B01|B05|B06|C01|E07|Z98|Z99)$...
Example: contributor_role=A01

Filter by ONIX contributor role. Based on ONIX codelist 17 (https://ns.editeur.org/onix/en/17). Codes: A01 (Author), A12 (Illustrator), A13 (Photographer), B01 (Editor), B05 (Adapter), B06 (Translator), C01 (Compiled by), E07 (Narrator), Z98 (Various), Z99 (Other).

user_id
integer >= 1

Filter records to those created by the given user ID.

work_id
integer >= 1

Filter records to those associated with the given work ID.

stars
integer [ 1 .. 5 ]

Filter reviews to those with exactly this many stars (1-5).

min_stars
integer [ 1 .. 5 ]

Filter reviews to those with stars greater than or equal to this value (1-5).

max_stars
integer [ 1 .. 5 ]

Filter reviews to those with stars less than or equal to this value (1-5).

user_label[]
Array of strings [ 1 .. 3 ] items
Items Enum: "normal" "team" "crew"

Filter by the review author's user label (OR logic - reviews whose author has any of the specified labels). The frontend "Hebban" filter is user_label[]=team&user_label[]=crew. ?user_label=team and ?user_label=team,crew are accepted as well.

length[]
Array of strings [ 1 .. 3 ] items
Items Enum: "short" "compact" "extended"

Filter by the length of the review text, counted in words; the title does not count (OR logic - reviews of any of the specified lengths). The boundaries currently are: short fewer than 50 words, compact 50 to 200 words, extended more than 200 words. The server counts the words: markup such as line breaks is not counted, a word is a run of letters and digits that may contain an apostrophe or hyphen (zo'n, e-mail), and punctuation and emoji on their own are not words. Combines with the other filters. ?length=extended and ?length=compact,extended are accepted as well.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

sort_by
string
Default: "created_at"
Enum: "id" "created_at" "stars" "likes_count" "comments_count"

Field to sort reviews by

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific review

Gets a review by ID.

Authorizations:
apiTokenAuth
path Parameters
review_id
required
integer

Review ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a review

Updates a review. Requires authentication; only the author can update their own review.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
review_id
required
integer

Review ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
work_type
string
Enum: "book" "ebook" "audiobook"

Type of work being reviewed

stars
integer [ 1 .. 5 ]

Star rating from 1 to 5

title
string

Review title

body
string

Review content

Responses

Request samples

Content type
application/json
{
  • "work_type": "book",
  • "stars": 1,
  • "title": "string",
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a review

Deletes a review. Requires authentication; only the author can delete their own review.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
review_id
required
integer

Review ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Get a specific review by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string

The SEO-friendly slug of the review (format: user-name-over-book-title)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List reviews for a work

Authorizations:
apiTokenAuth
path Parameters
work_id
required
integer

Work ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

user_id
integer >= 1

Filter records to those created by the given user ID.

stars
integer [ 1 .. 5 ]

Filter reviews to those with exactly this many stars (1-5).

min_stars
integer [ 1 .. 5 ]

Filter reviews to those with stars greater than or equal to this value (1-5).

max_stars
integer [ 1 .. 5 ]

Filter reviews to those with stars less than or equal to this value (1-5).

user_label[]
Array of strings [ 1 .. 3 ] items
Items Enum: "normal" "team" "crew"

Filter by the review author's user label (OR logic - reviews whose author has any of the specified labels). The frontend "Hebban" filter is user_label[]=team&user_label[]=crew. ?user_label=team and ?user_label=team,crew are accepted as well.

length[]
Array of strings [ 1 .. 3 ] items
Items Enum: "short" "compact" "extended"

Filter by the length of the review text, counted in words; the title does not count (OR logic - reviews of any of the specified lengths). The boundaries currently are: short fewer than 50 words, compact 50 to 200 words, extended more than 200 words. The server counts the words: markup such as line breaks is not counted, a word is a run of letters and digits that may contain an apostrophe or hyphen (zo'n, e-mail), and punctuation and emoji on their own are not words. Combines with the other filters. ?length=extended and ?length=compact,extended are accepted as well.

sort_by
string
Default: "created_at"
Enum: "id" "created_at" "stars" "likes_count" "comments_count"

Field to sort reviews by

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create a review for a work

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
work_type
required
string
Enum: "book" "ebook" "audiobook"

Type of work being reviewed

stars
required
integer [ 1 .. 5 ]

Star rating from 1 to 5

title
required
string

Review title

body
required
string

Review content

Responses

Request samples

Content type
application/json
{
  • "work_type": "book",
  • "stars": 1,
  • "title": "string",
  • "body": "string"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Ratings

Book ratings

Get current user's rating for a work

Gets the current user's rating for the work. Requires authentication. Returns 404 if the user has not rated the work.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "rated": true,
  • "stars": 1
}

Create or update current user's rating for a work (idempotent)

Idempotently creates or updates the current user's rating (singleton per user/work). Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
stars
required
integer [ 1 .. 5 ]

Star rating from 1 to 5

Responses

Request samples

Content type
application/json
{
  • "stars": 1
}

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's rating for a work

Deletes the current user's rating for the work (idempotent). Requires authentication. Returns 204 even if there is no rating to delete. Returns 409 if a review exists for this work by the same user.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Reading Statuses - Mine

My reading status

Get reading statuses with works

Lists reading statuses for the authenticated user, with embedded work data.

Returns reading statuses ordered by most recently added first. Supports cursor pagination and work sorting via sort_by.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
status
required
string
Enum: "read" "reading" "want-to-read"
Example: reading

Reading status filter

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "last_added"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "review_count" "favorite_count" "popularity" "title" "contributor" "last_added" "last_read" "own_rating"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date
  • publication_date_latest - Most recent publication date
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Number of readers
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
  • last_added - When added to shelf (default, most recent first)
  • last_read - When you last finished reading (read shelf) or when the status was last updated (other shelves)
  • own_rating - Your own rating (stars); works you have not rated sort last in both directions
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    },
  • "count": 0
}

Reading Statuses - Users

User reading statuses

Get reading statuses with works for a user

Lists reading statuses for a user, with embedded work data.

Returns reading statuses ordered by most recently added first. Supports cursor pagination.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
Example: 123

User ID

status
required
string
Enum: "read" "reading" "want-to-read"
Example: reading

Reading status filter

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "last_added"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "review_count" "favorite_count" "popularity" "title" "contributor" "last_added"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date
  • publication_date_latest - Most recent publication date
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Number of readers
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
  • last_added - When added to shelf (default, most recent first)
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    },
  • "count": 0
}

Reading Statuses - Works

Work reading statuses

List followed users who read a work

Lists the users the authenticated user follows who have this work on reading status read (paginated). Ordered by status_updated_at (when the reading status was last changed), most recently changed first. The authenticated user is never included. Users with a private profile are excluded; public and protected profiles are included. Users who only rated the work, without a read status, are not included. count is the total number of these users across all pages.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    },
  • "count": 0
}

Get current user's reading status for a work

Gets the current user's reading status for the work. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Create or update current user's reading status for a work (idempotent)

Creates or updates the current user's reading status (singleton per user/work). Requires authentication. When status is 'read', the finish date is recorded as a read entry (one registration per work per calendar year). If finished_on is omitted, it defaults to today in UTC. Changing the status away from 'read' removes the most recent read entry for the work whose year's challenge is still open; entries of closed challenge years are kept.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
status
required
string (ReadingStatusState)
Enum: "want_to_read" "reading" "read"

Current reading status for the work.

finished_on
string <date>

Optional date (YYYY-MM-DD, UTC). Defaults to today in UTC if omitted.

Responses

Request samples

Content type
application/json
{
  • "status": "want_to_read",
  • "finished_on": "2019-08-24"
}

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Delete current user's reading status for a work

Clears the current user's reading status for the work. Requires authentication. Always returns 204 even if no reading status existed. Clearing a 'read' status removes the most recent read entry for the work whose year's challenge is still open; entries of closed challenge years are kept.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Read Entries

Read entry tracking

List current user's read entries for a work

Lists the current user's read entries for the work, ordered by finished_on descending. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Create a read entry for the current user and work

Creates a read entry. A work is registered once per calendar year: a submission for a year already recorded returns the existing entry instead of creating another. This is not a true idempotent operation, so it still returns 201 Created. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
work_id
required
integer

Work ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
finished_on
required
string <date>

Date when the work was finished (YYYY-MM-DD, UTC)

source
string (ReadEntrySource)
Default: "manual"
Enum: "manual" "import" "challenge"

Source of the read entry.

Responses

Request samples

Content type
application/json
{
  • "finished_on": "2019-08-24",
  • "source": "manual"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Lists - Mine

My personal lists

Current user's collections (challenges and lists) with work IDs

Authorizations:
apiTokenAuthbearerAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Current user's collections with contains_work per entry for a given work

Authorizations:
apiTokenAuthbearerAuth
path Parameters
work
required
integer

The work ID to check membership against

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List my lists

Lists the current user's personal lists. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "created_at"
Enum: "created_at" "title" "likes_count" "works_count"

Field to sort results by.

  • created_at - Creation time
  • title - List title alphabetically
  • likes_count - Number of likes
  • works_count - Number of works in the list
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

preset
boolean

Filter lists by preset status. When true, only preset lists (top, favorite, wishlist, owned, lent) are returned. When false, only user-created (free) lists are returned. When omitted, all lists are returned.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Create a new list

Creates a personal list for the current user. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
title
string
null or string
visibility
string (ListVisibility)
Enum: "public" "private"

Visibility for personal book lists.

Responses

Request samples

Content type
application/json
{
  • "title": "My favorite books",
  • "description": "Books I can read over and over again",
  • "visibility": "public"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a specific list

Gets a personal list. Requires authentication; owners can always view.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update a specific list

Updates a personal list. Requires authentication; only the owner can update.

Preset lists (is_preset: true) have a system-managed title and description that cannot be changed. Only visibility can be updated on preset lists. Sending title or description for a preset list returns 422.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
title
string
null or string
visibility
string (ListVisibility)
Enum: "public" "private"

Visibility for personal book lists.

Responses

Request samples

Content type
application/json
{
  • "title": "Updated List Title",
  • "description": { },
  • "visibility": "public"
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Delete a specific list

Deletes a personal list. Requires authentication; only the owner can delete.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Get the works of a list

Lists works in one of the current user's personal lists. Requires authentication. Supports work sorting via sort_by.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "last_added"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "review_count" "favorite_count" "popularity" "title" "contributor" "last_added" "last_read"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date
  • publication_date_latest - Most recent publication date
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Number of readers
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
  • last_added - When added to list (default, most recent first)
  • last_read - When you last read the work (unread works always at the end)
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    },
  • "count": 0
}

Add a work to a list (idempotent)

Adds a work to one of the current user's personal lists. Idempotent — repeated calls succeed without side effects. Requires authentication; only the owner can update.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer
work_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Remove a work from a list

Removes a work from one of the current user's personal lists. Requires authentication; only the owner can update.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
list_id
required
integer
work_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Lists - Users

User lists

List a user's public lists

Lists the specified user's personal lists that are PUBLIC. Requires API token.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "created_at"
Enum: "created_at" "title" "likes_count" "works_count"

Field to sort results by.

  • created_at - Creation time
  • title - List title alphabetically
  • likes_count - Number of likes
  • works_count - Number of works in the list
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

preset
boolean

Filter lists by preset status. When true, only preset lists (top, favorite, wishlist, owned, lent) are returned. When false, only user-created (free) lists are returned. When omitted, all lists are returned.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific user's public list

Gets a user's personal list if it is PUBLIC.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
list_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the works of a user's public list

Lists works in a user's personal list if it is PUBLIC.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
list_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "last_added"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "review_count" "favorite_count" "popularity" "title" "contributor" "last_added"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date
  • publication_date_latest - Most recent publication date
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Number of readers
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
  • last_added - When added to list (default, most recent first)
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Challenges - Mine

My reading challenges

List my challenges

Returns all challenges the current user has joined, including their pledge target and progress. Use this to display the user's active and past challenges.

Authorizations:
(apiTokenAuthbearerAuth)
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Join a challenge

Join a reading challenge. Optionally set a pledge target (number of books to read). Returns 409 if the user has already joined this challenge, or if the challenge has expired (past its end date) — expired challenges no longer accept participants.

Authorizations:
(apiTokenAuthbearerAuth)
Request Body schema: application/json
required
challenge_id
required
integer

The ID of the challenge to join

null or integer >= 1

Optional pledge (number of books to read)

Responses

Request samples

Content type
application/json
{
  • "challenge_id": 0,
  • "pledge_target": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get my challenge details

Returns details about a specific challenge the user has joined, including their pledge target, progress, and the list of works they've added to this challenge.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
challenge_id
required
integer

The ID of the challenge

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Update my pledge

Update your pledge target (number of books to read) for a challenge you've joined. Returns 409 if the challenge has expired and is read-only.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
challenge_id
required
integer

The ID of the challenge

Request Body schema: application/json
required
null or integer >= 1

Number of books you pledge to read (null to remove pledge)

Responses

Request samples

Content type
application/json
{
  • "pledge_target": null
}

Response samples

Content type
application/json
{
  • "data": {
    }
}

Leave a challenge

Leave a challenge you've joined. This removes your participation and all works you've added to this challenge. Returns 409 if the challenge has expired and is read-only.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
challenge_id
required
integer

The ID of the challenge to leave

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Get the works of my challenge participation list

Lists works in the current user's challenge participation list for a given challenge. Once the challenge has expired, the list is frozen and only returns works with a read entry linked to that challenge. Other works are no longer part of the frozen list: they are not returned and no longer counted in works_count, which keeps matching the number of items returned here. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
challenge_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Add a work to my challenge participation list (idempotent)

Adds a work to the current user's challenge participation list. Idempotent — repeated calls succeed without side effects. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
challenge_id
required
integer
work_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Remove a work from my challenge participation list

Removes a work from the current user's challenge participation list. Requires authentication.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
challenge_id
required
integer
work_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}

Challenges - Users

User challenge participation

List a user's challenge participation

Lists a user's public challenge participation lists

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a user's challenge participation

Gets a user's participation in a specific challenge

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
challenge_id
required
integer

The ID of the challenge

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List works in a user's challenge

Lists the works a user has added to their challenge participation. Once the challenge has expired, the list is frozen and only returns works with a read entry linked to that challenge. Other works are no longer part of the frozen list: they are not returned and no longer counted in works_count, which keeps matching the number of items returned here.

Authorizations:
apiTokenAuth
path Parameters
user_id
required
integer
challenge_id
required
integer

The ID of the challenge

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Challenges - Public

Public reading challenges

Search for challenges

Search for challenges with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "published_at" "title"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

List challenges

Lists challenges available to join, filtered by year.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

from_year
integer [ 2000 .. 2100 ]
Default: 2025

Filter challenges from this year onwards (inclusive)

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction by year (desc = newest first, asc = oldest first)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

Get challenge statistics

Returns aggregated statistics for a specific challenge including participant count, total pledges, books read, and completion count.

Authorizations:
apiTokenAuth
path Parameters
challenge
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Works

Books and other works

List works

Lists works with cursor-based pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "id"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "title" "contributor"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date (works without a value are excluded)
  • publication_date_latest - Most recent publication date (works without a value are excluded)
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Total number of completed readings, all-time (includes re-reads)
  • read_count_30d - Unique readers in the last 30 days (rolling window, refreshed daily)
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

publication_date_first_from
string <date>
Example: publication_date_first_from=2026-03-10

Include works with publication_date_first on or after this date (YYYY-MM-DD). Works without a first publication date are excluded.

publication_date_first_until
string <date>
Example: publication_date_first_until=2026-04-09

Include works with publication_date_first on or before this date (YYYY-MM-DD). Works without a first publication date are excluded.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific work

Gets a work by ID.

Authorizations:
apiTokenAuth
path Parameters
work_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a work by ISBN-13

Look up a work by its normalized ISBN-13.

The ISBN must be provided as a 13-digit ISBN-13 without separators (no spaces or hyphens).

Authorizations:
apiTokenAuth
path Parameters
isbn
required
string = 13 characters ^[0-9]{13}$

13-digit ISBN-13 without separators.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Fetch multiple works by IDs

Fetches multiple works by their IDs in a single request.

Behavior:

  • Returns works in the same order as the input IDs
  • Missing IDs are skipped silently (no error)
  • Duplicate IDs return duplicate works (e.g., ids=1,5,5 returns work 5 twice)
  • Maximum 100 IDs per request

Example: GET /works/bulk?ids=1,6,5,5 returns 4 works in order: [1, 6, 5, 5]

Authorizations:
apiTokenAuth
query Parameters
ids
required
string^\d+(,\d+)*$
Example: ids=1,6,5,5

Comma-separated list of work IDs (max 100). Duplicates are allowed and will return the same work multiple times.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List featured works

Returns works from the "Uitgelicht" (Featured) editorial list. Works are ordered by their position in the list as curated by editors.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List popular new releases

Returns up to 100 works first published in the last 30 days, sorted by popularity (descending). Works with fewer than 2 ratings are excluded so a single rating cannot place a work at the top.

The list is fully algorithmic and refreshes with the current date and platform popularity; no editorial curation applies.

Authorizations:
apiTokenAuth
query Parameters
source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List recently read works

Returns up to 100 works that have been recently finished by users across the platform. Each work is shown once, ordered by most recent finish date.

Authorizations:
apiTokenAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List recently reviewed works

Returns up to 100 works that have been recently reviewed by users across the platform. Each work is shown once, ordered by most recent review date.

Authorizations:
apiTokenAuth

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List upcoming works

Returns works expected to become available within the next 3 months (configurable).

Upcoming works have:

  • NO editions with availability codes 20-23 (Available, In Stock, To Order, POD)
  • At least ONE edition with availability codes 10-12, 30-34 (Not Yet Available, Awaiting Stock, etc.)
  • An expected availability date within the configured window

Works are ordered by publication_date_first ascending (soonest first).

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Search for works

Search for works with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "publication_date_first" "publication_date_latest" "title" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "id"

Field to sort search results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

Get a specific work by slug

Gets a work by slug.

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get events for a work

Lists events for the work with pagination.

Authorizations:
apiTokenAuth
path Parameters
work_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

period
string
Default: "future"
Enum: "future" "past" "all"

Filter events by period. Default is future.

sort_by
string
Default: "starts_on"
Enum: "starts_on" "created_at"

Sort column (whitelisted). Defaults to starts_on.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get rank history for a work

Returns daily Hebban rank snapshots for a work, ordered chronologically (oldest first). Each entry represents the work's rank on a specific date (1 = most popular, up to 10,000). Data is available from November 2018. Works that are not currently ranked may still have historical data.

Authorizations:
apiTokenAuth
path Parameters
work_id
required
integer

The ID of the work

query Parameters
from
string <date>

Start date for the history range (inclusive). Defaults to 1 year ago. Must not be in the future.

to
string <date>

End date for the history range (inclusive). Defaults to today. Must not be in the future.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get recommendations for a work

Returns personalized recommendations for a work based on collaborative filtering. First request returns 202 and triggers generation. Subsequent requests return 200 with cached results. Recommendations are grouped into 8 subsets based on author/genre/recency similarity. Failed generation returns 200 with status=failed and error message.

Authorizations:
apiTokenAuth
path Parameters
work_id
required
integer

The ID of the work

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Contributors

Authors and contributors

Search for contributors

Search for contributors (authors) by name with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "name" "followers_count" "works_count" "popularity"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "asc"
Enum: "asc" "desc"

Sort direction

contributor_role
Array of strings[ items^(?:A01|A12|A13|B01|B05|B06|C01|E07|Z98|Z99)$... ]
Example: contributor_role=A01,B06

Filter by ONIX contributor role(s). Accepts comma-separated codes or array. Results include contributors with any of the specified roles (OR logic). Based on ONIX codelist 17 (https://ns.editeur.org/onix/en/17). Codes: A01 (Author), A12 (Illustrator), A13 (Photographer), B01 (Editor), B05 (Adapter), B06 (Translator), C01 (Compiled by), E07 (Narrator), Z98 (Various), Z99 (Other).

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

List contributors

Lists contributors with pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "popularity"
Enum: "id" "name" "followers_count" "works_count" "popularity"

Field to sort contributors by

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Fetch multiple contributors by IDs

Fetches multiple contributors by their IDs in a single request.

Behavior:

  • Returns contributors in the same order as the input IDs
  • Missing IDs are skipped silently (no error)
  • Duplicate IDs return duplicate contributors (e.g., ids=1,5,5 returns contributor 5 twice)
  • Maximum 100 IDs per request

Example: GET /contributors/bulk?ids=1,6,5,5 returns 4 contributors in order: [1, 6, 5, 5]

Authorizations:
apiTokenAuth
query Parameters
ids
required
string^\d+(,\d+)*$
Example: ids=1,6,5,5

Comma-separated list of contributor IDs (max 100). Duplicates are allowed and will return the same contributor multiple times.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Get a specific contributor by ID

Gets a contributor by ID.

Authorizations:
apiTokenAuth
path Parameters
contributor_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the works from a contributor

Lists works for the contributor with pagination.

Authorizations:
apiTokenAuth
path Parameters
contributor_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

contributor_role
string^(?:A01|A12|A13|B01|B05|B06|C01|E07|Z98|Z99)$...
Example: contributor_role=A01

Filter by ONIX contributor role. Based on ONIX codelist 17 (https://ns.editeur.org/onix/en/17). Codes: A01 (Author), A12 (Illustrator), A13 (Photographer), B01 (Editor), B05 (Adapter), B06 (Translator), C01 (Compiled by), E07 (Narrator), Z98 (Various), Z99 (Other).

sort_by
string
Default: "id"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "title" "contributor"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date (works without a value are excluded)
  • publication_date_latest - Most recent publication date (works without a value are excluded)
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Total number of completed readings, all-time (includes re-reads)
  • read_count_30d - Unique readers in the last 30 days (rolling window, refreshed daily)
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get events for a contributor

Lists events for the contributor with pagination.

Authorizations:
apiTokenAuth
path Parameters
contributor_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

period
string
Default: "future"
Enum: "future" "past" "all"

Filter events by period. Default is future.

sort_by
string
Default: "starts_on"
Enum: "starts_on" "created_at"

Sort column (whitelisted). Defaults to starts_on.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific contributor by slug

Gets a contributor by slug.

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Publishers

Publishers

List publishers

Lists publishers with pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

Get a specific publisher by ID

Gets a publisher by ID.

Authorizations:
apiTokenAuth
path Parameters
publisher_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the works from a publisher

Lists works for the publisher with pagination.

Authorizations:
apiTokenAuth
path Parameters
publisher_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "id"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "title" "contributor"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date (works without a value are excluded)
  • publication_date_latest - Most recent publication date (works without a value are excluded)
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Total number of completed readings, all-time (includes re-reads)
  • read_count_30d - Unique readers in the last 30 days (rolling window, refreshed daily)
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific publisher by slug

Gets a publisher by slug.

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Genres

Book genres

List genres

Lists genres with pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

Responses

Response samples

Content type
application/json
{}

Get a specific genre by ID

Gets a genre by ID.

Authorizations:
apiTokenAuth
path Parameters
genre_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get the works from a genre

Lists works for the genre with pagination.

Authorizations:
apiTokenAuth
path Parameters
genre_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "id"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "title" "contributor"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date (works without a value are excluded)
  • publication_date_latest - Most recent publication date (works without a value are excluded)
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Total number of completed readings, all-time (includes re-reads)
  • read_count_30d - Unique readers in the last 30 days (rolling window, refreshed daily)
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific genre by slug

Gets a genre by slug.

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Series

Book series

Get the works in a series

Lists the works in a series, paginated. Works are ordered by part number high-to-low; works without a part number follow, newest first.

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific series by slug

Gets a series by slug.

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Hebban 1000

Annual Hebban 1000 book rankings

List Hebban 1000 entries

Lists the Hebban 1000 entries ordered by rank for a specific year. Defaults to the most recent year that has entries when no year is provided.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

year
integer >= 2018

Filter entries for a specific Hebban 1000 year

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

List Hebban 1000 work IDs

Returns the work IDs of the Hebban 1000 for a specific year, ordered by rank. Defaults to the most recent year that has entries when no year is provided. Intended for clients that need to compute overlap with a user's read books.

Authorizations:
apiTokenAuth
query Parameters
year
integer >= 2018

Filter entries for a specific Hebban 1000 year

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Articles

Articles and blog posts

Search for articles

Search for articles with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

type
Array of strings (ArticleType)
Items Enum: "news" "interview" "book_of_the_month" "inspiration" "book_club" "opinion" "community" "advertorial" "promotion" "deepdive" "quiz"

Filter by type. Accepts single value, comma-separated values, or array syntax. Examples: ?type=news, ?type=news,interview, ?type[]=news&type[]=interview

sort_by
string
Default: "relevance"
Enum: "relevance" "published_at" "title" "likes_count" "comments_count"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

List articles

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

status
string
Enum: "draft" "scheduled" "published" "archived"
Example: status=published

Filter by publication status

type
Array of strings (ArticleType)
Items Enum: "news" "interview" "book_of_the_month" "inspiration" "book_club" "opinion" "community" "advertorial" "promotion" "deepdive" "quiz"

Filter by type. Accepts single value, comma-separated values, or array syntax. Examples: ?type=news, ?type=news,interview, ?type[]=news&type[]=interview

contributor_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those associated with the given contributor ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?contributor_id=123, ?contributor_id=123,456, ?contributor_id[]=123&contributor_id[]=456

work_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those associated with the given work ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?work_id=456, ?work_id=456,789, ?work_id[]=456&work_id[]=789

book_list_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those associated with the given book list ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?book_list_id=789, ?book_list_id=789,101, ?book_list_id[]=789&book_list_id[]=101

related_article_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those that reference or link to the given article ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?related_article_id=999, ?related_article_id=999,888, ?related_article_id[]=999&related_article_id[]=888

sort_by
string
Default: "id"
Enum: "id" "created_at" "updated_at" "published_at" "scheduled_at" "title"

Field to sort results by.

Note: Articles with null values in the sort column are excluded from results.

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific article

Authorizations:
apiTokenAuth
path Parameters
article_id
required
integer
query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this item, as carried by its preview link. Send it when fetching the item for a preview.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gets an article by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this item, as carried by its preview link. Send it when fetching the item for a preview.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Events

Events and activities

List featured events

Returns curated featured events ordered by position.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Search for events

Search for events with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "starts_on" "title"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "asc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

List events

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

period
string
Default: "future"
Enum: "future" "past" "all"

Filter events by period. Default is future.

sort_by
string
Default: "starts_on"
Enum: "starts_on" "created_at"

Sort column (whitelisted). Defaults to starts_on.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get works for an event

Lists works for the event with pagination.

Authorizations:
apiTokenAuth
path Parameters
event_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "id"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "title" "contributor"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date (works without a value are excluded)
  • publication_date_latest - Most recent publication date (works without a value are excluded)
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Total number of completed readings, all-time (includes re-reads)
  • read_count_30d - Unique readers in the last 30 days (rolling window, refreshed daily)
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get contributors for an event

Lists contributors for the event with pagination.

Authorizations:
apiTokenAuth
path Parameters
event_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "popularity"
Enum: "id" "name" "followers_count" "works_count" "popularity"

Field to sort contributors by

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific event by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Pages

Static pages

List pages

List published static pages with cursor-based pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific page by ID

Authorizations:
apiTokenAuth
path Parameters
page_id
required
integer
query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this item, as carried by its preview link. Send it when fetching the item for a preview.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a specific page by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this item, as carried by its preview link. Send it when fetching the item for a preview.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Tags

Content tags

Search for tags

Search for tags with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "articles_count" "name"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "asc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

List tags

Lists tags with pagination.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

Get a specific tag

Gets a tag by ID.

Authorizations:
apiTokenAuth
path Parameters
tag_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get works for a specific tag

Lists all works associated with a specific tag with pagination.

Authorizations:
apiTokenAuth
path Parameters
tag_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "id"
Enum: "id" "publication_date_first" "publication_date_latest" "ratings_count" "rating_average" "read_count" "read_count_30d" "review_count" "favorite_count" "popularity" "title" "contributor"

Field to sort results by.

  • id - Work ID
  • publication_date_first - First publication date (works without a value are excluded)
  • publication_date_latest - Most recent publication date (works without a value are excluded)
  • ratings_count - Number of ratings
  • rating_average - Average rating score
  • read_count - Total number of completed readings, all-time (includes re-reads)
  • read_count_30d - Unique readers in the last 30 days (rolling window, refreshed daily)
  • review_count - Number of reviews
  • favorite_count - Number of favorites
  • popularity - Popularity score
  • title - Work title alphabetically
  • contributor - Primary author name alphabetically
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

isbn
string [ 4 .. 13 ] characters ^[0-9]{4,13}$

Optional filter on edition ISBN-13. Provide 4–13 digits; results include works whose edition ISBN-13 starts with this prefix.

genres[]
Array of integers [ 1 .. 10 ] items

Filter by genre IDs (OR logic - works matching any of the specified genres)

language
Array of strings
Items Enum: "dut" "eng" "other"

Filter by language code (ONIX Codelist 74, based on ISO 639-2/B). Supports single value, comma-separated values, or array syntax. other includes all non-dut/eng languages and null.

source[]
Array of strings [ 1 .. 3 ] items
Items Enum: "cb" "titelbank" "v1"

Filter by work source (OR logic - works matching any of the specified sources)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get articles for a specific tag

Lists all articles associated with a specific tag with pagination.

Authorizations:
apiTokenAuth
path Parameters
tag_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

status
string
Enum: "draft" "scheduled" "published" "archived"
Example: status=published

Filter by publication status

type
Array of strings (ArticleType)
Items Enum: "news" "interview" "book_of_the_month" "inspiration" "book_club" "opinion" "community" "advertorial" "promotion" "deepdive" "quiz"

Filter by type. Accepts single value, comma-separated values, or array syntax. Examples: ?type=news, ?type=news,interview, ?type[]=news&type[]=interview

contributor_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those associated with the given contributor ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?contributor_id=123, ?contributor_id=123,456, ?contributor_id[]=123&contributor_id[]=456

work_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those associated with the given work ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?work_id=456, ?work_id=456,789, ?work_id[]=456&work_id[]=789

book_list_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those associated with the given book list ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?book_list_id=789, ?book_list_id=789,101, ?book_list_id[]=789&book_list_id[]=101

related_article_id
Array of integers <= 10 items [ items >= 1 ]

Filter articles to those that reference or link to the given article ID(s). Supports single value, comma-separated, or array syntax (OR logic). Examples: ?related_article_id=999, ?related_article_id=999,888, ?related_article_id[]=999&related_article_id[]=888

sort_by
string
Default: "id"
Enum: "id" "created_at" "updated_at" "published_at" "scheduled_at" "title"

Field to sort results by.

Note: Articles with null values in the sort column are excluded from results.

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get events for a specific tag

Lists all events associated with a specific tag with pagination.

Authorizations:
apiTokenAuth
path Parameters
tag_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

period
string
Default: "future"
Enum: "future" "past" "all"

Filter events by period. Default is future.

sort_by
string
Default: "starts_on"
Enum: "starts_on" "created_at"

Sort column (whitelisted). Defaults to starts_on.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get book lists for a specific tag

Lists all book lists associated with a specific tag with pagination.

Authorizations:
apiTokenAuth
path Parameters
tag_id
required
integer
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "created_at"
Enum: "created_at" "title" "likes_count" "works_count"

Field to sort results by.

  • created_at - Creation time
  • title - List title alphabetically
  • likes_count - Number of likes
  • works_count - Number of works in the list
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Gets a tag by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Campaigns

List curated book clubs

Returns curated book club campaigns ordered by position.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List curated giveaways

Returns curated giveaway campaigns ordered by position.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List featured book clubs (deprecated) Deprecated

Returns curated featured book club campaigns ordered by position. Deprecated in favor of GET /curated/book-clubs.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List featured giveaways (deprecated) Deprecated

Returns curated featured giveaway campaigns ordered by position. Deprecated in favor of GET /curated/giveaways.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Search for campaigns

Search for campaigns with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "published_at" "title"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

List campaigns

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

status
string
Enum: "draft" "scheduled" "published" "archived"
Example: status=published

Filter by publication status

type
Array of strings (CampaignType)
Items Enum: "giveaway" "book_club"

Filter by type. Accepts single value, comma-separated values, or array syntax. Examples: ?type=giveaway, ?type=giveaway,book_club, ?type[]=giveaway&type[]=book_club

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific campaign

Authorizations:
apiTokenAuth
path Parameters
campaign_id
required
integer
query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this item, as carried by its preview link. Send it when fetching the item for a preview.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Gets a campaign by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this item, as carried by its preview link. Send it when fetching the item for a preview.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

List reviews from approved campaign participants

Returns reviews for the campaign's work written by approved campaign participants only

Authorizations:
apiTokenAuth
path Parameters
campaign_id
required
integer

Campaign ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

user_id
integer >= 1

Filter records to those created by the given user ID.

stars
integer [ 1 .. 5 ]

Filter reviews to those with exactly this many stars (1-5).

min_stars
integer [ 1 .. 5 ]

Filter reviews to those with stars greater than or equal to this value (1-5).

max_stars
integer [ 1 .. 5 ]

Filter reviews to those with stars less than or equal to this value (1-5).

sort_by
string
Default: "created_at"
Enum: "id" "created_at" "stars" "likes_count" "comments_count"

Field to sort reviews by

sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Submit to a campaign

Submit to a campaign. This endpoint is idempotent: if the user has already submitted to this campaign, the existing submission is returned with a 200 status instead of creating a duplicate.

Authorizations:
(apiTokenAuthbearerAuth)
path Parameters
campaign
required
integer

Campaign ID

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.
Request Body schema: application/json
required
required
object

Flexible form data

Responses

Request samples

Content type
application/json
{
  • "data": { }
}

Response samples

Content type
application/json
{
  • "id": 0,
  • "campaign": {
    },
  • "user": {
    },
  • "data": { },
  • "created_at": "2019-08-24T14:15:22Z",
  • "updated_at": "2019-08-24T14:15:22Z"
}

List posts for a campaign

Lists posts for a campaign in one chronological stream, ordered by display_at (the publication date for a live post, the scheduled date for an upcoming one) with id as tiebreaker — so the intro post appears first and upcoming posts naturally follow the live ones. Every item has the same shape; upcoming posts carry upcoming: true with empty blocks (content stays private until live) and a null published_at, and their detail endpoint still returns 404 until they go live. Draft posts are never included.

Authorizations:
apiTokenAuth
path Parameters
campaign_id
required
integer

Campaign ID

query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific campaign post

Returns a single live campaign post, including its content blocks.

With a valid preview_id generated for this post, for another post of its campaign or for the campaign itself, a draft or scheduled post is returned as well, including its blocks. A preview is read-only: the comments of a post that isn't live stay unavailable.

Returns 404 for a post that doesn't exist, and for a post that isn't live unless preview_id is valid for that post or its campaign. A draft or scheduled post without such a token is indistinguishable from a post that doesn't exist; an archived post is never returned.

Authorizations:
apiTokenAuth
path Parameters
campaign_post_id
required
integer

Campaign post ID

query Parameters
preview_id
string <uuid>

Short-lived preview token generated by the CMS for this post, another post of its campaign or the campaign itself. A token that has expired, or was generated for something outside this campaign, gives a 404 for a post that isn't live.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Lists - Editorial

Editorial and curated lists

List curated app lists

Returns curated editorial book lists for the app ordered by position.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List curated homepage lists

Returns curated editorial book lists for the homepage ordered by position.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

List homepage lists (deprecated) Deprecated

Returns curated editorial book lists for the homepage ordered by position. Deprecated in favor of GET /curated/homepage/lists.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ]
}

Search for book lists

Search for book lists with support for sorting and pagination

Authorizations:
apiTokenAuth
query Parameters
page
integer >= 1
Default: 1

The page number for traditional pagination (used by search endpoints)

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

query
required
string [ 2 .. 255 ] characters

Search query (minimum 2 characters)

sort_by
string
Default: "relevance"
Enum: "relevance" "title" "created_at" "works_count" "likes_count"

Field to sort results by. When relevance is selected, results are sorted by search match score (highest first). The sort_direction parameter is ignored when sorting by relevance.

sort_direction
string (SortDirection)
Default: "asc"
Enum: "asc" "desc"

Sort direction

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {}
}

List work lists

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

sort_by
string
Default: "created_at"
Enum: "created_at" "title" "likes_count" "works_count"

Field to sort results by.

  • created_at - Creation time
  • title - List title alphabetically
  • likes_count - Number of likes
  • works_count - Number of works in the list
sort_direction
string
Default: "desc"
Enum: "asc" "desc"

Sort direction

status
string
Enum: "draft" "scheduled" "published" "archived"
Example: status=published

Filter by publication status

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": [
    ],
  • "links": {},
  • "meta": {
    }
}

Get a specific work list

Authorizations:
apiTokenAuth
path Parameters
list_id
required
integer
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Get a specific work list by slug

Authorizations:
apiTokenAuth
path Parameters
slug
required
string
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Slides

Landing page sliders and banners

List slides for a set

Returns active slides for a specific set, ordered by position. Only returns slides where is_active is true and current date is within the active_from/active_until range. This filtering is always applied server-side and cannot be modified via query parameters.

Authorizations:
apiTokenAuth
query Parameters
cursor
string

Encoded cursor for cursor-based pagination

per_page
integer [ 1 .. 250 ]
Default: 20

The number of items per page.

set
required
string (SlideSet)
Enum: "homepage" "books" "authors" "events" "reading_clubs" "theme_banner"

The slide set to retrieve (e.g., homepage, books, authors)

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{}

Stats

Public community statistics

Get public statistics

Returns public statistics about the Hebban community.

Statistics are precomputed hourly and cached. The cached_at field indicates when the data was last calculated.

Last 30 days stats use a rolling 30-day window.

Authorizations:
apiTokenAuth
header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Health

API health checks

Get API health status

Returns the current health status of the API and its dependencies.

This endpoint does not require authentication or the Accept: application/json header.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/json
{
  • "data": {
    }
}

Admin

Validate a preview token

Checks whether a short-lived preview_id token is currently valid. Used by the frontend before rendering previews of articles, pages, book clubs, book club posts and giveaways.

Authorizations:
apiTokenAuth
query Parameters
preview_id
required
string <uuid>

Short-lived preview token UUID generated by Filament.

header Parameters
X-Request-Id
string^[0-7][0-9A-HJKMNP-TV-Z]{25}$
Example: 01J9Z1Q4R7Z7B4M5X6C7D8E9FA

Optional client-provided correlation identifier (ULID).

  • If omitted, the server generates one.
  • If provided, it MUST be a valid ULID (26 characters, case-insensitive Base32).
  • Invalid values will result in a 400 Bad Request error.

Responses

Response samples

Content type
application/problem+json
{
  • "title": "Unauthenticated",
  • "status": 401,
  • "request_id": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "code": "auth.unauthenticated",
  • "type": "about:blank",
  • "detail": "Already joined this challenge.",
  • "instance": "01J9Z1Q4R7Z7B4M5X6C7D8E9FA",
  • "errors": {
    }
}