Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.tryhoard.com/llms.txt

Use this file to discover all available pages before exploring further.

​
Agent permissions and safety

When an AI assistant has bearer-token access to your Hoard account, the question isn’t “is the assistant authenticated” — it’s “what’s this specific call about to do, and is that worth a human glance?” Asking Claude to “increase my sales” is fine; Claude responding by setting every multiplier to 0.001x is not. Hoard’s job is to make sure the second one can never happen, no matter how the conversation is framed. We do that with three layers, applied to every write action.

​
Layer 1: Permission grants

Permission grants are your policy for the assistant. Each kind of action has a mode:
ModeWhat it means
denyAssistant cannot do this at all. Hard stop.
always_askEvery call needs an explicit click-through, no matter how low-risk.
ask_for_mutationsReads run automatically; any change asks first. (This is the default.)
auto_low_riskLow and medium risk run automatically; high and critical ask first.
auto_unless_criticalOnly critical-risk calls ask first. Power-user mode.
Defaults err on the side of asking. Edit a pricing rule? Default is ask_for_mutations. Run a sale? Default is always_ask. Change account settings? Default is always_ask. You can tighten or loosen any of these per kind of action from Settings. For most sellers, the defaults are the right call — let the assistant read freely, ask before changes.

​
Layer 2: Risk scoring (per call)

Even with a permission grant, every write call runs through a server-side risk scorer that classifies it as low, medium, high, or critical based on the actual parameters of the call. The scorer is user-relative: a 25% multiplier change is “high risk” for a Stay Competitive seller (whose pricing wizard set the per-card change cap at 20%) but “medium risk” for a Lead the Market seller (cap 30%). The system uses what you told the pricing wizard you were comfortable with as the calibration point. What pushes risk up:
  • Larger multiplier changes
  • Turning off “never go down” on rules that cover many cards
  • Changing the price source
  • Repricing across more cards
  • Aggregate projected drop in your listed inventory value
  • Lots of recent activity in the same session (cumulative escalation)
When a call’s risk exceeds what your grant allows, the assistant returns the preview to you with a “confirm to proceed” link instead of committing. You click through (signed in, on hoard.tryhoard.com), Hoard issues a short-lived confirmation token, and the commit goes through.

​
Layer 3: Hard floors (unconditional)

These are server-side invariants every write must clear, no matter who’s calling — assistant, dashboard, API key, OAuth, anything. The assistant literally cannot construct a request that violates them. If it tries, the server returns a floor_violation error explaining which floor tripped and what to do about it. Active hard floors today: Absolute minimum: $0.01. No listed price can ever go below one cent. Server-side invariant, not user-tunable. Your per-card price floor. Defaults to $1.00 but customizable in your pricing preferences. No card lists below this regardless of what the rule says. Per-rule aggregate drop cap. Default 30%. A single rule application cannot drop your total listed inventory value by more than this percentage. Tunable per-user. The point: if you accidentally tell the assistant “discount everything by 40%,” the server stops it. Per-session aggregate drop cap. Default 20%, rolling 1-hour window. Cumulative across multiple calls in the same session — a series of “small” edits that together drop the store significantly will trip this even if no single edit was big enough on its own. Tunable per-user. Per-card clamps (inherited from your pricing rules). Your never_go_down setting, your change_cap_pct (max % move per sync), your hard_floor — these already gate every reprice your dashboard runs, and they continue to gate everything an assistant initiates. The agent doesn’t get to bypass anything you’ve configured for yourself.

​
The flow in practice

What it looks like end-to-end when you ask Claude to “raise my Rare/Mythic pricing rule from 1.05x to 1.15x”:
  1. Claude calls the preview endpoint with the proposed change.
  2. The server checks your grant for pricing.edit_rule (default: ask_for_mutations).
  3. The risk scorer runs against the actual numbers. A 1.05 → 1.15 change is a +9.5% multiplier move. On a “Stay Competitive” cap-20 seller, that’s low risk. On a more conservative cap-15 seller, it might be medium.
  4. Hard floors run. They project what your aggregate listed value becomes after the change. If the rule covers 200 cards and the projected aggregate change is +$80 (an increase, not a decrease), no floor trips.
  5. Because your grant is ask_for_mutations and the action IS a mutation, the server returns a plan with requires_confirmation: true.
  6. Claude shows you the preview: “200 cards affected, projected change +$80, low risk, requires confirmation. Click here to confirm.”
  7. You click the link, sign-in is already valid, you tap Confirm.
  8. The server issues a 60-second confirmation token. Claude commits with the token. The change applies.
  9. Your audit log gets a new row: “edited rule X, multiplier 1.05 → 1.15, committed by Claude assistant at 2026-05-11 03:42 UTC.”
If you’d set pricing.edit_rule to auto_low_risk and this call scored low, steps 5–7 are skipped — Claude commits in one round trip and tells you what just happened. If the same edit had been “set the multiplier to 5.0x,” the scorer would have flagged it critical, the floors might have tripped (a massive markup on an active rule can push some cards above sale-likely thresholds), and even with auto_unless_critical the call would have required confirmation.

​
Audit log

Every committed change, every rejected-by-floor attempt, every expired plan that timed out without confirmation — they all go in your audit log. You can review it via Settings, and an AI assistant can read it back to you on request (“show me everything you changed in the last week”). The audit row includes: what action, what risk score, who committed it, what the before/after state was, and which floor tripped if any.

​
Best practices

  • Leave the defaults alone for a couple of weeks. Watch what gets asked. After you see a pattern (Claude always asks before reprice rule edits, you always click yes), consider loosening that one namespace to auto_low_risk. Most sellers settle in within 2-3 weeks.
  • Set a per-card floor that reflects your actual minimum. The default is 1.00.Ifyou′dneverlistacardbelow1.00. If you'd never list a card below 0.25, leave it at 1.00—thecushionisyoursafetynet.Ifyougenuinelysellbulkcommonsat1.00 — the cushion is your safety net. If you genuinely sell bulk commons at 0.10, lower it.
  • If you run flash sales, expect more confirmations. Sales by their nature push risk up. The system will ask. That’s working as intended; click through.
  • Read the audit log when something feels off. It captures exactly what happened. If the assistant says it edited a rule and you can’t see the change, the audit log is the source of truth.

​
What’s NOT controlled by this

These are all outside the agent permissions system and have their own (older, stricter) controls:
  • Sync mode (autonomous vs confirm) — set via the pricing wizard or Settings
  • Pricing engine clamps (change_cap_pct, change_cap_mode) — set via the pricing wizard
  • Connected apps revocation — set via Settings → Connected apps
These controls remain dashboard-only. An assistant cannot loosen them on its own.