Archive a cache tree: make it read-only and hide it from metrecept_list_cache_trees, keeping every entry so it can be restored later; archived=false restores it to the status it had before (active or frozen). Use it to retire a finished experiment's tree without losing it. Not for a temporary write lock: use metrecept_freeze_cache_tree. Not for freeing storage: use metrecept_delete_cache_tree. Archived trees still serve hits, but writes, eviction, reset and freeze return 409 tree_archived, and they cannot be a fork parent or promote target. List them with include_archived=true. Idempotent, not billed, audit-logged. Errors: 409 cannot_archive_main, 404 tree_missing. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Make a read-only GET call to a registered third-party API through the gateway and return the vendor's response body, with a signed receipt that stores only a hash of path and query. Use it for authenticated vendor JSON APIs mid-session. Register the service first with metrecept_register_api_service. Not for public web pages: use metrecept_fetch_web_pages. path must sit under the service's allowed_path_prefix (e.g. prefix "/v1" allows "/v1/lookup"); query is sent as the URL query string. Pass the same session_id as your chat and fetch calls to group them into one metrecept_get_session_receipt receipt. Billed per call at the plan rate. Unknown service returns 404 service_not_found; vendor errors and prefix violations return JSON {"error", "status"}. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Send one user message to a model through the Metrecept gateway (OpenAI-compatible) and return the reply text; an exact repeat of a request is served from the tenant's cache. Use it for model answers, optionally grounded in public pages via fetch_urls. Not for the page content itself: use metrecept_fetch_web_pages. Start with model "mock" to test without an upstream key; pick real ids from metrecept_list_models. purpose only applies when fetch_urls is set; check allowed values with metrecept_get_fetch_policy. Pass one session_id across a run's chat, fetch and API calls, then read metrecept_get_session_receipt. Metered and receipted per call. Failures (bad model, missing BYOK key, refused fetch, rate limit) return JSON {"error", "status"}. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Delete a whole non-main cache tree: its metadata, digest index, references and the cached responses it owns. Use it to clean up after an experiment, typically after metrecept_manage_cache_tree promote. Find ids with metrecept_list_cache_trees. Not for a single entry: use metrecept_evict_cache_entry. Destructive and immediate, no undo; not billed. Refuses "main" (409 cannot_delete_main) and trees with children (409 tree_has_children; delete children first). Responses another tree references after a promote are kept until their TTL. A missing or already-deleted tree returns 404 tree_missing. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Evict one cached response from a cache tree by its request digest, so the next identical request in that tree is a fresh miss sent upstream and billed as a miss. Use it to drop a stale or wrong cached answer. Get the digest from metrecept_list_cache_entries. Not for removing a whole tree: use metrecept_delete_cache_tree. Ownership: eviction removes only this tree's own copy or reference. An entry inherited from a parent is untouched; evict it in the parent. If this tree owns the bytes, trees referencing them after a promote also lose the entry. Destructive and immediate, no undo; not billed. Errors: 404 tree_missing or entry_missing (also on a repeat), 409 tree_frozen, 400 invalid_digest. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Fetch public web pages through the Metrecept compliance filter and return redacted markdown or JSON context, metered and receipted. Use it when you need the page content itself. Not for a model answer grounded in pages: pass fetch_urls to metrecept_create_chat_completion. Not for an authenticated JSON API you hold a key for: use metrecept_call_api. Call metrecept_get_fetch_policy first to pick a valid purpose and stay within its character caps; a few URLs per call is the norm. Pass the same session_id you use on chat and API calls to group them into one metrecept_get_session_receipt receipt. Behaviour: the tenant must have accepted Terms/DPA at Checkout, otherwise the call is refused. robots.txt is respected (fail-closed), PII is redacted, and login walls, 401/403 and 402 pay-per-crawl refusals are honoured, never bypassed. Never cached. Failures return JSON {"error", "status"} with secrets redacted. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Freeze a cache tree so it keeps serving its cached responses but accepts no new writes, or unfreeze it (frozen=false) back to active. Use it to pin a known-good cache, for example a release branch's tree, while experiments continue in forks. Not for hiding or retiring a tree: use metrecept_archive_cache_tree. Not for removing it: use metrecept_delete_cache_tree. While frozen, misses are served upstream but not stored, eviction returns 409 tree_frozen and the tree cannot be a fork parent or promote target. Idempotent, not billed, audit-logged. Errors: 409 cannot_freeze_main, 409 tree_archived (restore it first), 404 tree_missing. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Read the web-fetch compliance policy enforced for this tenant: allowed purpose values, robots.txt and PII-redaction settings, whether Terms/DPA acceptance is required, and per-source and total character caps. Use it before metrecept_fetch_web_pages or a metrecept_create_chat_completion with fetch_urls, or after a refused fetch to see which rule applied. Not for third-party APIs: metrecept_call_api uses registered services instead. Read-only, not billed. A bad or missing key returns the gateway's 401 JSON error. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Read the tenant's cumulative savings ledger: cache hit ratio and hit tokens, estimated upstream spend avoided by cache replays, what Metrecept billed for hits and misses, net saving and ROI. Use it for the money view. Not for raw meters or plan: use metrecept_get_usage; for per-day meters use metrecept_get_usage_history. To share these numbers publicly use metrecept_publish_savings_receipt. Avoided-spend figures are list-price estimates (the response carries a disclaimer); billed figures are exact. Read-only, not billed, never cached. A bad or missing key returns the gateway's 401 JSON error. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Get one signed, aggregated receipt for a session: every chat completion, web fetch and API call tagged with the same session_id, with event count, total billed USD, cache hits/misses, fetch and API counts, first/last timestamps, the compact JWS and a verify_url. Use it at the end of an agent run and put verify_url in the PR, ticket or email the run produced; anyone can verify it in a browser, no account needed. Not for a public savings snapshot: use metrecept_publish_savings_receipt. Not for tenant totals: use metrecept_get_usage. Read-only, makes no upstream call, not billed. An unknown id returns event_count 0, not an error. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Read the tenant's live lifetime usage meters: requests, cache hit/miss tokens and ratio, web fetches, API calls, billed USD per meter and total, today's UTC-day values, plan, billing status and whether the soft web-fetch cap is lifted. Use it for 'how much have I used / what plan am I on'. Not for per-day trends: use metrecept_get_usage_history. Not for money saved: use metrecept_get_savings. Not for one run's signed record: use metrecept_get_session_receipt. Read-only, not billed, never cached. A bad or missing key returns the gateway's 401 JSON error. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Read the tenant's usage meters as a per-UTC-day series, oldest day first, plus window totals: requests, cache hit/miss tokens and USD, prewarm, web fetches, API calls, custody and statement meters, upstream cache tokens and billed_usd. Use it for trends or 'what did I spend each day'. Not for lifetime totals or plan: use metrecept_get_usage. Not for spend avoided: use metrecept_get_savings. Read from the durable per-day ledger; idle days are 0, nothing is estimated. Read-only, not billed. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

List the tenant's registered third-party API services: name, base URL, path prefix, auth header name and purpose. No credentials are stored, so none are returned. Use it to confirm a service name before metrecept_call_api. Register new ones with metrecept_register_api_service; remove with metrecept_unregister_api_service. Read-only, not billed, live, not paginated. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

List entries cached in one tree: request digest, model, token count, byte size and TTL remaining. Metadata only; never returns prompt or response content. Use it to inspect a tree or to get the digest that metrecept_evict_cache_entry needs. Get tree ids from metrecept_list_cache_trees. Page through with offset = previous offset + limit until fewer than limit entries come back. Read-only, not billed, live. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

List every cache tree (isolated exact-replay namespace) the tenant owns, always including the default "main", ordered main first then by creation time. All trees come back in one call. Each tree reports its status: active, frozen or archived. Use it to find a tree_id for the other cache tools. Not for a tree's contents: use metrecept_list_cache_entries. To create, fork or promote use metrecept_manage_cache_tree; to remove a non-main tree use metrecept_delete_cache_tree. Archived trees are hidden unless include_archived=true. Read-only, not billed, live. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

List model ids the gateway can route chat to (mock plus examples for OpenAI, Anthropic, Gemini, DeepSeek, Moonshot, Z.ai, Qwen, xAI) and the prefix routing table. Use it before metrecept_create_chat_completion to pick a model; any id under a routed prefix is forwarded verbatim. Not for which vendors are actually configured: use metrecept_list_providers. Static list, read-only, not billed. Non-mock models need your own upstream key (BYOK). Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Show which upstream vendors the gateway has configured and ready (mock, openai, anthropic and each OpenAI-compatible vendor), with BYOK header name and billing model. Use it to debug a failed metrecept_create_chat_completion or check a vendor is ready. Not for picking a model id: use metrecept_list_models. Reports key presence only; keys are never validated upstream or returned. Read-only, not billed, live. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Create, fork or promote a cache tree (an isolated exact-replay namespace). Use it to isolate cache for an experiment or PR: fork main, send chat calls into the fork, promote it back when good, then remove it with metrecept_delete_cache_tree. Not for listing trees: use metrecept_list_cache_trees. Not for deleting a tree or entry: use metrecept_delete_cache_tree or metrecept_evict_cache_entry. create and fork give the new tree an empty local index that reads its parent chain copy-on-write, so it serves parent entries by reference with zero bytes copied; its own new entries stay local. promote adds references to tree_id's own entries in the target tree (bytes_copied is always 0) and leaves the child intact; it never swaps trees, main stays the default and cannot itself be promoted. Not billed; audit-logged. Errors return ok=false with status and error: 409 tree_exists, 404 parent_missing, 404 tree_missing, 409 cannot_promote_main, 409 parent_frozen, 409 tree_archived or parent_archived, 400 invalid_cache_tree. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Mint one fresh signed Ed25519 receipt (compact JWS) of a chosen kind by making the smallest real gateway call that produces it, and return the receipt with its kid, iat and a verify_url. Use it to show or test receipt verification end to end, or to attach a real receipt to a demo or bug report. Not for a run you already made: use metrecept_get_session_receipt. Not for a public savings page: use metrecept_publish_savings_receipt. Each kind makes real calls billed as normal (cache_miss, finops, cache_bypass, web_fetch and api_call are metered; cache_hit bills one miss then a hit). Anyone can check verify_url in a browser against the public key directory. Errors come back as JSON {"error", ...}: no_api_service when kind api_call has no registered service, no_receipt when none of that kind came back. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Refresh an about-to-expire Anthropic prompt-cache breakpoint for a session with a one-token call, so the next real turn reads the cache instead of paying a fresh cache write. Use it from an idle timer when a long Claude conversation is about to sit past the cache TTL. Not for the gateway's own exact-replay cache (it never touches it): use metrecept_create_chat_completion. Not for OpenAI or other vendors, whose prompt caching is automatic. Sends your transcript and your upstream key exactly like a chat call; nothing is stored. Unbilled by the gateway (returns billed:false, billed_usd 0; the vendor still charges its own tokens) and audit-logged. Errors: 400 prewarm_unsupported_model for non-claude models, 400 cache_autopilot_disabled when the gateway has cache autopilot off, 401/402 for a missing upstream key. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Publish a public, shareable savings receipt: an immutable Ed25519-signed snapshot of current savings at metrecept.co.uk/r/, plus a README badge snippet. Use it when the user wants to share savings outside the tenant. Not for checking the numbers privately: use metrecept_get_savings (call it first to review). Not for a per-run record: use metrecept_get_session_receipt. Side effect: creates a public page that lives 90 days and shows only display_name, never the tenant id or key. Not billed. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Register or update a third-party API service so metrecept_call_api can make receipted GET calls to it. Use it once per vendor before metrecept_call_api; confirm with metrecept_list_api_services, remove with metrecept_unregister_api_service. Stores only the non-secret shape (base URL, path prefix, auth header name, purpose); the credential travels per call as metrecept_call_api's service_key and is never stored. Re-using a name overwrites that service. Private/internal base URLs are rejected. Not billed. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.

Unregister one of the tenant's third-party API services so metrecept_call_api can no longer reach it. Use it to retire a vendor integration; check exact names with metrecept_list_api_services. Not for changing settings: re-register the same name with metrecept_register_api_service. Destructive and immediate, no undo, though no credential is lost because none is stored. Later calls and repeat unregisters return 404 service_not_found; 404 feature_disabled means API passthrough is off. Not billed. Requires a Metrecept API key (METRECEPT_API_KEY env on stdio, or Authorization: Bearer on remote HTTP); results are scoped to that key's tenant only.