Connect your assistant

Read a durable capture with its raw rounds, revision, timing and game-definition state. Owning-group members only. Supply variantId to preview exact parameter mapping, conflicts and ranking impact; this writes nothing. Pass the returned previewToken and current revision to hyr_capture_match resolve only after reviewing it. A round is not automatically a separate match.

Persist ONE match, optionally with ordered raw rounds, before catalog research. capture records a completed historical match; start records an open match and starts its persisted wall clock. Use exactly one of gameName (provisional) or variantId (catalog). Unknown score direction/unit/settings stay omitted, never guessed or zero-filled. A provisional/open/cancelled match is visible but unranked. update/finish/cancel act on the same matchId with expectedRevision. finish records the observed end; cancel never fabricates duration. A round is not a match: ask the actual format before splitting. Resolve only after hyr_get_capture previews a variant and returns previewToken; resolution preserves original IDs/raw results/rounds/rosters/timing. reopen_resolution returns a mistaken resolution to unranked review. Every write needs a unique opId; exact retries are durable across devices and days.

Add, update or remove a private note for this person's AI ONLY when the person explicitly asks you to remember, change or forget something. Do not save things the person didn't ask for, and do not infer preferences from the conversation. Pass their explicit request as theirWords for the record. Read hyr_get_overview first; noteId comes from notesForYou. Notes are 1–300 trimmed characters, capped at 25 active notes, and visible only to this person and their own connected AI. Remove retires the note; it keeps the stored record. Returns the saved note and the full current notesForYou list. Confirm what changed back to the person.

The orientation call — make it first. Returns who the person is on How You Rank, the groups they play in with each group's pinned ranking methods and their own position under them, any game night that is currently open, their most recent matches, and which permissions this connection actually holds. Read and follow notesForYou at the start of every conversation: these are the person's private notes for their AI. What they say in this conversation overrides saved guidance.

Find games by name, by a name people also call them (Hearts is "Black Lady"), or by category, player count and team capability. Query words team or partnership find team variations; party game searches catalogue categories. Filters can be used without a name. Returns matching variations and their supported counts, plus AKA names and researchStatus (packet structure only, not executed verification). Use the slug with hyr_get_game.

Everything the encyclopedia holds about one game: how to play, history, official links and videos, the names people also call it and its variations, its variations and their rulesets, frequently asked rules questions, scorecard styles. Set includeResearch to read authored source evidence, explicit unknown rule cases, variation guides and executable scorecard definitions. Research receipts record an author's checks; they do not certify the rules or native delivery.

Call this before hyr_record_match for any game you have not recorded before. Games differ enormously — some record points, some placements, some only a winner, some are co-operative — and this returns the exact result signature for a variation, naming the fields a match write must carry and the values they accept.

A group's members, its Leader Metrics — the ranking systems it treats as its scoreboard, each read weighted or unweighted, with that pair's current #1 — its per-game weighting, and the standings under a method you choose. Each leader metric also carries `story`: how differently it reads this group's results compared with plain win/loss. In a small group most methods repeat the win/loss story exactly, so `reorders: 0` means that metric is telling the group nothing new — say so rather than presenting it as a second opinion. Groups this person cannot see are not returned.

How You Rank's founding idea: the same match history, ranked many ways. Ask for a group's, a game's or a person's standings under a named method, or omit the method to get the list of methods with what each one measures.

Recent matches this person can see, newest first, with each one's result and how it was recorded (by a person, or by an assistant, and which one). Filter by group or game.

Look up the opId used to record a match through this same account and client. Durable receipts survive the 24-hour replay cache. Only currently accessible matches are returned. Not found does not prove a previous write failed: older receipts may have expired. Do not blindly record again.

Sides, players, scores, placements, which groups it counts in, whether anyone has disputed it, and its provenance.

The matches THIS assistant recorded for this person, newest first, with each one's id, game and variation, who played, the result, when it was played and when the person's own 24-hour window to correct it closes. Call this when somebody says a match you recorded was wrong and you no longer have the id — after a long conversation, or in a new one. Then correct it with hyr_update_match. Pass includeOthers true to widen it to everything this person recorded themselves, however they recorded it.

Sessions — an evening of games in one group. Returns what is open now and what has finished, with each night's games and standings. A match recorded while a night is open joins that night automatically.

Every list they keep — a main shelf, a camping bag, a two-player shelf — plus their wishlist, and the group shelves they can see (a household's "Jarvie Home"), each saying whether this person may change it. Name one to get its games with their notes, keywords and variation picks. Deleted lists are left out; ask with includeDeleted to see the ones hyr_manage_list can restore.

How You Rank's own lists of the most popular board, card, dice and party games — ranked from sales charts, surveys, Wikipedia pageviews and play counts, with the sources credited. Omit listSlug for every list with how many of its games are on the site and how many are coming soon; name one to get its ranked entries. status narrows to games already on the site (on_site, each with a gameSlug for hyr_get_game) or not yet on it (coming_soon).

The person's own achievements, and the ones they are nearest to earning.

Proposals waiting at /queue: the ones filed for this person, and the ones about a group they administer. Use it to answer "did that go through?" and to avoid filing the same thing twice. There is no tool that approves a proposal. Deciding is a person's act; point them at /queue.

The person's queue at /queue: things they have asked their AI to do later. Each has their own words, an effort hint (auto, quick, careful, deep), and what it is about. Read "waiting" to find work; "needs_you" holds asks where you asked the person something (once they answer, the ask comes back to waiting with their answer beside your question). Work an ask with hyr_update_ask.

This connection's own permissions: what it holds, what it does not, and what is never issuable to any assistant. Signing in granted the whole toolset, so a permission this connection does not hold is one the person switched off on purpose — call this and tell them exactly which one, and where to change it.

The games ON a list. add, remove and move games between lists; note keeps the person's note on one game's copy (condition, house rules, where it lives); variations says which variations that copy plays; keywords sets the person's own private keywords for a game, which follow it onto every list. For the lists themselves — create, rename, share, reorder, restore — use hyr_manage_list. add, remove and move also work on a group's shelf (hyr_get_collections says which ones this person may change), exactly as far as the site lets them. Games are named by catalogue slug or exact name. A game that is not in the catalogue is never guessed or invented: it comes back under notInCatalogue with near-matches and how to ask for it. This is the person's own lane, and every change here can be undone.

The person's lists themselves — their own lane, and every change here can be undone. - create: a new list with a name, and optionally an emoji, a description and a visibility (private unless they say otherwise). - edit: rename it, or change its emoji or description (null clears either). - share: set visibility. private is only them; link is anyone holding the link, listed nowhere; public is anyone, listed on their profile. Making a list public is theirs to decide and you may do it when they ask — say back that it is now public. - rotate_link: a fresh share link; the old one stops working at once. - reorder: order is their lists, first to last; unnamed ones keep their order after. - set_main: which list is their main one (it shows first and cannot be deleted). - restore: bring back a deleted list with every game, note and variation it had — hyr_get_collections with includeDeleted lists them. Deleting is hyr_delete_list. The wishlist is not a list these tools change.

Files a dispute on a recorded match. This changes no record and no standings — it asks the people in the group to check something. Use it when you believe a result is wrong rather than editing anything.

Moves one ask along. "claim" before you start (pass title if the ask has none — a few words a person scans in a list). "ask_person" when you need something only they can say; the ask waits for them at /queue. "complete" when you are done, with a note saying what you did and links to anything on this site you made or changed. "release" puts a claimed ask back untouched. Pass expectedVersion from hyr_list_asks: if the ask changed since you read it, you are told rather than overwriting the person's edit. Archiving and deleting are the person's alone.

When the person says "put that on my queue", "remind me to…" or "do that later", write it down here instead of doing it now. Each ask lands on their queue at /queue as Waiting, marked as added by their AI at their request, and you (or another AI of theirs) pick it up later with hyr_list_asks. Only at the person's request: an idea of your own is something to say in the conversation, not something to file.

Files a proposal instead of writing. The person sees it at /queue and approves it, corrects it first, or turns it down. This is optional, not a fallback, and not the safe option — writing directly is equally normal and usually what the person wants. Choose it when you genuinely should: you are not sure you understood; the person said "put it in for me to check"; or several people share the group and one of them should confirm. It is NOT the way around a refusal. Signing in grants every write tool this server has, so a permission you do not hold is one the person switched off on purpose — filing the same write as a proposal walks around their decision. Say which permission is missing instead. payload is EXACTLY the arguments you would have passed to the tool itself, so approving does precisely what you meant. A match proposal is checked as it is filed — if the game name or a player cannot be resolved, you are told now, while the person is still here to answer, rather than leaving them a proposal that fails when they press Approve. It writes nothing to anybody's records — it only asks.

Optional clock records game duration, informational turn times, or a clock-game time bank. Only a Timed variation with timeout forfeits may record timedOut; turn timing never changes the result. Clock sides use stable sideNumber in result order, not placement. Omitted clock preserves existing timing. Records a match from plain description — the game by name or alias, the players by the names the person uses, and their scores, places or who won. Prefer this over hyr_record_match: it resolves the ids for you and refuses rather than guessing unless the game has an exact normalized title, slug or catalogued alias. Near game names are suggestions only. An otherNameMatches receipt tells you when a saved Also called name matched; relay it, for example Aaron → Erin Jarvie via another name. Call it FIRST with dryRun true. You get back exactly what it understood — which game, which variation, which people, which result — and you show that to the person in your own words. If they say it is right, call again with dryRun false and the same arguments. It will refuse, in a sentence you can relay, when: no exact game title, slug or alias matches; an alias names multiple games or variations; the game has several variations and none is the default; a name matches more than one person on the roster; a name matches nobody (pass createMissingPlayers true, once the person has said to add them as guests); or the result given cannot describe a result for this game — a game that records scores will not accept 'Dad won' alone; or the variation has a REQUIRED setting and params does not answer it, which is how a variation played for a set number of hands insists on the count it is weighted by. A dry run also comes back with followUpQuestions: at most two optional things worth one more question — how long it took, and, for a game that declares one, the state of the win. Ask them once, take "I don't remember" for an answer, and record either way. They never block anything. Recording a match changes several people's ranking history at once. That is not a reason to hesitate — it is what the person connected you for — but it is a reason to be sure. If you are not confident, say so and ask, rather than recording something you are guessing at.

Attach an existing canonical match to another group without copying it; detach it, or accept/decline a pending share as the receiving group's admin. Use hyr_get_group to find pendingSharingRequests. Every player must have an active receiving-group membership linked by the same person or an existing reserved email; matching names never merge people. Preview with dryRun first. Corrections and deletion stay canonical across groups. Use the returned slug, membership count and activity to distinguish similar groups. A share by someone who already holds authority in the receiving group — its owner, its creator, or an owner/admin on its roster — returns status "attached" immediately, every time; there is nothing to wait for and no second step to take. A share that genuinely needs approval returns status "pending" together with `approvers`, the people who can accept it, each with their participantId, displayName and role. Relay those names instead of saying "an admin": tell the person exactly who to ask.

Optional clock records game duration, informational turn times, or a clock-game time bank. Only a Timed variation with timeout forfeits may record timedOut; turn timing never changes the result. Clock sides use stable sideNumber in result order, not placement. Omitted clock preserves existing timing. Fixes a match that was recorded wrong — the variation, the results, the settings it was played under, the notes, when it was played, how long it took, or how many rounds it completed. Send only the fields that are wrong; everything you leave out is left exactly as it is. Players also match their saved Also called names; relay any otherNameMatches receipt so the person knows which name matched. PREFER THIS OVER DELETING AND RECORDING AGAIN. A match has an identity: photos hang off it, a game night counts it, a share link points at it. Correcting keeps all of that; deleting and re-recording throws it away to fix a field. `results` replaces the whole result, so re-state every side, not only the one that changed. Changing `variation` re-checks the result against how that variation records results, and refuses — in a sentence you can relay — when they do not fit: moving a match from a variation that only records who won to one that records scores needs the scores as well, in the same call. Call it first with dryRun true, read back what it says the match would become, and only then call again with dryRun false. Afterwards, tell the person what the match now says — the variation and every side — so they can confirm the correction landed the way they meant. Whoever recorded a match can correct it for 24 hours; after that a group admin can, and anyone else is refused with that sentence. Use hyr_list_my_recent_matches if you no longer have the id.

Deletes a match: a duplicate, or one recorded against the wrong group. It is a recoverable delete — the match leaves every view and counts for nobody, and an admin of the group can put it back exactly as it was from the site's deleted-items list. Nothing here erases anything. This is the SECOND choice. If what is wrong is a detail — the variation, a score, a player, the date — correct it with hyr_update_match instead; deleting and recording again loses the match's photos, its place in a game night and its share link. Ask the person before calling, in plain words, and pass confirm true only once they have said yes: this comes off everybody's rankings. Whoever recorded the match may remove it within 24 hours; after that, and for anybody else's match, it takes a group admin. Afterwards, tell the person exactly what was removed so they can say if it was the wrong one.

Deletes one of the person's own lists. It is a recoverable delete: the list leaves every view, its games stay in every other list they are on, and hyr_manage_list action restore (or the person, from their Collections page) puts it back exactly as it was, games, notes and all. Nothing here erases anything. If what is wrong is the name, the emoji or who can see it, change that with hyr_manage_list instead of deleting. The main list cannot be deleted — make another one main first. A group's shelf is not deleted by this tool. Ask the person first, and pass confirm true only once they have said yes. Afterwards tell them what was deleted and that it can be restored. A person can switch this one permission off at /settings/ai and keep everything else.

Optional clock records game duration, informational turn times, or a clock-game time bank. Only a Timed variation with timeout forfeits may record timedOut; turn timing never changes the result. Clock sides use stable sideNumber in result order, not placement. Omitted clock preserves existing timing. Writes a result. This is not the person's own lane: recording a match changes several people's ranking history at once, so get it right the first time. Call hyr_describe_result_shape first unless you already know this game's result signature. If a game night is open in the group, the match joins it automatically. Every match you write is marked as recorded by this assistant. If the person mentioned how long it took, or when it started and finished, put that in startedAt / endedAt / durationMinutes. A match's length is a field of its own. It will refuse, in a sentence you can relay, when the variation has a REQUIRED setting and params does not answer it — a variation played for a set number of hands is not rankable without the count, because the group weights it per hand. hyr_describe_result_shape lists a variation's settings and marks the required ones.

Adds a game — but read this first, because what it does is narrower than its name and saying so wrongly to the person is the failure mode. It searches the catalogue first. Only an exact normalized title, slug or catalogued alias counts as already in the catalogue. If the game is already there you get it back and nothing is written; if something close is there you get the near-matches and should check with the person, because a second copy of a game splits a group's history in two. If it is a different game, repeat with confirmNotListed: true. If it is genuinely missing, this files a CANDIDATE carrying what you supplied and your sources. A candidate is not a playable game: a person finishes it through the catalogue's quality pipeline, which needs the real rules, images and a ranking review that no tool call can supply. Tell the person that plainly — do not imply they can record a result against it yet. Sources are required, and they are not decoration: never write rules you remember. Give the publisher's page, a rules page, or a BoardGameGeek entry, and leave a field out rather than guess at it. The candidate also goes on the public request list at /games/requests, where people vote on what gets added next. vote defaults to false: ask the person before setting vote: true to spend one of their ten votes. The result says whether it did. Filing a missing game needs type and description too — the request list shows them. To request a game without sources, use hyr_vote_game_request instead.

The public request list at /games/requests: games that are NOT in the catalogue yet, ranked by how many people voted for them, with the other interest signals (people who typed the title onto their shelf or wishlist, and recorded matches waiting on it). Also returns this person's own ten votes — how many are free, which games hold them — and notes about votes that came back because a game was added, declined or merged. Each request says what kind of game it is (type, tags) and carries a short description. Views: open (default), added (recently added to the catalogue), declined. Sorts: votes (default), newest, az, interest (votes + waiting matches + shelves and wishlists). Filter by type or tag, or search title and description with q — "which card games are people asking for?" is view open, type card. Pass slug for one request. A request is not a game: never offer to record a match against one.

The person's own votes on the request list. Everyone signed in has ten, at most one per game; a vote can be taken back at any time, and comes back by itself when the game is added to the catalogue. Actions: - request: ask for a game by title, with its type and a short description (both required for a new request; tags optional). The catalogue is searched first — a game already here is returned instead. A title somebody already requested reuses that request. Near-matches come back for you to check with the person; repeat with confirmNotListed: true only if it is genuinely a different game. vote defaults to false. Ask the person before setting vote: true to spend a vote on a new or existing request. - vote: +1 a request by slug. Refused when all ten votes are in use — offer to move one, and never take a vote back without being asked. - remove_vote: take the person's vote back from a request. - dismiss_notices: clear the notes about returned votes once the person has seen them. Only at the person's request: a vote is theirs to spend, not yours.

Everything about a group except its results: make one, rename it, add the people who play in it, and choose the ranking systems it is judged by. Identity actions: list_people lists manageable roster identities; reuse_player explicitly adds an existing person to a group using groupId and sourceParticipantId. preview_people takes targetParticipantId and sourceParticipantIds and returns exact mappings, counts, conflicts and a previewToken. Review that concrete mapping with the person before consolidate_people with the same IDs and previewToken. reverse_people takes the returned auditId and refuses intervening identity changes. These operations preserve roster IDs, local names/handles/roles and results; they never transfer claimed ownership or grant private group access. Names and emails never authorize consolidation. Actions: - create: a new group, with this person as its owner. - update: its name, description or type. - add_player: add somebody by name as an unclaimed player. Give their email too and their place is reserved for that account, which they claim themselves. No account is ever created for anybody. Players belong to a group's roster and can play before claiming. add_player asks before it adds. If somebody of that name already plays in another group this person manages, the first call writes NOTHING and comes back with offeredExistingPeople: true and a list of candidates. Two people really do share a name, so a name match never links anybody by itself — put the choice to the person, then call add_player again: with reuseParticipantId set to the chosen candidate's sourceParticipantId (same person, one history across both groups), or with createNew: true (a different person, a separate and independent player, exactly as before). Only people this person can already manage are ever offered. The second call may reuse the same opId — the offer itself is never recorded as an answer. - update_player: correct an existing player's name or set, change or clear an unclaimed player's email reservation. Supply player to identify the existing record; name is the corrected display name. otherNames replaces their global Also called list (up to 10 names, 1–40 characters each; [] clears). Use it when voice typing keeps spelling Erin as Aaron: these names help recording find them in every group. Never repeat their own display name or handle. Requires a linked person. Keeps their handle and match history. Claimed account emails cannot be changed by a group admin. Only when the person says the old spelling was a mistake, add correctHandle: true to regenerate the handle from the name (the old handle keeps working as a link). - remove_player: remove an unused, unclaimed player from this group. Refuses claimed members and anyone referenced by match or event history. - invite: mint a reusable group join link. The recipient signs in and can choose an existing unclaimed player, preserving history. Reserved players require the matching verified email. How You Rank sends no invitation emails, so the person has to send the link — say so plainly. - pin_methods: replace this group's whole set of Leader Metrics — the ranking systems it treats as its scoreboard, each read weighted or unweighted. This changes how every member's standing reads, not just this person's, so confirm it before you do it. - set_game_weight: how much one game counts in the group's cross-game rankings. 0 excludes it, 1 is normal. Name a variation as well and the weight applies to that variation alone — different variations are genuinely different games to rank, and a variation's own weight always beats its game's. - set_weighting_mode: whether those weights apply at all. - set_parameter_scaling: group-specific positive numeric parameter scaling for one variation. parameterKey null resets it; numeric weight remains inherited or overridden as before. - export_weights: download complete group game/variation settings, including inactive entries. Export and retain this snapshot before experimenting with weights so the person can undo the batch. - preview_weights: preview a portable snapshot without changing data; returns currentRevision. - restore_weights: show the person the exact preview and obtain their agreement before applying the snapshot with expectedRevision from preview; atomically refuses stale or unresolved backups and retains an undo snapshot. - weight_history: last 20 restores with before/after snapshots. Backups exclude individual-result overrides and leader metrics. - set_role: make a member with an account an admin of the group, or take admin away again. Only the group's creator (or a site admin) can do this, and the creator's own role cannot be changed this way. Somebody with no account holds no role at all — invite them first. - transfer_ownership: make another member the group's CREATOR. A group has exactly one creator, and the creator can do everything here including deleting the group, so confirm the person means it and name who it is going to. The outgoing creator stays on as an admin. Only the current creator or a site admin can do it, and the person receiving it must already be an active member with an account. Every action but create needs this person to be an owner or admin of the group. Holding the permission is not the same as having authority over somebody else's group, and a refusal will say so.

Configure fixed teams or individual rankings for one night, choose its own cross-game methods and game/variation weights or inherit the owning group's current settings. Use hyr_list_sessions with sessionId to read roster IDs, available methods and current settings first. Attendance is separate from actual participation: sitting out creates no loss or zero. Session team assignments recalculate eligible matches from the whole night, including matches recorded before teams were chosen. Use confirm_match_teams with confirm:true only when a particular match had different actual teams; that explicit match correction stays fixed. Mixed-game totals are win/draw or normalized rankings, never raw scores summed across games.

Starts, ends or reopens a session in a group. This matters beyond bookkeeping: while a night is open, every match recorded in that group joins it — by you, by the person, or by anyone else in the group.

Keeps the picture of the night with the result: the scoresheet, the final board, the table. Call it with action "begin" and the file's exact byte length and SHA-256, and it answers with a short-lived upload address ON howyourank.com — never a storage vendor's — plus the two calls that follow: PUT the bytes there, then POST the finish URL. Nothing is attached until finish succeeds, and nothing is stored if the bytes do not match what you declared. This tool is for clients that can make an outbound HTTP request with a file body. If yours cannot, or its network policy blocks howyourank.com, say so plainly and point the person at the match page — that setting belongs to their AI account and this site cannot change it. Accepted formats: image/jpeg, image/png, image/webp, image/gif, up to 12 MB each. One opId per photo; for a set of photos, size and hash them all first and run a couple of uploads at a time, keeping each file's opId, address and finish call paired. A photo attached this way begins private, exactly as one the person adds themselves: it is visible to the match's group, never on a public share link. This tool cannot publish anything, change a match's visibility, or hand back an original.