API Overview

The MeterBase API provides programmatic access to utility rate intelligence, property management, tenant billing, Stripe subscription billing, audit logging, benchmarking, due diligence, and AI-powered bill analysis. The API exposes 63 endpoints across 15+ categories. All endpoints are served over HTTPS and return JSON responses.

Base URL

https://app.meterbase.io/api/v1

All paths in this documentation are relative to the base URL. For example, /auth/login resolves to https://app.meterbase.io/api/v1/auth/login.

Interactive Documentation

A live Swagger UI is available at:

https://app.meterbase.io/docs

You can authorize with your Bearer token or API key and execute requests directly from the browser.

---

Authentication

Every request (except /auth/register and /auth/login) must include one of the following headers:

Method	Header	Format
Bearer Token (JWT)	Authorization	Bearer <access_token>
API Key	X-API-Key	giq_xxxxxxxxxxxxxxxx

Bearer tokens are obtained from the login endpoint. API keys are created and managed through the API keys endpoints.

Which method to use?

Use Bearer tokens for short-lived browser sessions and frontend applications. Use API keys for server-to-server integrations, scripts, and CI/CD pipelines.

---

Rate Limits

Rate limits are enforced per authentication principal (user or API key) using a sliding window.

Tier	Requests / Minute	Requests / Day	Concurrent
Free	30	1,000	5
Pro	120	10,000	20
Enterprise	600	100,000	100

When a rate limit is exceeded, the API returns 429 Too Many Requests with the following headers:

Header	Description
X-RateLimit-Limit	Maximum requests allowed in the window
X-RateLimit-Remaining	Requests remaining in the current window
X-RateLimit-Reset	UTC epoch seconds when the window resets
Retry-After	Seconds to wait before retrying

---

Request Format

• Content-Type: application/json for all JSON request bodies.
• Content-Type: multipart/form-data for file uploads (bill PDFs, rate schedule PDFs, CSV imports).
• All request bodies must be valid JSON (when applicable).
• Dates use ISO 8601 format: YYYY-MM-DD or YYYY-MM-DDTHH:MM:SSZ.

---

Response Format

All successful responses return JSON with an appropriate HTTP status code.

Single resource:

{
  "id": "prop_abc123",
  "name": "Sunset Apartments",
  "address": "123 Main St",
  "created_at": "2026-01-15T10:30:00Z"
}

Collection (paginated):

{
  "items": [
    { "id": "prop_abc123", "name": "Sunset Apartments" },
    { "id": "prop_def456", "name": "Harbor View Plaza" }
  ],
  "total": 47,
  "page": 1,
  "per_page": 20,
  "pages": 3
}

---

Pagination

All list endpoints support pagination via query parameters:

Parameter	Type	Default	Description
page	integer	1	Page number (1-indexed)
per_page	integer	20	Items per page (max 100)

Example:

curl -H "Authorization: Bearer $TOKEN" \
  "https://app.meterbase.io/api/v1/pm/properties?page=2&per_page=50"

---

Error Format

All errors return a consistent JSON structure:

{
  "detail": "A human-readable description of the error."
}

For validation errors (422), the detail field contains an array of individual field errors:

{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "field required",
      "type": "value_error.missing"
    },
    {
      "loc": ["body", "password"],
      "msg": "ensure this value has at least 8 characters",
      "type": "value_error.any_str.min_length"
    }
  ]
}

---

HTTP Status Codes

Code	Meaning	When
200 OK	Success	GET, PATCH, and some POST requests
201 Created	Resource created	POST requests that create a resource
400 Bad Request	Malformed request	Invalid JSON, missing content type
401 Unauthorized	Auth failure	Missing, expired, or invalid token/key
404 Not Found	Resource not found	Invalid ID or resource does not exist
422 Unprocessable Entity	Validation error	Field-level validation failures
429 Too Many Requests	Rate limited	Exceeded tier rate limits
500 Internal Server Error	Server error	Unexpected failure on the server
503 Service Unavailable	Maintenance	Planned downtime or dependency outage

---

Versioning

The API is versioned via the URL path (/api/v1). Breaking changes will be introduced under a new version prefix (e.g., /api/v2). Non-breaking additions (new fields, new endpoints) may be added to the current version without notice.

Deprecation Policy

When a new API version is released, the previous version will remain available for at least 12 months. Deprecation notices are sent via email and appear in the X-API-Deprecation response header.

---

Endpoint Categories

Category	Prefix	Endpoints	Description
Authentication	/auth	5	Login, register, API keys, password reset
Properties & Portfolios	/pm	10	CRUD for properties and portfolios, dashboard stats
Bills	/bills	5	Upload, list, detail, AI analysis
Tenant Billing (RUBS)	/billing	5	Config, calculate, PMS billing, history
Stripe Billing	/billing/stripe	5	Checkout, portal, status, usage, webhooks
Tariffs & Rates	/tariffs	6	Search, detail, compare, rate schedules
Savings & Analysis	/savings	4	Analyze, portfolio-analyze, recommendations
Dashboard & Analytics	/pm/dashboard	3	Stats, cost-trend, global-analytics
Benchmarking	/pm/analytics	2	Benchmarks, rankings
Due Diligence	/pm/due-diligence	1	Acquisition cost modeling
Property Health	/pm/properties	1	Health scores (RAG status)
Audit Logs	/audit	1	Admin audit log viewer
AI Endpoints	/ai	4	Extract, analyze, compare, chat
Alerts	/alerts	3	List, read, dismiss
Bulk Import	/bulk-import	3	CSV property/bill import
Reports	/reports	3	Generate, list, download
Propexo (PMS)	/propexo	2	Sync, webhook

---

SDKs and Libraries

Language	Package
Python	pip install meterbase
JavaScript/TypeScript	npm install @meterbase/sdk

---

Support

For API-related questions, contact api-support@meterbase.io or visit the Community Forum.