API docs by Redocly

Hebban.nl API specification (0.9.74)

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"
}

Common error codes:

  • 400 Bad Request — Invalid request format or parameters
  • 401 Unauthenticated — Missing or invalid authentication
  • 403 Forbidden — Authenticated but not authorized
  • 404 Not Found — Resource doesn't exist
  • 406 Not Acceptable — Missing Accept: application/json header
  • 422 Unprocessable Content — Validation errors (includes errors field with details)
  • 429 Too Many Requests — Rate limit exceeded

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.

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

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": {
    }
}

Auth - Password

Password reset and recovery

Send password reset 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
email
required
string <email>

Responses

Request samples

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

Response samples

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

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"
}

Resend email verification

Resend the email verification link to the authenticated user. Rate limited to 3 requests per hour.

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
{
  • "message": "Verification email 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)
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.

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.

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

User's email address (must be unique)

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 <= 1000 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.

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 - 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

Fully qualified class name 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": "string",
  • "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.

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.

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 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.

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.

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).

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).

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"

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)
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": {
    }
}

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": {
    }
}

Reading Statuses - Works

Work reading statuses

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' and append_read_entry is true, also appends a read entry. If finished_on is omitted, it defaults to today in UTC.

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.

append_read_entry
boolean
Default: true

When true and status is 'read', also append a read entry

finished_on
string <date>

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

Responses

Request samples

Content type
application/json
{
  • "status": "want_to_read",
  • "append_read_entry": true,
  • "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.

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. Duplicate submissions for the same (user, work, finished_on) are de-duplicated. 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": {
    }
}

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.

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": {
    }
}

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.

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. 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

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" "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 - 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
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.

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 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 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.

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" "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.

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 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" "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 - 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
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.

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" "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 - 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
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.

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" "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 - 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
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.

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": {
    }
}

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 current year 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
{}

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
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
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" "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 - 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
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.

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
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
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" "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 - 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
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.

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
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
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"
}

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

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 article and page previews.

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": {
    }
}