API Reference

The RiftScribe REST API provides access to the Riftbound card database. Public endpoints are freely accessible. Private endpoints power internal features and may change without notice.

Base URL: https://riftscribe.gg● Live spec loaded

Quick Start

Fetch all cards with a single request:

curl "https://riftscribe.gg/api/cards?limit=10"

Search for a card by name:

curl "https://riftscribe.gg/api/cards/search?q=dragon"

Public Endpoints

Open

No authentication required. All responses are JSON.

GET/api/cardsPublic

List cards

List cards with optional filtering by set, faction, rarity, type, and name search. Total match count is returned in the X-Total-Count response header.

Query Parameters

qSearch query for card name

set_idFilter by set ID

factionFilter by faction

rarityFilter by rarity

typeFilter by card type (e.g. Unit, Spell, Battlefield)

is_bannedFilter by ban status

sortSort order

limitMaximum number of cards to return

offsetNumber of cards to skip

▸ Show example

curl \
  "https://riftscribe.gg/api/cards?q=dragon&set_id=OGN"

GET/api/cards/searchPublic

Search cards by name (typeahead)

Search cards by name with fuzzy matching for typeahead/autocomplete functionality. Uses PostgreSQL pg_trgm for efficient fuzzy text search. Results are ordered by: 1. Exact matches first (case-insensitive) 2. Prefix matches 3. Similarity score (fuzzy matches) 4. Alphabetical by name Minimum query length: 2 characters Maximum results: 20

Query Parameters

qrequiredSearch query (minimum 2 characters)

typesFilter by card types

limitMaximum results

▸ Show example

curl \
  "https://riftscribe.gg/api/cards/search?q=dragon"

GET/api/cards/filtersPublic

Get available filter values

Get all available distinct values for filtering cards. Returns distinct values for: - Sets: All set IDs in the database - Factions: All faction values - Rarities: All rarity levels Useful for populating filter dropdowns with available options.

▸ Show example

curl \
  "https://riftscribe.gg/api/cards/filters"

GET/api/cards/{card_id}Public

Get a single card with details

Get detailed information for a single card. Supported ID formats: - Full ID: `OGN-001-298` (set-collector_number-internal_id) - Short format: `OGN-1` or `OGN-001` (set-collector_number) - Alternate art: `OGN-100a` (letter suffix) or full ID `OGN-100a-298` - Signature/star: `OGN-301-star` or `OGN-301*` - Token: full ID `UNL-T03` The API normalizes collector numbers, so `OGN-1` and `OGN-001` both work. A bare collector number (`OGN-100`) always resolves to the base card; use the variant suffix to reach alternate arts and signatures.

Path Parameters

card_idrequired

▸ Show example

curl \
  "https://riftscribe.gg/api/cards/OGN-1"

Private Endpoints

Internal

These endpoints power internal features like Riftboundle. Not intended for third-party use and may change without notice.

GET/health/livenessPrivate

Liveness probe

Check if the application is running. Used by Kubernetes liveness probes.

▸ Show example

curl \
  "https://riftscribe.gg/health/liveness"

GET/health/readinessPrivate

Readiness probe

Check if the application is ready to serve traffic by verifying its critical dependencies (database). Used by Kubernetes readiness probes. Returns 503 when a dependency is unavailable so traffic is not routed to a pod that cannot serve it.

▸ Show example

curl \
  "https://riftscribe.gg/health/readiness"

GET/api/riftboundle/todayPrivate

Get today's puzzle

Get or create today's Riftboundle puzzle. Returns puzzle metadata without revealing the solution. Puzzles are generated deterministically based on the date.

▸ Show example

curl \
  "https://riftscribe.gg/api/riftboundle/today"

POST/api/riftboundle/guessPrivate

Submit a guess

Submit a guess for a Riftboundle puzzle. The API validates the puzzle, evaluates the guess against the solution, and stores the attempt. Returns attribute-by-attribute feedback without revealing the solution unless the guess is correct. Evaluation results: - `exact`: The attribute matches exactly - `close`: The attribute is close (for numeric values) - `wrong`: The attribute does not match

▸ Show example

curl \
  -X POST \
  "https://riftscribe.gg/api/riftboundle/guess"

GET/api/riftboundle/statePrivate

Get puzzle state

Get the current state of a puzzle for a user. Returns all previous attempts and whether the puzzle is solved/finished. Useful for refreshing the page or resuming an in-progress game.

Query Parameters

puzzle_idrequired

user_idrequired

▸ Show example

curl \
  "https://riftscribe.gg/api/riftboundle/state?puzzle_id=1&user_id=my-session-id"

GET/api/quizPrivate

List Quizzes

List authored quizzes, optionally filtered by category, difficulty, or tag.

Query Parameters

categoryFilter by category

difficultyFilter by difficulty 1-3

tagFilter by tag (exact match)

▸ Show example

curl \
  "https://riftscribe.gg/api/quiz?category=value&difficulty=value"

GET/api/quiz/duePrivate

List Due Quizzes

List authored quizzes due for review for a given user, ordered by due_at, limit 20.

Query Parameters

user_idrequiredUser identifier

▸ Show example

curl \
  "https://riftscribe.gg/api/quiz/due?user_id=my-session-id"

GET/api/quiz/{quiz_id}Private

Get Quiz

Get a single authored quiz by ID.

Path Parameters

quiz_idrequired

▸ Show example

curl \
  "https://riftscribe.gg/api/quiz/EXAMPLE"

POST/api/quiz/masteryPrivate

Record Quiz Mastery

Record a quiz mastery result and apply SM-2 spaced repetition.

▸ Show example

curl \
  -X POST \
  "https://riftscribe.gg/api/quiz/mastery"

GET/api/card-quiz/generatePrivate

Generate Card Quiz

Generate a dynamic quiz question for a card, without writing anything to the DB.

Query Parameters

user_idrequiredUser identifier

template_typeForce a specific template type

factionRestrict candidate card to this faction

▸ Show example

curl \
  "https://riftscribe.gg/api/card-quiz/generate?user_id=my-session-id"

POST/api/card-quiz/masteryPrivate

Record Card Mastery

Record a card quiz mastery result and apply SM-2 spaced repetition.

▸ Show example

curl \
  -X POST \
  "https://riftscribe.gg/api/card-quiz/mastery"

GET/api/card-quiz/duePrivate

List Due Cards

List card+template pairs due for review for a given user, ordered by due_at, limit 20.

Query Parameters

user_idrequiredUser identifier

▸ Show example

curl \
  "https://riftscribe.gg/api/card-quiz/due?user_id=my-session-id"

OpenAPI Spec

Machine-readable spec at /openapi.json. Interactive Swagger UI at /docs.

Swagger UI →openapi.json

Loading…