Skip to content
How You Rank
Sign in

Developer Docs

API v1 Playbook

Contract-first docs for agents and integrations.

API v1 Docs

This API is designed for both human developers and AI agents.

Start Here

  • OpenAPI contract: GET /api/v1/openapi

  • Capability manifest: GET /api/v1/capabilities

  • Effective access and usage: GET /api/v1/usage

  • Identity check: GET /api/v1/me

First-success path for agents:

  1. Create a key in /api-keys.

  2. Copy the secret once.

  3. Call /me, /capabilities, and /usage.

  4. Perform one safe action, such as GET /games?limit=1.

  5. Preserve the returned requestId for support handoff.

Auth

Authorization: Bearer hyr_live_...

You can also send:

  • X-API-Key

  • X-HYR-API-Key

Recommended agent headers:

  • X-HYR-Agent: your-agent/version

  • X-Request-Id: your-correlation-id

  • X-HYR-Debug: true only when debugging a denied request

Standard Envelopes

Success:

{
  "data": {},
  "requestId": "req_123"
}

Paginated list:

{
  "data": [],
  "pagination": {
    "limit": 25,
    "count": 25,
    "total": 140,
    "hasMore": true,
    "nextCursor": "..."
  },
  "requestId": "req_123"
}

Error:

{
  "code": "invalid_request",
  "message": "name is required.",
  "details": null,
  "requestId": "req_123"
}

Denied requests can be retried once with X-HYR-Debug: true or ?trace=true. The error's details.trace field contains sanitized diagnostics only: reason, required tier/scope, quota retry timing, and support hints. Never send raw API keys in support handoff.

Idempotency

For write endpoints, send:

Idempotency-Key: your-stable-key

Replays return Idempotency-Replayed: true. Key reuse with changed payload returns 409 idempotency_key_conflict.

Tiers, Presets, And Operator Access

Public API tiers are:

  • Trial

  • Standard

  • Trusted

Trial is for new or low-history accounts trying the site and API safely. Standard is the normal self-serve tier for established users. Trusted is elevated access for integrations or users with enough trust/history to justify broader quotas or sensitive scopes.

Admin / Operator is not a normal public tier. It requires a Trusted key owned by an approved operator identity, explicit operator scopes, request IDs, idempotency keys on writes, and audit-log correlation.

The API Center is preset-first. Use raw scopes only when a preset does not fit the integration. Before a serious agent run, call:

HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs doctor

/usage returns the current key's tier, presets, scopes, quotas, effective access, blocked-operation reasons, first-success steps, and support handoff fields.

Core Endpoints

  • Games: GET /games, GET /games/{slug}

  • Collections: GET /collections, GET /collections/{slug}, PATCH /collections/{slug}, POST /collections/{slug}, DELETE /collections/{slug}

  • Legacy owned games: GET /owned-games, POST /owned-games, PATCH /owned-games, DELETE /owned-games

  • Wishlists: GET /wishlist-games, POST /wishlist-games, PATCH /wishlist-games, DELETE /wishlist-games

  • Homes: GET /homes, POST /homes, GET /homes/{slug}

  • Public showcase: GET /showcase/players/{handle}/collection, GET /showcase/players/{handle}/wishlist, GET /showcase/homes/{slug}/collection, GET /showcase/homes/{slug}/wishlist

  • Groups: GET /groups, GET /groups/{slug}, POST /groups (Admin / Operator), DELETE /groups/{slug} (Admin / Operator)

  • Groups bulk: POST /groups/bulk (Admin / Operator)

  • Players: GET /players, GET /players/{handle}, POST /players (Admin / Operator)

  • Players bulk: POST /players/bulk (Admin / Operator)

  • Matches: GET /matches, GET /matches/{id}, POST /matches (Admin / Operator), PATCH /matches/{id} (Admin / Operator), DELETE /matches/{id} (Admin / Operator)

  • Matches bulk: POST /matches/bulk (Admin / Operator)

  • Sessions: GET /sessions, GET /sessions/{id}, POST /sessions (Admin / Operator), PATCH /sessions/{id} (Admin / Operator)

  • Sessions bulk: POST /sessions/bulk (Admin / Operator)

  • Rankings: GET /rankings, GET /ranking-methods

  • Rulesets: GET /rulesets/{variantId}, POST /rulesets/create-combo (Admin / Operator)

  • Relationships: GET /player-links, POST /player-links (Admin / Operator), DELETE /player-links (Admin / Operator)

  • API keys: POST /api-keys/{keyId}/rotate

  • Admin API key controls: GET /admin/api-keys/analytics, POST /admin/api-keys/{keyId}/force-rotate, PATCH /admin/api-keys/{keyId}/suspend

  • Admin support lookup: GET /admin/api-keys/audit?requestId=...

  • Admin operator queue: GET /admin/operator-queue, POST /admin/operator-queue, GET /admin/operator-queue/{id}, PATCH /admin/operator-queue/{id}

  • Admin user tools: GET /admin/users, PATCH /admin/users

  • Game admin check: GET /games/check

  • Game catalog import: POST /games/import (trusted admin keys, idempotency supported)

  • Admin catalog quality: GET /admin/catalog-quality/queue, GET /admin/catalog-quality/candidates, GET /admin/catalog-quality/specs, POST /admin/catalog-quality/specs, POST /admin/catalog-quality/refresh, GET /admin/catalog-quality/items/{gameSlug}, GET /admin/catalog-quality/runner-packet, POST /admin/catalog-quality/ranking-assessments

Collections, Homes, And Wishlists

Authenticated management endpoints let a user:

  • track named personal and group collections

  • track owned games and wishlist items inside a collection

  • keep legacy personal/home shelf integrations working during migration

  • add catalog-backed titles or custom titles

  • control collection public visibility

Canonical public collection pages live at /collections/{slug}. Public showcase endpoints still let another website render a player or home's collection/wishlist without an API key.

Showcase Query Params

  • fields: comma-separated optional field groups

    • year
    • players
    • playtime
    • image
    • thumbnail
    • scope
    • home
    • notes
    • visibility
    • timestamps

  • limit: maximum item count

Example: Jarvie Home Public Feeds

curl 'https://howyourank.com/collections/jarvie-home'
curl 'https://howyourank.com/api/v1/showcase/homes/jarvie-home/collection?fields=name,image,players&limit=12'
curl 'https://howyourank.com/api/v1/showcase/homes/jarvie-home/wishlist?fields=name,image,players&limit=12'

Example: Home Wishlist Upsert

curl https://howyourank.com/api/v1/wishlist-games \
  -X POST \
  -H 'Authorization: Bearer hyr_live_...' \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: home-wishlist-001' \
  -d '{
    "items": [
      {
        "gameName": "Croquet",
        "homeSlug": "jarvie-home",
        "isVisiblePublic": true
      }
    ]
  }'

Rendering Notes

  • catalogStatus: "catalog" means the title resolved to a catalog game.

  • catalogStatus: "custom" means the title is still usable and public, but it does not yet exist in the imported game catalog.

  • For small cards, prefer image.square when present and fall back to a text tile when it is null.

Limits

Rate + quota headers are returned on every authenticated request:

  • X-RateLimit-*

  • X-Daily-*

Admin Catalog Quality

The catalog-quality subsystem is for admin agents and catalog operations tooling.

It joins two workflows:

  • intake of unresolved custom titles

  • audit of cataloged games against family-specific data specs

Families

  • board

  • card

  • dice

  • tile

  • word

  • party

  • sport

  • lawn

  • digital

Core endpoints

  • GET /api/v1/admin/catalog-quality/queue

  • GET /api/v1/admin/catalog-quality/candidates

  • GET /api/v1/admin/catalog-quality/specs

  • POST /api/v1/admin/catalog-quality/specs

  • POST /api/v1/admin/catalog-quality/refresh

  • GET /api/v1/admin/catalog-quality/items/{gameSlug}

  • GET /api/v1/admin/catalog-quality/runner-packet

  • POST /api/v1/admin/catalog-quality/ranking-assessments

Queue query params

  • search

  • family

  • missingField

  • staleOnly=true|false

  • sortBy

  • order=asc|desc

Runner packet usage

Use /runner-packet when you want one deterministic unit of work for an agent.

Examples:

curl 'https://howyourank.com/api/v1/admin/catalog-quality/runner-packet' \
  -H 'Authorization: Bearer hyr_live_...'

curl 'https://howyourank.com/api/v1/admin/catalog-quality/runner-packet?family=board' \
  -H 'Authorization: Bearer hyr_live_...'

Handbook

See docs/api/CATALOG_QUALITY_AGENT_HANDBOOK.md in the repo for the full agent workflow and terminology.

Operator Workflow

Before an agent runs Admin / Operator writes, use docs/runbooks/API_OPERATOR_WORKFLOW.md.

Minimum handoff fields:

  • route family and user API vs Admin API boundary

  • required preset, tier, and scopes

  • queue item, Linear issue, or explicit input packet

  • allowed batch size

  • verification endpoint

  • request ID, idempotency key, actor, key label, and timestamp

Stop if /usage says the key lacks the effective access needed for the route, if duplicate candidates are ambiguous, or if the write would change shared scoring/ranking semantics without PM approval.

Reviewed Queue Packets

External agents should propose high-risk match/session, group/player, or key-security work before writing:

HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs admin:operator-queue:create \
  --idempotency-key queue_req_123 \
  --json '{"lane":"match_session","title":"Fix score entry","riskLevel":"high","proposedByAgent":"agent-name","packet":{"correctionType":"patch","affectedMatchIds":["match_1"],"before":{"score":10},"after":{"score":12},"reason":"Score entry correction","rankingImpact":"localized"}}'

match_session packets use affected match/session IDs, before/after fields, correction reason, and ranking impact. group_player packets use canonical handle/slug decisions, relationship changes, ownership/role impact, and explicit handle-change approval. api_key_security packets use exact key IDs, evidence request IDs or abuse signals, proposed action, and rollback plan.

Approval does not execute the write. After execution, attach receipts and verification results:

HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs admin:operator-queue:get --id queue_item_id
HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs admin:operator-queue:dry-run --id queue_item_id
HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs admin:operator-queue:execute --id queue_item_id --claim-id claim_queue_item_id

HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs admin:operator-queue:review \
  --id queue_item_id \
  --json '{"status":"executed","executionReceipts":[{"route":"/api/v1/matches/match_1","method":"PATCH","requestId":"req_write_123","statusCode":200,"executedAt":1779390000000}]}'

Request ID Lookup

HYR_API_KEY=hyr_live_... node tools/hyr-api-cli.mjs admin:api-keys:audit --request-id req_123

The lookup returns sanitized audit entries for operators: route, action type, key ID, user ID, agent name, timestamp, and safe metadata.

Policy controls

  • Optional granular grants (scopeGrants) can be attached to keys.

  • Trusted-tier keys can use IP allowlists.

  • Emergency write/all kill switches can be enabled operationally.