API Overview

Use the API docs when you are wiring Meterry into your own backend systems.

These pages are kept separate from the product guides so API references, request examples, and integration contracts can grow without mixing into the main docs navigation. Each endpoint has its own page with request fields, examples, and response shape.

Base URL

All API endpoints use the following base URL:

https://api.meterry.com

Endpoints listed in these docs are relative to this base. For example, POST /v1/projects/:project_id/raw-events/:id/process resolves to https://api.meterry.com/v1/projects/:project_id/raw-events/:id/process.

Authentication

Meterry uses API keys for authentication. Each API key is scoped to a project and carries a set of permissions.

Send the key as a bearer token in the Authorization header:

Authorization: Bearer <api-key-secret>
Content-Type: application/json

You can create and manage API keys from the Portal under Project > API keys. Keys are shown only once at creation time — store the secret securely in your backend environment.

Never expose API keys in browser or mobile client code. All API calls should originate from a trusted backend service.

Available APIs

• List published Plans reads the server-owned catalog used by Pricing and Checkout.

• Read current tenant entitlement returns the active Plan, grant period, limits, usage, and features.

• Create Account creates the billing entity that owns wallets and usage routes.

• Bind Subject Route maps a usage subject to the billing account that should pay for it.

• List Subject Routes lists active usage-subject routes for a billing account.

• Create Usage Control Rule binds a usage subject to a billing account and configures range limits.

• List Usage Control Rules lists usage-control routes and range limits for a billing account.

• List Usage Limit Plans lists reusable Plans with lifecycle filters, server-side search, and pagination.

• Get Subject Realtime Limits reads all realtime limit windows for one subject in a single call.

• Reset Usage Limits creates a scoped realtime limit reset boundary for a project, account, Plan, or subject route.

• Archive Usage Limit Plan hides a Plan from active lists while preserving existing route bindings.

• Restore Usage Limit Plan returns an archived Plan to active lists and route selectors.

• Create Wallet creates a currency wallet for an account.

• Credit Wallet adds balance to a wallet with optional idempotency.

• Grant Voucher grants voucher funds to a billing account and currency.

• List Voucher Grants lists issued vouchers and remaining voucher balances for an account.

• Revoke Voucher Grant revokes a voucher and removes its remaining active funds.

• Get Realtime Wallet Amount reads realtime account funds by account or subject route.

• Create Rule Set creates extractor and pricing rule set drafts.

• List Rule Sets lists extractor and pricing rule sets in a project.

• Get Rule Set reads the current runtime-visible rule set version.

• List Rule Set Versions lists draft and published version history.

• Get Rule Set Version reads one draft or published history entry.

• Update Rule Set Draft creates or updates the next editable draft version.

• Publish Rule Set publishes the current draft version.

• Rollback Rule Set switches runtime back to a previous published version.

• Delete Rule Set Draft discards the current draft.

• Test Rules dry runs extractor and pricing rules against raw usage JSON.

• Ingest Usage Event submits raw usage JSON for extraction, rating, and analytics.

• List Usage Events queries processed usage events.

• List Usage Event Details queries usage events together with charge items.

• List Usage Metrics lists metrics from published extractor rule sets for query selectors.

• List Processing Failures queries Event recovery rows for raw events that were not consumed cleanly.

• Summarize Processing Failures aggregates Event recovery rows by reason, subject, and extractor.

• Analysis Query returns chart-ready grouped series for Analysis boards and is the recommended base for new integrations.

• Aggregate Usage is the legacy flat grouped-row query. Use it only if you still need the older response shape.

• Query Bills returns account-filtered usage quantities and amounts with cursor pagination and requires an explicit metric list.