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.

HTTP Entry Errors

Request decoding, authentication, authorization, and routing failures return an HTTP error status and a JSON object with an English error string:

{"error":"invalid request body"}

Status	Meaning
400	Invalid JSON, rejected request fields, invalid parameters, or unsupported tenant headers.
401	Missing or invalid API credentials or Subject Token.
403	The credential does not allow the requested scope, tenant, project, or subject.
404	No matching API route (api not found).
413	The request body exceeds the endpoint’s size limit (request_body_too_large).
429	The ingest request rate limit was exceeded (rate_limit_exceeded).
500	An unexpected failure occurred before the response was sent (internal server error).
503	Authentication dependencies or required server configuration are unavailable. This is distinct from an invalid credential.

The entry-error response contains only the public message. Parser details and internal failure information are recorded in server logs. Ingest rejections have the additional fields documented on the single-event and batch pages. Business errors and their additional response fields are documented on each endpoint page.

Available APIs

• 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.
• Discard Usage Limit Plan Draft drops the unpublished draft revision and reverts the Plan to its published revision.
• 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.

Related endpoints

• Create Usage Limit Plan

• Get Usage Limit Plan

• Update Usage Limit Plan Draft

• Publish Usage Limit Plan

• Roll Back Usage Limit Plan

• List Usage Limit Plan Revisions

• Retry Failed Raw Event reprocesses one pending failure log with optional corrected business input.