Skip to main content

​
Hosted Billing & Metering

This page describes the contract between the open-source AMFS HTTP API / MCP server and the proprietary control plane (amfs-internal) that records usage and enforces quotas on SenseLab Cloud.

​
Ops Model

Operation classOps chargedExamples
Read-like1GET entry, search, list, explain (read path), MCP amfs_read, amfs_search, …
Write-like2POST write entry, record_context, MCP amfs_write, …
Outcome commit0commit_outcome / MCP amfs_commit_outcome (product choice; still logged)

​
HTTP Route → Ops

The authoritative matrix for the hosted gateway is maintained in amfs-internal (amfs_control_plane.metering — op_cost_for_request(method, path)). It mirrors amfs-http-server routes, for example:
  • GET /api/v1/entries/... → 1
  • POST /api/v1/entries/... → 2
  • POST /api/v1/outcomes → 0
  • GET /health → 0
Default for unmatched API paths: 1 op (conservative).

​
MCP Tool → Ops

Use classify_mcp_tool(tool_name) in the same module. Tools such as amfs_read, amfs_search, amfs_list → 1; amfs_write, amfs_record_context → 2; amfs_commit_outcome → 0.

​
Control Plane API

The hosted edge should call (server-side only, with X-AMFS-Internal-Key): POST /api/v1/internal/usage/record with JSON { "account_id": "<uuid>", "ops": <n> } Responses:
  • 200 — updated counts (ops_consumed, ops_remaining, …)
  • 402 — plan_required, quota_exceeded, or over limit; body includes upgrade_url / plan_comparison_url where applicable
Dashboard users receive usage hints via GET /api/v1/me plus response headers X-AMFS-Ops-Remaining, X-AMFS-Ops-Limit, and X-AMFS-Usage-Warning (80 / 95 / 100).