Build with your game data

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

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

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.

For write endpoints, send:

Idempotency-Key: your-stable-key

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

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.

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.

Rate + quota headers are returned on every authenticated request:

• X-RateLimit-*

• X-Daily-*

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.

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.

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