Developers

Ratings API

A versioned REST API serving first-party rating data: developmental-benefit and design-risk scores, age floors, and session guidance — resolvable by slug or by the store identifier a device actually sees. It serves only data this service produced; no third-party metadata is redistributed. Every response carries provenance (review tier, scoring method, methodology v1.3 stamp) and every score change is journaled, never silently overwritten.

FILL: partner positioning paragraph (who this is for, licensing contact)

Authentication

Every data endpoint takes an API key as a bearer token. Sandbox keys (sk_…) serve the complete response schema for a fixed evaluation subset of titles at 30 requests/minute; partner keys (pk_…) serve the full catalog at 300 requests/minute. Keys are issued per agreement and stored only as hashes — a lost key is replaced, never recovered.

Authorization: Bearer sk_your_sandbox_key

Quickstart — store identifier to rating

The integration path for a parental-control agent: pass what the device sees, get the rating back in one call.

curl -H "Authorization: Bearer sk_your_sandbox_key" \
  "https://lumikin.org/api/v1/lookup?store=steam&id=730"

Every response uses one envelope — { data, error, meta }. Interpreting the rating: data.score is the 0–100 headline number; data.recommendedMinAge is the age floor; data.sessionGuidance.minutesPerDay is the daily budget and is null when suppressed (17+ titles, or risk past the gate) — the label then carries the recommendation. meta.mapping.verified tells you whether the store-identifier mapping has been human-checked.

{
  "data": {
    "slug": "counter-strike-global-offensive",
    "type": "game",
    "score": 58,
    "recommendedMinAge": 17,
    "sessionGuidance": { "minutesPerDay": null, "label": "Age-restricted — not recommended for children", ... },
    "provenance": { "reviewTier": "automated", "methodologyVersion": "1.0", ... },
    ...
  },
  "error": null,
  "meta": { "apiVersion": "v1", "mapping": { "store": "steam", "id": "730", "source": "rawg_store_link", "verified": false } }
}

Endpoints

Endpoint	What it serves
`GET /api/v1/games/{slug}`	Rating for a standalone game
`GET /api/v1/experiences/{slug}`	Rating for a UGC experience (Roblox, Fortnite Creative)
`GET /api/v1/lookup?store=&id=`	Resolve a store identifier (Steam appID, Play package, Apple ID, Roblox universe ID) to a rating
`GET /api/v1/changes?since=`	Journaled score changes, oldest first, for forward polling
`GET /api/v1/coverage`	Live coverage, freshness, and provenance statistics
`GET /api/v1/openapi.json`	This API, machine-readable (OpenAPI 3.0) — no key required

Full request/response contract: /api/v1/openapi.json (OpenAPI 3.0). Error codes are consistent everywhere: unauthorized, rate_limited, invalid_params, not_found, not_rated, insufficient_data.

Versioning & deprecation

The path segment (/v1/) is the contract. Within v1, changes are additive only: new fields may appear; existing fields never change meaning, type, or disappear.
Rating values change as games are rescored — that is the product, and the changes feed reports every one. The methodology version in each response says which rubric produced the number.
A breaking contract change ships as /v2/ with v1 maintained in parallel for at least 6 months, with notice to every active key holder.

Data quality & provenance

Coverage, freshness, and provenance-mix numbers are published — computed live, not claimed — on the data-quality page and served by /v1/coverage (one source of truth). The scoring rubric itself is public on the methodology page.