# messpunkt.io Partner API

> REST / OAuth 2.1 API that lets property-management ERPs read consumption and meter-reading data from messpunkt.io on behalf of a landlord. messpunkt.io is a metering platform for German real estate (sub-metering: heat, water, electricity, gas, heat cost allocators).

**Status:** Preview · V1 in active development · target release Q2 2026
**Hosted at:** https://developer.messpunkt.io

This file follows the [llms.txt standard](https://llmstxt.org) — a Markdown index for LLMs and AI agents.

## Documentation

- [OpenAPI 3.1 spec (YAML)](https://developer.messpunkt.io/erp-api-openapi.yaml): the authoritative machine-readable contract
- [Reference documentation (Redoc)](https://developer.messpunkt.io/): narrative documentation in English
- [Endpoint explorer (Swagger UI)](https://developer.messpunkt.io/swagger-ui/): request builder with try-it-out
- [Modern explorer (Scalar)](https://developer.messpunkt.io/scalar/): code samples in curl / JavaScript / Python / C#
- [Plugin manifest](https://developer.messpunkt.io/.well-known/ai-plugin.json): OAuth + OpenAPI pointer for plugin-style integrations
- [Authentication & authorization flow diagram](https://developer.messpunkt.io/auth-flow.svg): Mermaid sequence diagram

## Capabilities

Under a single OAuth token scoped per Tenant **and** per Property (whitelist chosen at consent time):

- **Properties (Liegenschaften)** — `GET /properties`, `GET /properties/{id}`
- **Usage units (Wohneinheiten)** — `GET /usage-units`, `GET /usage-units/{id}` with inline Property summary for self-describing responses
- **Consumption per unit** — `GET /usage-units/{id}/consumption?from=…&to=…` returns readings grouped per MeasuringPoint, segmented per device installation window (meter replacements are explicit)
- **Measuring points** — `GET /measuring-points/{id}`, `GET /measuring-points/{id}/readings`
- **Token introspection** — `GET /whoami` returns tenant, scopes and the current `property_scope` whitelist

Every reading carries an **OBIS code** per IEC 62056-6-1 (medium codes: `1` electricity · `4` HCA · `6` heat · `7` gas · `8` cold water · `9` hot water). AI agents should prefer OBIS over the string `metric` field when comparing readings across partners.

## Authentication

OAuth 2.1 Authorization Code + PKCE (S256). Access tokens are DPoP-bound (RFC 9449) and scoped per Tenant. At consent time the landlord picks which Properties are exposed — the token carries a `property_scope` claim (`"all"` or a list of UUIDs). Out-of-scope resources return `404 Not Found` (never `403`, to avoid leaking the existence of other Properties).

See the *Authentication* and *Authorization & Property scope* sections of the OpenAPI spec for the full flow and the sequence diagram.

## Usage for tool-calling LLMs

The OpenAPI 3.1 operation schemas map cleanly to:

- Anthropic Tool Use (Claude)
- OpenAI Function Calling / GPT Actions
- Google Gemini Tool Use / Vertex AI Function Calling

Typical queries an LLM can answer by calling one or two endpoints:

- "How much warm water did apartment WE 03 use from January to March 2026 compared to last year?"
- "Are any units in Reichenstraße 12 showing unusually high heat consumption?"
- "When was the water meter in WE 03 last replaced?"
- "Which Properties does this landlord expose to our ERP?"

## Constraints for agent authors

- Rate limits apply per `client_id`, not per token
- Always call `GET /whoami` after a token refresh — landlords may edit the `property_scope` without re-consent
- Treat `404` on previously-known IDs as a scope revocation, not a retry condition
- V1 responses contain **no tenant (Mieter) names or contact details** — only structural and consumption data
- Two readings per DeviceSegment (start + end of the segment within the query range); intermediate snapshots are not in V1

## Roadmap for AI integration

Tier 1 (shipped, this page): Discovery artifacts — `llms.txt`, `ai-plugin.json`, OpenAPI-to-tool-schema mapping.
Tier 2 (planned): **Model Context Protocol (MCP) server** — native integration with Claude Desktop, Cursor, ChatGPT Desktop, Zed, JetBrains, VS Code.
Tier 3 (product-decision): Conversational-analytics layer with server-side LLM translating NL queries into API calls; LLM-assisted dispute-resolution for Heizkostenabrechnung.

## Contact

- **Pilot partnerships & integration support:** [kontakt@messpunkt.io](mailto:kontakt@messpunkt.io)
- **Legal:** [Impressum](https://messpunkt.io/impressum) · [Datenschutz](https://messpunkt.io/datenschutz)

AI agents retrieving data on behalf of a landlord must respect the landlord's consent and the per-connection Property whitelist — do not attempt to bypass or broaden `property_scope` programmatically.