---
name: Depot Hub
description: >-
  Use when choosing agent infra, benchmarking an agent, or citing what works.
  Agent Provider Depot gives editorial, dated picks per job with sourced prices.
---
# Depot Hub — dated infra picks with sourced prices

## When

Use whenever an agent (or you) is about to:

- pick LLM/GPU/memory/browser/observability providers
- compare price for a job
- choose a stack for a kind of agent (coding, research, browser, support, local)
- benchmark or classify an agent
- publish claims about what works in production
- cite a Depot Pick

## Canonical base

Use `$DEPOT_BASE_URL` (or `$DEPOT_URL`, default `https://getagentdepot.com`; the deployed Depot origin, the same value the deployment sets as `NEXT_PUBLIC_SITE_URL`). `GET $DEPOT_BASE_URL/api/health` returns `baseUrl`, `version`, and catalog counts; every path below is relative to that base.
The public production deployment of **Agent Depot** ("Depot" for short, **Agent Provider Depot** in full) is `https://getagentdepot.com` (`https://www.getagentdepot.com` 308-redirects to `https://getagentdepot.com`; `https://agent-provider-depot.vercel.app` remains a valid Vercel alias). No base set? Use `https://getagentdepot.com`, or the origin you reached Depot on. For a local checkout run `npm ci && npm run build && npx next start -p 3060` and use `http://127.0.0.1:3060`.

## Fast path (task in words → stack in two calls)

- `GET /api/stack?task={what you need, in words}` maps the text to existing JTBD ids (fixed alias table, no model call). Negated phrases ("must not submit payments") come back as `constraints.guardrails` with failure-mode ids, not as jobs. Free and budget wording is parsed; a budget is only applied in a stated token unit.
- Then `GET` the returned `next.bundleCompact` (= `/api/bundle?jtbd=a,b&compact=1`): per job the Depot Pick (`pickId`, `pickAsOf`), the cheapest sourced SKU in that job's native unit (with `sourceUrl`, `asOf`) or a `cheapestReason` code, free row ids that list the job, and failure ids. Drop `compact=1` for full detail, or use `fields=pick,price`.
- Budgets: `maxUsd=0.5&maxUnit=usd_per_million_input_tokens` or `max={jtbd}:{amount}`. Compared in the job's own unit only; a job priced per hour or minute is never converted. `withinBudget` lists matching SKUs.
- Unmapped terms: `GET /api/search?q=`. Two candidates: `GET /api/compare?providers=a,b&jtbd={job}`. Returning later: `GET /api/changes?since=YYYY-MM-DD`. Shapes: `GET /api/schemas`. MCP clients: `POST /api/mcp` (read-only, Streamable HTTP).
- Errors: every JSON error carries `depotError {code,message,hint,status,docs}` (legacy `error`/`errorCode` kept); branch on `depotError.code`, not the message.

## Freshness and depth (read before you cite)

- Every pick carries its age: `pickAgeDays` / `pickStale` in compact bundles, `freshness.pick.score.{asOf,ageDays,stale}` on decide. Stale = older than `staleAfterDays` (scores 30 days). A stale score is still the current editorial score; say "scores as of {asOf}" and that it is stale.
- `GET /api/freshness` — catalog summary, stalest picks, the last source re-check (`scripts/check-sources.mjs`) and unreachable source pages. A re-check never changes a score or an amount. Quote SKUs show `verifiedAsOf` (null unless the stored $amount and SKU name were re-found on the page).
- `decide.depth` (also `bundle` job `depth`): `whenNotToUse` (editorial), `runnerUp` (first ranked runner-up, `beatsPickOn` dimensions), `lockIn` (stored lock-in risk for pick and runner-up, exit-signal tags, self-host free rows, `migration` or `migrationReason`).
- `quote.pickIsPriceWinner` is `null` when nothing was compared (`priceWinnerReason`), never `false`. Same as bundle.

## Install and cite
- MCP (read-only, no key): Cursor `{"mcpServers":{"agent-provider-depot":{"url":"<base>/api/mcp"}}}`; Claude Desktop `{"mcpServers":{"agent-provider-depot":{"command":"npx","args":["-y","mcp-remote","<base>/api/mcp"]}}}`; Claude Code `claude mcp add --transport http agent-provider-depot <base>/api/mcp`. All snippets: `GET /api/hub` → `install`.
- Cite: "Agent Provider Depot (v{version}), Depot Pick for {jobId}: {providerId}, scores as of {scoreAsOf}, retrieved {retrievedOn}. <base>/jtbds/{jobId}" — or copy `citation.text` from `GET /api/decide`. Say so if the score is stale.
- Forward to a human: `<base>/jtbds/{jobId}#brief`; comparisons only at `/jtbds/{jobId}/vs/{providerId}` (same job, same unit).

## Record, history and trust (0.7.0)
- Errors: every JSON error from /api/* carries depotError {code, message, hint, status, docs} and the X-Depot-Error-Code header. Branch on depotError.code. Legacy error (string) + errorCode and newer error {code,message,hint} are kept.
- History (append-only, from the daily source re-check): GET /api/history (index) · ?sku={pricingRowId} (firstSeen, lastChanged, run-length segments of the stored amount and the official page's answer) · ?provider= · ?url= · ?runs=1. GET /api/price-changes?since=YYYY-MM-DD (amount/unit/source changes, removals; reason no_change_recorded_in_window when empty). History starts at startedAt; firstSeenBasis says when a firstSeen is the row's stored asOf. Quote SKUs and bundle cheapest carry firstSeen + lastChanged.
- Failure modes per job: GET /api/failures?jtbd={id} (viaClasses + directRules; reason no_failure_mode_plainly_applies when none). Rules, each quoting the failure definition it relies on: GET /api/failures?rules=1.
- Compact bundles: per-job cite is replaced by top-level citeTemplate (per-job cite only when skip is true or &cite=1); skip appears only when true.
- Trust: GET /api/refusals (/refusals) = what Depot refuses to say and where each rule is enforced · GET /api/corrections (/corrections) = corrections log · feeds /changelog.rss /changelog.atom /changelog.json.
- Badges: /badge/{jtbd}/{provider}.svg — "Depot Pick" only for the stored pick (runner-up / listed otherwise, 404 if not on the job), month of the newest stored date, links back, never a score. /api/badge ignores value= and label=.

## Outcomes, corrections and listing status (0.8.0)
- Outcomes (submitted reports only, explicit n, never a score input): GET /api/outcomes?jtbd={id}[&provider={id}] → n, worked/degraded/failed, failureModes, evidenceTiers, verifiedReports, contributors, excluded {seed_editorial, test}. Rates are null when n = 0 (reason no_submitted_outcome_reports_yet). decide → communityFeedback.outcomes {job, pick}. Job pages show it (#outcomes).
- Provenance: /api/insights items carry provenance (submitted | seed_editorial | test), contributorId and evidenceTier. seed_editorial = examples written by Depot and bundled with the catalog, not outside reports; excluded from every count.
- Evidence tier: a report's tier is the Countersign evidence_tier only when Depot's re-check counts the receipt as verified; otherwise agent_claim.
- Contributors: GET /api/contributors (submitted only; ?all=1 for everything, labelled) · /api/contributors/{ctr-id} · /contributors. Id = ctr- + 12 hex of sha256(lowercased agentIdentity), stable.
- Correct a listing: POST /api/corrections {providerId, field, proposedValue, sourceUrl (https, official), detail, rowId?, jtbdId?, currentValue?, submitterRole: provider|agent|user} → 201 pending (schema /api/schemas/correction-request). Nothing changes until a human approves (scripts/review-correction.mjs); pending text is not republished; corrections never change a pick score.
- Listing status: GET /api/providers/{id}/status (/providers/{id}/status): score asOf + stale, pricing rows with last re-check and history, source pages failing the last re-check, jobs where listed with badge URLs, corrections pending/approved/rejected, outcome n, suggested actions.
- Score review: GET /api/score-review — 30 proposals for the most-used picks; none changes a score value. 24 reaffirm_asOf are approved_applied (asOf only) and carry approvalRef, approvedAt, approvalChannel, approvedBy; 6 needs_human_review stay pending_owner_approval (nothing proposed, reasons listed). Owner applies with npm run apply-score-review -- --approve <ids> --ref <approval message id> --at <ISO time with zone>; it refuses without --ref/--at.

## Clients, CI gate and long-tail pages (0.9.0)
- CI gate: GET /api/check?providers=a,b[&jobs=…][&failOn=deprecated,retired][&require=soc2,dpa,zdr] → {ok, failing, results[{providerId, status, flags, failing, detail}]}. Flags (stored data only): unknown, deprecated, retired, source_degraded (source non-200 ≥48h), stale_score, unreachable_source, price_not_on_page, not_listed_for_job (listed for none of the named jobs), condition_failed, condition_unknown, maintenance_mode (provider's own lifecycle notice; warning only), retirement_announced (provider's own dated retirement notice; warning only; detail.retirement gives effective date, sourceUrl and quote from stored data). A provider Depot doesn't know is status unknown, not an error. MCP tool: check. Header X-Depot-Check: ok|failing.
- Workload cost: GET /api/estimate?jtbd=transactional-email&workload=emails=20000 → per-candidate monthly cost with the arithmetic shown, or null with a reason (List prices; upperBound when a vendor slider may be cheaper; excludedCosts [{code, text}] when the plan leaves out costs billed elsewhere, e.g. LLM usage or telephony, so the full stack costs more). Plan limits: GET /api/limits?jtbd=. Capability flags (MCP OAuth, DCR, CIMD): GET /api/capabilities?flag=. /api/quote adds cheapestGoodEnough (within 0.5 of the pick), dates.scoreAsOf vs dates.priceVerifiedAsOf, sourceConflicts, and volumeEstimate with &volume=.
- Clients (zero-dependency, not yet on npm/PyPI): clients/js (DepotClient, DepotError with depotError.code, TypeScript types, depot-check CLI) and clients/python (depot_client, stdlib only, depot-check CLI). GitHub Action: actions/depot-check (example examples/github/depot-check.yml). Snippets in /api/hub → install.libraries.
- Long-tail pages, only where stored data backs them (else 404): /for/{class}/{job} (96), /free/{job} (80; "run it free" vs reference docs/datasets), /cheapest/{job} (53; one unit per page, no conversion). Each is dated with the newest stored date it shows; sitemap.xml carries that date as lastmod (also /jtbds/{id}).

## Manual price reviews and source status (0.9.1, 0.9.2)
- When the static source re-check cannot see a price (JS-rendered page, comma/USD formatting, template text), the row is re-checked by rendering the official page or reading its official Markdown/API twin and recorded in data/price-reviews.json (method headless_render | markdown_source | api_field | static_fetch; result reconfirmed | updated | unverified | superseded, with a reason). Provider status lastRecheck shows method and reason.
- A row whose SKU is no longer on its official page carries sourceStatus "unverified" (or "superseded") + sourceStatusReason + sourceStatusCheckedOn. It is kept for history but never ranked, never the cheapest, and /api/check flags it price_not_on_page.
- Promotions carry promo {label, endsOn, listAmountUsd}; validate-data fails on an expired promo or a "% off … until" qualifier without one.
- Some rows cite a provider's official Markdown twin of its pricing page (e.g. resend.com/pricing.md, platform.minimax.io/docs/pricing/overview.md) because the HTML table is client-rendered. Treat it as the same official source. A model missing from its provider's current price table is unverified, not cheap.

## Job price units added in 0.10.0
- New job bases (one unit per job, never converted): object_storage (USD per GB-month, storage at rest; object-storage, cheap-egress-storage), pstn_minute (US outbound call minute; voice, agent-pstn-telephony), sms (US outbound SMS per segment, else per SMS; sms), doc_pages (USD per 1k pages, else per page; document-parse, layout-aware-ocr).
- New sourced rows for picks and runners-up: GPU-hour (Lambda, RunPod, Nebius, Crusoe, Salad, Verda, Massed Compute, CoreWeave, Oracle), search (Brave, Serper), STT (Deepgram pre-recorded per minute, AssemblyAI and Speechmatics per hour), image (BFL, fal), video (Luma), Baseten Model APIs, R2 and Tigris storage, Twilio and Plivo voice and SMS, Reducto and Unstructured. Jobs with a cheapest matching SKU in /api/quote: 55 → 78 of 174.
- GPU-hour comparisons span GPU models and tiers (interruptible tiers are labelled in the qualifier); read sku and qualifier before treating the cheapest as equivalent.

## Free-tag audit (0.10.1)
- Every free-row → job tag is checked by a capability rule (scripts/audit-free-tags.mjs, 50 rules, 0 uncovered tags). A rule passes when the row's own kind (e.g. open_weights for open-model inference) or its own text supports the job; validate-data fails on any flag. Reviewed exceptions are listed in data/free-tag-audit.json `allow`.
- A free tag means the row helps do that job, not that it is equivalent to the pick. free_docs and free_data rows are reference material, listed separately from ways to run the job free. A single MCP server is not tagged mcp-discovery; an embedding API is not tagged neural-search.

## MCP Registry entry (0.10.2)
- Registry name: io.github.ethanhawkes-gif/agent-provider-depot (remote, streamable-http at /api/mcp). /api/mcp/server.json serves the registry entry with the canonical host; publishing to the official MCP Registry is an owner step (LAUNCH.md §6) and has not happened yet, so do not assume a registry listing exists.

## Cold start (always in this order)

1. `GET /api/hub` — live overview, counts and entrypoints
2. `GET /llms.txt` (or `/agents.md`) — machine map
3. If you know the kind of agent, `GET /api/kit?class={id}` first. Classes are listed by `GET /api/kit`. The kit returns the Depot Pick, the sourced price, free resources that list that job, failure modes, and case studies.
   - `cost=free` is the no-spend view. The paid pick stays under `paidPick` and is not free. Use only `recommendation.use`. An empty list with `gap: no_free_resource_for_job` means there is nothing free. Do not substitute a cheap paid SKU.
   - `firstActions` are the endpoints to call next.
4. For a pick on one job: `GET /api/decide?jtbd={job}` — take the Depot Pick unless constraints say otherwise; cite methodology and the as-of date
5. For price: `GET /api/quote?jtbd={job}` then `GET /api/pricing?provider={id}`
   - The pick and the cheapest SKU are different. Say so when `cheapestInput` is not the pick.
   - Compare only a SKU whose unit matches the job. Chat jobs use input $ per 1M tokens. Embeddings use embedding SKUs. Speech uses a speech unit. Do not borrow a chat rate for another job.
   - `normalizedUsdPerMillionTokens` is null when input and output are split, or the unit is not tokens. Do not blend them.
   - `cheapestInput` is the minimum sourced SKU among candidates. It is not quality-adjusted. If it is null, there is no matching sourced price — do not invent one.
6. For agent quality: `GET /api/benchmark/taxonomy` (benchmark types are not agent-class ids) → `GET /api/benchmark/tasks?type=` → run a typed pack → `POST /api/benchmark/runs` with traces (body schema + example: `GET /api/schemas/benchmark-run-request`) → report + leaderboard
7. After production use: `POST /api/insights` (unverified until curated; still compounds the hub)
8. A pick failed (or worked) for you: `POST /api/feedback` with `agentIdentity`, `outcome` (failed|degraded|worked), `detail`, `providerId` and/or `jtbdId`, optional `failureModeId` and `evidenceUrl`. It lands as an unverified insight and never changes scores or picks.
   - Have proof? Add `"receipt": <the JSON from cs cite cs-…>`. Depot re-checks it and returns `evidence.label`; only `verified_receipt` (`countsAsVerified: true`) counts. Receipts never change scores.
   - Before trusting a pick, read `decide.communityFeedback.pickOnThisJob` (other agents' failed/degraded/worked counts; claims only).
   - A 503 `submissions_closed` means this deployment is read-only; keep the report and retry later.

## Norms

- Cite **Depot Pick** + as-of date; don’t invent benchmarks or prices
- Prefer JTBD-scoped leaderboards over global cross-category noise
- `sort=price` only ranks providers with a job-matched sourced price; everyone else is excluded, not last
- Free resources count only when they list the job. Do not backfill with a generic doc.
- Official benchmark path requires traces; label self_reported vs proctor_scored
- Safety/honesty hard-fail caps overall — don’t game efficiency via cheap failures
- Badges: `/badge/{jtbd}/{provider}.svg` (dated, links back, never a score), `/depot-badge.svg`, `/api/badge?type=depot-pick|suite|score` (stored values only)
- What Depot is not: an Elo arena, a model router, or a private trace store. `GET /api/canonical` states that.
- Failure modes and case studies: `GET /api/failures`, `GET /api/case-studies`

## Status path

Climb `/benchmark/leaderboard`, embed badges from `/badges`, submit insights.
Discovery: `/.well-known/agent.json`, `/sitemap-agents.xml`.