{
  "components": {
    "parameters": {
      "AcceptLanguage": {
        "description": "The caller's languages by preference, used when lang is not sent.",
        "in": "header",
        "name": "Accept-Language",
        "required": false,
        "schema": {
          "example": "pt-MZ,pt;q=0.9,en;q=0.5",
          "type": "string"
        }
      },
      "FirstRunToken": {
        "description": "Opaque run token from an earlier progress or next-steps response. It joins this request's first-use events to one run and carries no identity.",
        "in": "header",
        "name": "X-First-Run-Token",
        "required": false,
        "schema": {
          "type": "string"
        }
      },
      "IdempotencyKey": {
        "description": "Makes the shift command safe to retry. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 7 days. A completed success is stored and returned again with its original status and body, with the response header Idempotent-Replayed: true and no second transition. The same key on a different request (body, path, or caller) is refused with 409 Conflict. A refusal (4xx) or a server error (5xx) is never stored, so the same key can be sent again with the corrected values. Omitting the header keeps the behaviour without retry protection.",
        "in": "header",
        "name": "Idempotency-Key",
        "required": false,
        "schema": {
          "maxLength": 255,
          "minLength": 1,
          "type": "string"
        }
      },
      "IntegrationCategory": {
        "description": "Return only integrations of this category: payment, identity, notification, smart_meter, gis, scada, document_store, accounting or erp.",
        "in": "query",
        "name": "category",
        "schema": {
          "enum": [
            "payment",
            "identity",
            "notification",
            "smart_meter",
            "gis",
            "scada",
            "document_store",
            "accounting",
            "erp"
          ],
          "type": "string"
        }
      },
      "IntegrationHealth": {
        "description": "Return only integrations whose last reported health is unknown, healthy, degraded or unavailable.",
        "in": "query",
        "name": "health",
        "schema": {
          "enum": [
            "unknown",
            "healthy",
            "degraded",
            "unavailable"
          ],
          "type": "string"
        }
      },
      "IntegrationStatus": {
        "description": "Return only integrations in this status: active, suspended or disabled.",
        "in": "query",
        "name": "status",
        "schema": {
          "enum": [
            "active",
            "suspended",
            "disabled"
          ],
          "type": "string"
        }
      },
      "NotificationEventType": {
        "description": "Exact event type that produced the intent; returns only intents with this event type.",
        "in": "query",
        "name": "event_type",
        "schema": {
          "type": "string"
        }
      },
      "OrganizationStatus": {
        "description": "Only return organizations in this status: active, suspended or closed.",
        "in": "query",
        "name": "status",
        "schema": {
          "enum": [
            "active",
            "suspended",
            "closed"
          ],
          "type": "string"
        }
      },
      "PageAfter": {
        "description": "Opaque cursor returned by the previous page.",
        "in": "query",
        "name": "after",
        "schema": {
          "type": "string"
        }
      },
      "PageLimit": {
        "description": "Maximum resources to return (default 20, maximum 100).",
        "in": "query",
        "name": "limit",
        "schema": {
          "maximum": 100,
          "minimum": 1,
          "type": "integer"
        }
      },
      "PlanLang": {
        "description": "The language to answer plan text in, as a language tag (pt, en, pt-MZ). It wins over Accept-Language. A language without a translation falls back to the plan's default text.",
        "in": "query",
        "name": "lang",
        "required": false,
        "schema": {
          "example": "en",
          "type": "string"
        }
      },
      "Search": {
        "description": "Resource-specific text search.",
        "in": "query",
        "name": "q",
        "schema": {
          "type": "string"
        }
      },
      "SearchLimit": {
        "description": "Maximum results per type (default 5, larger values are clamped to 20).",
        "in": "query",
        "name": "limit",
        "schema": {
          "maximum": 20,
          "minimum": 1,
          "type": "integer"
        }
      },
      "SearchQuery": {
        "description": "Search text, trimmed before use.",
        "example": "maria",
        "in": "query",
        "name": "q",
        "required": true,
        "schema": {
          "maxLength": 100,
          "minLength": 2,
          "type": "string"
        }
      },
      "ServiceAreaStatus": {
        "description": "Returns only service areas with this exact status, for example active; omit it to return all.",
        "in": "query",
        "name": "status",
        "schema": {
          "type": "string"
        }
      },
      "StockIdempotencyKey": {
        "description": "Makes an inventory write safe to retry, for field issues replayed from offline phones. 1 to 255 visible ASCII characters, scoped to the tenant and endpoint and kept for 30 days. A completed write is stored with its response in the same transaction and returned again with its original status and body and the header Idempotent-Replayed: true, recording nothing twice. The same key on a different request (body, path or caller) is refused with 409 idempotency_conflict. A refusal is never stored.",
        "in": "header",
        "name": "Idempotency-Key",
        "required": false,
        "schema": {
          "maxLength": 255,
          "minLength": 1,
          "type": "string"
        }
      },
      "UtilityKind": {
        "description": "Only return utilities of this kind: authority, municipal, regional, national, rural, private or industrial.",
        "in": "query",
        "name": "utility_kind",
        "schema": {
          "enum": [
            "authority",
            "municipal",
            "regional",
            "national",
            "rural",
            "private",
            "industrial"
          ],
          "type": "string"
        }
      }
    },
    "schemas": {
      "AcceptInvitationRequest": {
        "properties": {
          "full_name": {
            "description": "Required when the invitation creates a new account without a name",
            "type": "string"
          },
          "password": {
            "description": "Existing user's password, or the password for a new account",
            "type": "string"
          },
          "token": {
            "type": "string"
          }
        },
        "required": [
          "token",
          "password"
        ],
        "type": "object"
      },
      "AcceptServiceRequestInput": {
        "properties": {
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "notes": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Account": {
        "properties": {
          "account_number": {
            "type": "string"
          },
          "billing_entity_id": {
            "type": "string"
          },
          "closed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "opened_at": {
            "format": "date-time",
            "type": "string"
          },
          "permissions": {
            "description": "Present only in consumer responses and lists the authenticated identity's permissions for this account.",
            "items": {
              "enum": [
                "account.read",
                "invoice.read",
                "payment.create",
                "reading.create",
                "ticket.create",
                "connection.manage",
                "member.invite"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "property_address": {
            "description": "Address line of the referenced property. Omitted when unknown.",
            "type": "string"
          },
          "property_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "suspended",
              "closed"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "tenant_slug": {
            "description": "The utility's slug, so a client can brand the account. Omitted when unknown.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "customer_id",
          "property_id",
          "account_number",
          "billing_entity_id",
          "status"
        ],
        "type": "object"
      },
      "AccountInvitation": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "channel": {
            "enum": [
              "phone",
              "email"
            ],
            "type": "string"
          },
          "code": {
            "description": "Present only in the creation response, for the staff member who created the invitation; never returned by listings or logged. The code is also delivered to the recipient by e-mail or text message.",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "permissions": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "recipient": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "accepted",
              "revoked",
              "expired"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountInvitationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AccountInvitation"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountLink": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "membership",
              "request"
            ],
            "type": "string"
          },
          "permissions": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "enum": [
              "active",
              "pending",
              "rejected"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountLinkList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AccountLink"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "AccountLinkRequest": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "identity_id": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "approved",
              "rejected",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountLinkRequestPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AccountLinkRequest"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountLinkResult": {
        "properties": {
          "link": {
            "$ref": "#/components/schemas/AccountLink"
          },
          "message": {
            "type": "string"
          },
          "request": {
            "$ref": "#/components/schemas/AccountLinkRequest"
          },
          "status": {
            "enum": [
              "linked",
              "pending"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountMove": {
        "description": "A request to move an account and its subtree under another parent.",
        "properties": {
          "account_id": {
            "description": "Account being moved, together with its descendants.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Move identifier (prefixed \"amv_\").",
            "example": "amv_01JD5Q0K6R3C9W2N7Y4T8B1M5X",
            "type": "string"
          },
          "previous_parent_id": {
            "description": "Parent at the time of the request; empty when the account was a root.",
            "type": "string"
          },
          "source_consented_at": {
            "description": "When the current parent consented.",
            "format": "date-time",
            "type": "string"
          },
          "source_consented_by": {
            "description": "Person who requested the move on behalf of the current parent.",
            "type": "string"
          },
          "status": {
            "description": "pending until the destination approves, then completed.",
            "enum": [
              "pending",
              "completed"
            ],
            "type": "string"
          },
          "target_consented_at": {
            "description": "When the destination approved; null while pending.",
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "target_consented_by": {
            "description": "Person who approved the move for the destination; empty while pending.",
            "type": "string"
          },
          "target_parent_id": {
            "description": "Requested new parent; empty when the move detaches the account as a root.",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "account_id",
          "previous_parent_id",
          "target_parent_id",
          "source_consented_by",
          "source_consented_at",
          "target_consented_by",
          "target_consented_at",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "AccountMoveList": {
        "properties": {
          "data": {
            "description": "Pending moves, oldest first.",
            "items": {
              "$ref": "#/components/schemas/AccountMove"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "AccountPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Account"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "AccountRelationship": {
        "properties": {
          "agreement_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "from_account_id": {
            "type": "string"
          },
          "from_account_name": {
            "type": "string"
          },
          "grants": {
            "items": {
              "$ref": "#/components/schemas/AccountRelationshipGrant"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "active",
              "revoked",
              "expired"
            ],
            "type": "string"
          },
          "to_account_id": {
            "type": "string"
          },
          "to_account_name": {
            "type": "string"
          },
          "type": {
            "enum": [
              "operations",
              "reseller",
              "regulator"
            ],
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountRelationshipGrant": {
        "properties": {
          "action": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "role": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AccountRelationshipPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AccountRelationship"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "AccountTreeEntry": {
        "description": "One account in the signed-in person's accessible-account tree. Ancestor entries (direct false and no membership) only place other entries in the tree and grant no access.",
        "properties": {
          "account_type": {
            "description": "Kind of account, for example utility or organization.",
            "example": "utility",
            "type": "string"
          },
          "direct": {
            "description": "True when the person holds a membership in this account itself.",
            "type": "boolean"
          },
          "id": {
            "description": "Account identifier.",
            "type": "string"
          },
          "inherited": {
            "description": "True when access comes from an inherited grant of a membership in an ancestor account.",
            "type": "boolean"
          },
          "membership_id": {
            "description": "Membership that gives the person access. For inherited access it is the source membership in the ancestor account.",
            "type": "string"
          },
          "name": {
            "description": "Account display name.",
            "example": "Northern Water",
            "type": "string"
          },
          "parent_id": {
            "description": "Parent account in the ownership tree; absent for a root.",
            "type": "string"
          },
          "relationship_access": {
            "description": "True when access comes from a consented relationship with another account.",
            "type": "boolean"
          },
          "roles": {
            "description": "Roles the person holds through this entry; empty for ancestor entries.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scopes": {
            "description": "For inherited access, the scopes the grant allows in this account.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "source_account_id": {
            "description": "For inherited access, the ancestor account whose membership grants it.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "account_type",
          "name",
          "roles",
          "direct"
        ],
        "type": "object"
      },
      "AccountTreeList": {
        "properties": {
          "data": {
            "description": "Accessible accounts and the ancestor entries that arrange them.",
            "items": {
              "$ref": "#/components/schemas/AccountTreeEntry"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "AddWorkOrderMaterialLinesRequest": {
        "properties": {
          "kit_id": {
            "type": "string"
          },
          "materials": {
            "items": {
              "$ref": "#/components/schemas/WorkOrderMaterialInput"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "Alarm": {
        "properties": {
          "acknowledged_at": {
            "format": "date-time",
            "type": "string"
          },
          "acknowledged_by": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "last_observed_at": {
            "format": "date-time",
            "type": "string"
          },
          "opened_at": {
            "format": "date-time",
            "type": "string"
          },
          "peak_value": {
            "type": "number"
          },
          "resolution_code": {
            "description": "Stable code of a resolution the server wrote (alarm.auto_cleared); clients word it and fall back to resolution_notes. Absent for notes people typed.",
            "type": "string"
          },
          "resolution_notes": {
            "type": "string"
          },
          "resolved_at": {
            "format": "date-time",
            "type": "string"
          },
          "rule_id": {
            "type": "string"
          },
          "sample_id": {
            "type": "string"
          },
          "sensor_id": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "status": {
            "enum": [
              "open",
              "acknowledged",
              "resolved"
            ],
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "AlarmList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Alarm"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AlarmRule": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "clear_threshold": {
            "type": "number"
          },
          "comparison": {
            "enum": [
              "above",
              "below"
            ],
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "notify_phones": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "parameter": {
            "type": "string"
          },
          "sensor_id": {
            "type": "string"
          },
          "severity": {
            "enum": [
              "critical",
              "warning",
              "info"
            ],
            "type": "string"
          },
          "source": {
            "enum": [
              "telemetry",
              "quality"
            ],
            "type": "string"
          },
          "threshold": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "AlarmRuleList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AlarmRule"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ApproveInventoryStocktakeRequest": {
        "properties": {
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "type": "object"
      },
      "AssetStatus": {
        "enum": [
          "operational",
          "maintenance",
          "offline",
          "decommissioned"
        ],
        "type": "string"
      },
      "AssetType": {
        "enum": [
          "source",
          "treatment_plant",
          "reservoir",
          "pump_station",
          "pipe",
          "valve",
          "hydrant",
          "dma",
          "junction",
          "customer_tap"
        ],
        "type": "string"
      },
      "AttentionItem": {
        "properties": {
          "count": {
            "format": "int64",
            "type": "integer"
          },
          "kind": {
            "enum": [
              "applications_review",
              "invoices_overdue",
              "subscriptions_ending",
              "jobs_dead",
              "collectors_attention",
              "connectors_down",
              "tenants_suspended",
              "plan_limit_near"
            ],
            "type": "string"
          },
          "oldest_at": {
            "format": "date-time",
            "type": "string"
          },
          "severity": {
            "enum": [
              "critical",
              "warning",
              "info"
            ],
            "type": "string"
          },
          "target": {
            "description": "Client route; clients validate it against their own routes",
            "type": "string"
          }
        },
        "required": [
          "kind",
          "count",
          "severity",
          "target"
        ],
        "type": "object"
      },
      "AttentionReport": {
        "properties": {
          "items": {
            "items": {
              "$ref": "#/components/schemas/AttentionItem"
            },
            "type": "array"
          },
          "partial": {
            "description": "True when a source failed and its items are missing",
            "type": "boolean"
          }
        },
        "required": [
          "items",
          "partial"
        ],
        "type": "object"
      },
      "AuditEvent": {
        "properties": {
          "action": {
            "description": "Stable action code in English",
            "type": "string"
          },
          "actor_id": {
            "type": "string"
          },
          "actor_name": {
            "description": "Display label of the actor; the person's name when known, Sistema for a system actor. Not part of the hash chain.",
            "type": "string"
          },
          "actor_type": {
            "type": "string"
          },
          "details": {
            "type": "object"
          },
          "hash": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "ip_address": {
            "type": "string"
          },
          "prev_hash": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "summary": {
            "description": "Human-readable description in the reader's locale (pt-MZ by default), derived from the action and resource when read; the fallback for summary_code; not part of the hash chain",
            "type": "string"
          },
          "summary_code": {
            "description": "Stable code clients translate as audit.<code>: the action when known, change.<resource_type>, or change",
            "type": "string"
          },
          "summary_params": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values for the translated summary, such as reference",
            "type": "object"
          },
          "tenant_id": {
            "type": "string"
          },
          "timestamp": {
            "format": "date-time",
            "type": "string"
          },
          "user_agent": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AuditEventPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AuditEvent"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AuditExportVerification": {
        "properties": {
          "valid": {
            "description": "True when this server issued the signature for this digest and the caller's tenant.",
            "example": true,
            "type": "boolean"
          }
        },
        "required": [
          "valid"
        ],
        "type": "object"
      },
      "AuditSiemDestination": {
        "description": "An audit event destination. Credentials are never returned; the has_* flags report whether each one is stored.",
        "properties": {
          "aws_access_key_id": {
            "description": "Access key ID (cloudwatch only).",
            "type": "string"
          },
          "created_at": {
            "description": "When the destination was created.",
            "format": "date-time",
            "type": "string"
          },
          "enabled": {
            "description": "Whether events are delivered.",
            "type": "boolean"
          },
          "endpoint_url": {
            "description": "Receiving URL.",
            "type": "string"
          },
          "format": {
            "description": "Event encoding.",
            "enum": [
              "cloudevents",
              "cef"
            ],
            "type": "string"
          },
          "has_auth_header": {
            "description": "Whether an auth_header credential is stored.",
            "type": "boolean"
          },
          "has_aws_secret": {
            "description": "Whether a secret access key is stored.",
            "type": "boolean"
          },
          "has_secret": {
            "description": "Whether a signing secret is stored.",
            "type": "boolean"
          },
          "id": {
            "description": "Destination identifier.",
            "example": "sie_01JD3X8Q7M2N4P5R6S7T8V9W0X",
            "type": "string"
          },
          "index": {
            "description": "Index name (elastic only).",
            "type": "string"
          },
          "log_group": {
            "description": "Log group (cloudwatch only).",
            "type": "string"
          },
          "log_stream": {
            "description": "Log stream (cloudwatch only).",
            "type": "string"
          },
          "name": {
            "description": "Display name.",
            "type": "string"
          },
          "provider": {
            "description": "Delivery adapter.",
            "enum": [
              "webhook",
              "splunk",
              "datadog",
              "cloudwatch",
              "elastic"
            ],
            "type": "string"
          },
          "region": {
            "description": "Cloud region (cloudwatch only).",
            "type": "string"
          },
          "tenant_id": {
            "description": "Tenant whose audit events are delivered.",
            "example": "tenant_alpha",
            "type": "string"
          },
          "updated_at": {
            "description": "When the destination was last changed.",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "AuditSiemDestinationCreate": {
        "description": "A destination that receives the tenant's audit events in real time. auth_header, secret and aws_secret_access_key are write-only: they are encrypted at rest and never returned. Unknown fields are rejected.",
        "properties": {
          "auth_header": {
            "description": "Credential sent with each delivery (as the Authorization header, or the provider's API key header). With provider splunk or elastic, a value without a space gets the provider's scheme prefix. Write-only.",
            "type": "string",
            "writeOnly": true
          },
          "aws_access_key_id": {
            "description": "Access key ID, required for cloudwatch.",
            "type": "string"
          },
          "aws_secret_access_key": {
            "description": "Secret access key, required for cloudwatch. Write-only.",
            "type": "string",
            "writeOnly": true
          },
          "enabled": {
            "description": "Whether events are delivered. Defaults to true.",
            "type": "boolean"
          },
          "endpoint_url": {
            "description": "Receiving URL; must be a public https address. Required, except for cloudwatch, where it defaults to the regional logs endpoint.",
            "example": "https://siem.example.com/ingest",
            "format": "uri",
            "type": "string"
          },
          "format": {
            "description": "Event encoding. Defaults to cloudevents.",
            "enum": [
              "cloudevents",
              "cef"
            ],
            "type": "string"
          },
          "index": {
            "description": "Index name, required for elastic.",
            "type": "string"
          },
          "log_group": {
            "description": "Log group, required for cloudwatch.",
            "type": "string"
          },
          "log_stream": {
            "description": "Log stream, required for cloudwatch.",
            "type": "string"
          },
          "name": {
            "description": "Display name. Must not be blank.",
            "example": "Security operations",
            "type": "string"
          },
          "provider": {
            "description": "Delivery adapter. Defaults to webhook.",
            "enum": [
              "webhook",
              "splunk",
              "datadog",
              "cloudwatch",
              "elastic"
            ],
            "type": "string"
          },
          "region": {
            "description": "Cloud region, required for cloudwatch (for example eu-west-1).",
            "example": "eu-west-1",
            "type": "string"
          },
          "secret": {
            "description": "Shared secret used to sign each delivered body with HMAC-SHA256 in a signature header. Write-only.",
            "type": "string",
            "writeOnly": true
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "AuditSiemDestinationList": {
        "description": "The tenant's audit event destinations.",
        "properties": {
          "destinations": {
            "description": "Every destination of the tenant, without credentials.",
            "items": {
              "$ref": "#/components/schemas/AuditSiemDestination"
            },
            "type": "array"
          }
        },
        "required": [
          "destinations"
        ],
        "type": "object"
      },
      "AuditSiemTestResult": {
        "description": "Confirmation that the destination accepted a test event.",
        "properties": {
          "message": {
            "description": "Human-readable confirmation.",
            "example": "Test event dispatched successfully",
            "type": "string"
          },
          "status": {
            "description": "Always ok.",
            "example": "ok",
            "type": "string"
          }
        },
        "required": [
          "status",
          "message"
        ],
        "type": "object"
      },
      "AuthContext": {
        "properties": {
          "account_id": {
            "description": "Canonical account targeted by this membership or consent-derived context; legacy context identifiers remain during the compatibility period",
            "type": "string"
          },
          "accounts": {
            "items": {
              "$ref": "#/components/schemas/LinkedConsumerAccount"
            },
            "type": "array"
          },
          "acting_organization_id": {
            "description": "Organization whose grant provides this context",
            "type": "string"
          },
          "agreement_id": {
            "description": "Agreement that provides this context, when applicable",
            "type": "string"
          },
          "capabilities": {
            "additionalProperties": {
              "enum": [
                "inactive",
                "pending",
                "active",
                "restricted"
              ],
              "type": "string"
            },
            "type": "object"
          },
          "grant_expires_at": {
            "description": "Expiry of the context grant, when applicable",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Membership or consent-derived context identifier used to switch context",
            "type": "string"
          },
          "initials": {
            "description": "Two-letter account initials computed by the server for consistent client rendering",
            "maxLength": 2,
            "minLength": 1,
            "type": "string"
          },
          "kind": {
            "description": "How the person reaches the context; organization means access is derived from an active organization account grant",
            "enum": [
              "member",
              "organization",
              "agreement",
              "support"
            ],
            "type": "string"
          },
          "last_used_at": {
            "description": "Last time this person used the context; used to order recent contexts",
            "format": "date-time",
            "type": "string"
          },
          "mode": {
            "enum": [
              "live",
              "sandbox"
            ],
            "type": "string"
          },
          "organization": {
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "type": {
                "type": "string"
              },
              "visible_accounts": {
                "description": "Accounts in this organization that the signed-in person can open",
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "id",
              "name",
              "visible_accounts"
            ],
            "type": "object"
          },
          "organization_id": {
            "type": "string"
          },
          "organization_name": {
            "type": "string"
          },
          "parent_tenant_id": {
            "description": "Parent live tenant for a sandbox",
            "type": "string"
          },
          "roles": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "sandbox_name": {
            "description": "Server-provided sandbox display name",
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "tenant_id": {
            "type": "string"
          },
          "tenant_name": {
            "type": "string"
          },
          "tenant_slug": {
            "description": "The utility's slug, for GET $PUBLIC_API/branding?tenant=<slug>; set whenever tenant_id is",
            "type": "string"
          },
          "type": {
            "enum": [
              "platform",
              "tenant",
              "organization",
              "consumer"
            ],
            "type": "string"
          },
          "workspace_state": {
            "enum": [
              "sandbox",
              "sandbox_only",
              "unverified",
              "verifying",
              "live",
              "restricted",
              "suspended",
              "closed"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "type",
          "initials",
          "roles",
          "scopes"
        ],
        "type": "object"
      },
      "AuthSession": {
        "properties": {
          "access_token": {
            "description": "Short-lived JWT signed with the installation signing key",
            "type": "string"
          },
          "active_context": {
            "$ref": "#/components/schemas/AuthContext"
          },
          "contexts": {
            "items": {
              "$ref": "#/components/schemas/AuthContext"
            },
            "type": "array"
          },
          "dev_code": {
            "description": "Verification code echoed only when the server runs in development mode",
            "type": "string"
          },
          "expires_in": {
            "description": "Access token lifetime in seconds",
            "type": "integer"
          },
          "refresh_token": {
            "description": "Opaque rotating refresh token",
            "type": "string"
          },
          "token_type": {
            "enum": [
              "Bearer"
            ],
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserProfile"
          },
          "verification_delivery_failed": {
            "description": "Set on signup when the verification code could not be sent. The account exists; request the code again with the verify endpoints.",
            "type": "boolean"
          }
        },
        "required": [
          "access_token",
          "token_type",
          "expires_in",
          "refresh_token",
          "user",
          "active_context",
          "contexts"
        ],
        "type": "object"
      },
      "AutomationAction": {
        "properties": {
          "delay_minutes": {
            "description": "Minutes after the previous step",
            "type": "integer"
          },
          "params": {
            "description": "send_notification: event_type, template_key, recipient_type, recipient_id, channels (email, in_app), message and in_app_title (the default text, in the utility's default language; message up to 2000 bytes, in_app_title up to 160), and optional translations, an object keyed by locale (pt-MZ or en-US) whose values hold message and/or in_app_title for recipients in that locale. At send time the recipient's notification language (else the utility's default language) selects its version, falling back to the default text field by field; translations require a default message. A rule with no text uses the template catalogue's starter text for its template_key, if any, and otherwise sends nothing on direct channels. Invalid text is rejected with code request.invalid and the offending field in params.field. create_collection_case: aging_bucket, notes. issue_disconnection_notice: cutoff_days, delivered_via. apply_late_fee: amount_cents or percent, reason. create_work_order: order_type, priority, description, crew_id. create_ticket: subject, description, category, priority. set_metadata: values. call_webhook: url, secret.",
            "type": "object"
          },
          "type": {
            "enum": [
              "send_notification",
              "create_collection_case",
              "issue_disconnection_notice",
              "apply_late_fee",
              "create_work_order",
              "create_ticket",
              "set_metadata",
              "call_webhook"
            ],
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "AutomationCondition": {
        "properties": {
          "field": {
            "description": "amount (cents), days_overdue, customer_category, service_area, or metadata.<key>",
            "type": "string"
          },
          "operator": {
            "enum": [
              "eq",
              "neq",
              "gt",
              "gte",
              "lt",
              "lte",
              "in",
              "not_in",
              "contains",
              "exists"
            ],
            "type": "string"
          },
          "value": {}
        },
        "required": [
          "field",
          "operator"
        ],
        "type": "object"
      },
      "AutomationOutcome": {
        "properties": {
          "attempts": {
            "type": "integer"
          },
          "error": {
            "type": "string"
          },
          "finished_at": {
            "format": "date-time",
            "type": "string"
          },
          "index": {
            "type": "integer"
          },
          "not_before": {
            "format": "date-time",
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "result": {
            "type": "object"
          },
          "status": {
            "enum": [
              "pending",
              "succeeded",
              "failed",
              "skipped",
              "would_run"
            ],
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AutomationRule": {
        "allOf": [
          {
            "$ref": "#/components/schemas/AutomationRuleInput"
          },
          {
            "properties": {
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "created_by": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "status": {
                "enum": [
                  "enabled",
                  "disabled"
                ],
                "type": "string"
              },
              "tenant_id": {
                "type": "string"
              },
              "updated_at": {
                "format": "date-time",
                "type": "string"
              }
            },
            "type": "object"
          }
        ]
      },
      "AutomationRuleInput": {
        "properties": {
          "actions": {
            "items": {
              "$ref": "#/components/schemas/AutomationAction"
            },
            "type": "array"
          },
          "conditions": {
            "items": {
              "$ref": "#/components/schemas/AutomationCondition"
            },
            "type": "array"
          },
          "description": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "template_key": {
            "type": "string"
          },
          "trigger": {
            "$ref": "#/components/schemas/AutomationTrigger"
          }
        },
        "required": [
          "name",
          "trigger",
          "actions"
        ],
        "type": "object"
      },
      "AutomationRulePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AutomationRule"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AutomationRuleUpdate": {
        "properties": {
          "actions": {
            "items": {
              "$ref": "#/components/schemas/AutomationAction"
            },
            "type": "array"
          },
          "conditions": {
            "items": {
              "$ref": "#/components/schemas/AutomationCondition"
            },
            "type": "array"
          },
          "description": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "trigger": {
            "$ref": "#/components/schemas/AutomationTrigger"
          }
        },
        "type": "object"
      },
      "AutomationRun": {
        "properties": {
          "attempts": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "finished_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "next_attempt_at": {
            "format": "date-time",
            "type": "string"
          },
          "outcomes": {
            "items": {
              "$ref": "#/components/schemas/AutomationOutcome"
            },
            "type": "array"
          },
          "record_id": {
            "type": "string"
          },
          "record_type": {
            "type": "string"
          },
          "rule_id": {
            "type": "string"
          },
          "rule_name": {
            "type": "string"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "running",
              "waiting",
              "succeeded",
              "failed",
              "cancelled"
            ],
            "type": "string"
          },
          "trigger_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AutomationRunPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/AutomationRun"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "AutomationTestResult": {
        "properties": {
          "actions": {
            "items": {
              "$ref": "#/components/schemas/AutomationOutcome"
            },
            "type": "array"
          },
          "conditions": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "reason": {
            "type": "string"
          },
          "record_id": {
            "type": "string"
          },
          "record_type": {
            "type": "string"
          },
          "rule_id": {
            "type": "string"
          },
          "subject": {
            "type": "object"
          },
          "would_fire": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "AutomationTrigger": {
        "properties": {
          "cron": {
            "description": "Five-field cron expression, schedule only",
            "type": "string"
          },
          "days": {
            "description": "N for invoice.overdue, ticket.unresolved, work_order.overdue; cycle length of reading.missing",
            "type": "integer"
          },
          "threshold": {
            "description": "Percentage of the average that fires consumption.anomaly",
            "type": "integer"
          },
          "timezone": {
            "type": "string"
          },
          "type": {
            "enum": [
              "invoice.issued",
              "invoice.overdue",
              "invoice.paid",
              "payment.received",
              "reading.missing",
              "reading.review_required",
              "consumption.anomaly",
              "ticket.created",
              "ticket.unresolved",
              "work_order.overdue",
              "disconnection.notice_expired",
              "schedule",
              "alarm.opened"
            ],
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "BillingAdjustment": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "amount_cents": {
            "type": "integer"
          },
          "approved_by": {
            "type": "string"
          },
          "category": {
            "enum": [
              "general",
              "late_fee",
              "interest"
            ],
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "note_number": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "type": {
            "enum": [
              "credit_note",
              "debit_note"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "invoice_id",
          "account_id",
          "type",
          "amount_cents",
          "reason",
          "approved_by",
          "created_at"
        ],
        "type": "object"
      },
      "BillingInvoice": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "amount_due_cents": {
            "type": "integer"
          },
          "arrears_cents": {
            "type": "integer"
          },
          "balance_cents": {
            "type": "integer"
          },
          "billing_run_id": {
            "type": "string"
          },
          "consumption_id": {
            "type": "string"
          },
          "consumption_m3": {
            "type": "number"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "dispute_reason": {
            "type": "string"
          },
          "disputed_at": {
            "format": "date-time",
            "type": "string"
          },
          "due_date": {
            "format": "date-time",
            "type": "string"
          },
          "estimate_reconciled_at": {
            "format": "date-time",
            "type": "string"
          },
          "estimated": {
            "type": "boolean"
          },
          "from_reading_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "invoice_number": {
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": "string"
          },
          "line_items": {
            "description": "Invoice lines. A line the server words carries description_code (invoice_line.fixed_fee, invoice_line.volumetric_tier, invoice_line.minimum_top_up, invoice_line.sanitation, invoice_line.vat, invoice_line.reconciliation) and description_params (tier, from, to; percent); clients word the code and fall back to description. Lines named after a tariff's own charges have no code.",
            "items": {
              "additionalProperties": true,
              "type": "object"
            },
            "type": "array"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "paid_at": {
            "format": "date-time",
            "type": "string"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "reconciliation_cents": {
            "type": "integer"
          },
          "sanitation_cents": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "draft",
              "open",
              "paid",
              "partially_paid",
              "void",
              "uncollectible"
            ],
            "type": "string"
          },
          "subtotal_cents": {
            "type": "integer"
          },
          "tariff_version_id": {
            "type": "string"
          },
          "tax_cents": {
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "to_reading_id": {
            "type": "string"
          },
          "total_cents": {
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "void_reason": {
            "type": "string"
          },
          "voided_at": {
            "format": "date-time",
            "type": "string"
          },
          "write_off_reason": {
            "type": "string"
          },
          "written_off_at": {
            "format": "date-time",
            "type": "string"
          },
          "written_off_cents": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "invoice_number",
          "customer_id",
          "account_id",
          "period_start",
          "period_end",
          "total_cents",
          "balance_cents",
          "amount_due_cents",
          "currency",
          "status",
          "due_date",
          "issued_at",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "BillingRun": {
        "properties": {
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "error_message": {
            "type": "string"
          },
          "estimated_invoices": {
            "type": "integer"
          },
          "exception_count": {
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "issued_amount_cents": {
            "description": "Total of the invoices issued by the most recent execution of this run; total_amount_cents covers every execution.",
            "format": "int64",
            "type": "integer"
          },
          "issued_invoices": {
            "description": "Invoices issued by the most recent execution of this run.",
            "type": "integer"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "schedule_id": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "skipped_accounts": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending",
              "running",
              "completed",
              "failed"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "total_amount_cents": {
            "type": "integer"
          },
          "total_invoices": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "period_start",
          "period_end",
          "total_invoices",
          "total_amount_cents",
          "status",
          "issued_invoices",
          "issued_amount_cents",
          "skipped_accounts",
          "estimated_invoices",
          "exception_count",
          "created_at"
        ],
        "type": "object"
      },
      "BillingRunPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/BillingRun"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "BillingRunPreview": {
        "properties": {
          "capability_active": {
            "type": "boolean"
          },
          "estimated_count": {
            "type": "integer"
          },
          "exception_count": {
            "type": "integer"
          },
          "exceptions": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "invoice_count": {
            "type": "integer"
          },
          "invoices": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "total_amount_cents": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "BillingRunRequest": {
        "properties": {
          "auto_consumption": {
            "type": "boolean"
          },
          "due_date": {
            "format": "date-time",
            "type": "string"
          },
          "estimate_missing": {
            "type": "boolean"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "required": [
          "period_start",
          "period_end"
        ],
        "type": "object"
      },
      "BillingSchedule": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BillingScheduleInput"
          },
          {
            "properties": {
              "id": {
                "type": "string"
              },
              "last_error": {
                "type": "string"
              },
              "last_run_at": {
                "format": "date-time",
                "type": "string"
              },
              "last_run_id": {
                "type": "string"
              },
              "next_run_at": {
                "format": "date-time",
                "type": "string"
              },
              "status": {
                "enum": [
                  "active",
                  "paused"
                ],
                "type": "string"
              },
              "tenant_id": {
                "type": "string"
              }
            },
            "type": "object"
          }
        ]
      },
      "BillingScheduleInput": {
        "properties": {
          "auto_consumption": {
            "default": true,
            "type": "boolean"
          },
          "day_of_month": {
            "maximum": 28,
            "minimum": 1,
            "type": "integer"
          },
          "due_days": {
            "type": "integer"
          },
          "estimate_missing": {
            "type": "boolean"
          },
          "name": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "day_of_month",
          "due_days"
        ],
        "type": "object"
      },
      "BookSiteVisitInput": {
        "properties": {
          "date": {
            "description": "One of the offered days",
            "format": "date",
            "type": "string"
          },
          "notes": {
            "maxLength": 1000,
            "type": "string"
          }
        },
        "required": [
          "date"
        ],
        "type": "object"
      },
      "Branding": {
        "properties": {
          "colors": {
            "$ref": "#/components/schemas/BrandingColors"
          },
          "copyright": {
            "description": "Who the copyright line names (© <year> <copyright>). Empty means the legal name; when both are empty, clients show no copyright line rather than assume the product name.",
            "type": "string"
          },
          "icon_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "legal_name": {
            "type": "string"
          },
          "links": {
            "properties": {
              "privacy": {
                "type": "string"
              },
              "terms": {
                "type": "string"
              },
              "website": {
                "type": "string"
              }
            },
            "required": [
              "website",
              "terms",
              "privacy"
            ],
            "type": "object"
          },
          "logo_dark_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "logo_url": {
            "description": "Absolute path with a v hash, such as $PUBLIC_API/branding/assets/logo?v=…; null when unset",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "short_name": {
            "type": "string"
          },
          "support": {
            "properties": {
              "email": {
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "url": {
                "type": "string"
              }
            },
            "required": [
              "email",
              "phone",
              "url"
            ],
            "type": "object"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "name",
          "short_name",
          "legal_name",
          "copyright",
          "support",
          "links",
          "colors",
          "logo_url",
          "logo_dark_url",
          "icon_url",
          "updated_at"
        ],
        "type": "object"
      },
      "BrandingColors": {
        "properties": {
          "accent": {
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "type": "string"
          },
          "brand": {
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "type": "string"
          },
          "brand_foreground": {
            "pattern": "^#[0-9A-Fa-f]{6}$",
            "type": "string"
          }
        },
        "required": [
          "brand",
          "brand_foreground",
          "accent"
        ],
        "type": "object"
      },
      "BrandingPatch": {
        "description": "Every field is optional; null resets it to the configured value.",
        "properties": {
          "colors": {
            "properties": {
              "accent": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "brand": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "brand_foreground": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": [
              "object",
              "null"
            ]
          },
          "copyright": {
            "description": "Who the copyright line names; empty uses the legal name.",
            "maxLength": 200,
            "type": [
              "string",
              "null"
            ]
          },
          "legal_name": {
            "maxLength": 200,
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "maxLength": 80,
            "type": [
              "string",
              "null"
            ]
          },
          "privacy_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "short_name": {
            "maxLength": 30,
            "type": [
              "string",
              "null"
            ]
          },
          "support_email": {
            "type": [
              "string",
              "null"
            ]
          },
          "support_phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "support_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "terms_url": {
            "type": [
              "string",
              "null"
            ]
          },
          "website_url": {
            "type": [
              "string",
              "null"
            ]
          }
        },
        "type": "object"
      },
      "BrandingSource": {
        "enum": [
          "configured",
          "custom"
        ],
        "type": "string"
      },
      "BulkInvitationRequest": {
        "properties": {
          "invitations": {
            "items": {
              "$ref": "#/components/schemas/InvitationInput"
            },
            "type": "array"
          }
        },
        "required": [
          "invitations"
        ],
        "type": "object"
      },
      "BusinessOverview": {
        "description": "Domain totals and series are returned only when the caller has the corresponding domain read scope. Receivables require invoices:read or collections:read; collection_rate requires both invoices:read and payments:read. Portfolio overviews apply these checks separately to each account.",
        "properties": {
          "arrears_collected_cents": {
            "description": "Part of collected_cents applied to invoices billed in earlier periods, or to no invoice",
            "format": "int64",
            "type": "integer"
          },
          "billed_cents": {
            "format": "int64",
            "type": "integer"
          },
          "collected_cents": {
            "format": "int64",
            "type": "integer"
          },
          "collected_current_period_cents": {
            "description": "Part of collected_cents applied to invoices billed in the period",
            "format": "int64",
            "type": "integer"
          },
          "collection_rate": {
            "description": "Percentage of the period's billed amount collected through payments applied to invoices billed in that period, capped at 100. Payments against earlier invoices are in arrears_collected_cents and do not raise this rate.",
            "maximum": 100,
            "type": "number"
          },
          "collections_by_hour": {
            "$ref": "#/components/schemas/CollectionsByHour"
          },
          "currency": {
            "type": "string"
          },
          "open_work": {
            "properties": {
              "incidents": {
                "type": "integer"
              },
              "tickets": {
                "type": "integer"
              },
              "work_orders": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "period": {
            "type": "object"
          },
          "read_rate": {
            "type": "number"
          },
          "readings_count": {
            "type": "integer"
          },
          "receivables_by_ageing": {
            "items": {
              "properties": {
                "balance_cents": {
                  "type": "integer"
                },
                "bucket": {
                  "type": "string"
                },
                "invoices": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "series": {
            "properties": {
              "billed_cents": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              },
              "collected_cents": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              },
              "readings": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              },
              "volume_m3": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "volume_m3": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "BusinessPortfolioOverview": {
        "properties": {
          "accounts": {
            "description": "The root account first, then each readable descendant account.",
            "items": {
              "properties": {
                "account_holder_name": {
                  "description": "Display name of the account holder. Omitted when unknown.",
                  "type": "string"
                },
                "account_id": {
                  "type": "string"
                },
                "account_number": {
                  "description": "Number of the referenced account. Omitted when unknown.",
                  "type": "string"
                },
                "overview": {
                  "$ref": "#/components/schemas/BusinessOverview"
                }
              },
              "required": [
                "account_id",
                "overview"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "billed_cents": {
            "description": "Sum of billed_cents across the accounts.",
            "format": "int64",
            "type": "integer"
          },
          "collected_cents": {
            "description": "Sum of collected_cents across the accounts.",
            "format": "int64",
            "type": "integer"
          },
          "currency": {
            "description": "Currency shared by every account in the portfolio.",
            "type": "string"
          },
          "period": {
            "description": "Reporting month.",
            "properties": {
              "end": {
                "format": "date-time",
                "type": "string"
              },
              "label": {
                "example": "2026-10",
                "type": "string"
              },
              "start": {
                "format": "date-time",
                "type": "string"
              }
            },
            "type": "object"
          },
          "readings_count": {
            "description": "Sum of readings_count across the accounts.",
            "type": "integer"
          },
          "root_account_id": {
            "description": "The caller's tenant, at the root of the portfolio.",
            "type": "string"
          },
          "series": {
            "description": "Daily series summed across the accounts, oldest first.",
            "properties": {
              "billed_cents": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              },
              "collected_cents": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              },
              "readings": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              },
              "volume_m3": {
                "items": {
                  "$ref": "#/components/schemas/SeriesPoint"
                },
                "type": "array"
              }
            },
            "type": "object"
          },
          "volume_m3": {
            "description": "Sum of volume_m3 across the accounts.",
            "type": "number"
          }
        },
        "required": [
          "root_account_id",
          "period",
          "currency",
          "accounts",
          "billed_cents",
          "collected_cents",
          "volume_m3",
          "readings_count",
          "series"
        ],
        "type": "object"
      },
      "BusinessUtilityRelationship": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "end_reason": {
            "type": "string"
          },
          "ended_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "description": "What the person is to the utility.",
            "enum": [
              "requester",
              "follower",
              "assisted_helper"
            ],
            "type": "string"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "ended",
              "invited",
              "pending_review",
              "suspended",
              "declined",
              "expired"
            ],
            "type": "string"
          },
          "subject_id": {
            "description": "Identifier of that record.",
            "type": "string"
          },
          "subject_type": {
            "description": "Type of the record the relationship is about, when it is about one.",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "kind",
          "status",
          "started_at",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "BusinessUtilityRelationshipPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/BusinessUtilityRelationship"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "CalendarDayInput": {
        "properties": {
          "area_id": {
            "type": "string"
          },
          "date": {
            "format": "date-time",
            "type": "string"
          },
          "kind": {
            "default": "holiday",
            "enum": [
              "holiday",
              "closure",
              "working"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          }
        },
        "required": [
          "date"
        ],
        "type": "object"
      },
      "CalendarImport": {
        "properties": {
          "added": {
            "items": {
              "$ref": "#/components/schemas/CalendarImportItem"
            },
            "type": "array"
          },
          "affected": {
            "items": {
              "properties": {
                "count": {
                  "type": "integer"
                },
                "from": {
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "to": {
                  "format": "date-time",
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "type",
                "id",
                "count"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "affected_limitations": {
            "description": "Consumer coverage gaps and date behaviors not recalculated by this preview.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "applied_at": {
            "format": "date-time",
            "type": "string"
          },
          "changed": {
            "items": {
              "$ref": "#/components/schemas/CalendarImportItem"
            },
            "type": "array"
          },
          "confirmed_by": {
            "type": "string"
          },
          "conflicts": {
            "items": {
              "properties": {
                "date": {
                  "format": "date",
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                },
                "existing_kind": {
                  "enum": [
                    "holiday",
                    "closure",
                    "working"
                  ],
                  "type": "string"
                },
                "incoming_kind": {
                  "enum": [
                    "holiday",
                    "closure",
                    "working"
                  ],
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "format": {
            "enum": [
              "ics",
              "csv"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/CalendarImportItem"
            },
            "type": "array"
          },
          "outcome": {
            "type": "string"
          },
          "removed": {
            "items": {
              "$ref": "#/components/schemas/CalendarImportItem"
            },
            "type": "array"
          },
          "source_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "preview",
              "applied",
              "failed"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CalendarImportInput": {
        "properties": {
          "auto_apply": {
            "type": "boolean"
          },
          "content": {
            "type": "string"
          },
          "format": {
            "enum": [
              "ics",
              "csv"
            ],
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "url": {
            "type": "string"
          }
        },
        "required": [
          "format"
        ],
        "type": "object"
      },
      "CalendarImportItem": {
        "properties": {
          "area_id": {
            "type": "string"
          },
          "date": {
            "format": "date",
            "type": "string"
          },
          "day": {
            "type": "integer"
          },
          "easter_kind": {
            "enum": [
              "western",
              "orthodox"
            ],
            "type": "string"
          },
          "easter_offset": {
            "type": "integer"
          },
          "kind": {
            "type": "string"
          },
          "kind_of_day": {
            "enum": [
              "holiday",
              "closure",
              "working"
            ],
            "type": "string"
          },
          "month": {
            "type": "integer"
          },
          "name_en": {
            "type": "string"
          },
          "name_pt": {
            "type": "string"
          },
          "observed": {
            "enum": [
              "none",
              "next",
              "previous",
              "nearest"
            ],
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "source_ref": {
            "type": "string"
          },
          "uid": {
            "type": "string"
          },
          "valid_from": {
            "format": "date",
            "type": "string"
          },
          "valid_to": {
            "format": "date",
            "type": "string"
          },
          "weekday": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "CalendarRuleInput": {
        "properties": {
          "area_id": {
            "type": "string"
          },
          "day": {
            "maximum": 31,
            "minimum": 1,
            "type": "integer"
          },
          "easter_kind": {
            "enum": [
              "western",
              "orthodox"
            ],
            "type": "string"
          },
          "easter_offset": {
            "type": "integer"
          },
          "kind": {
            "enum": [
              "fixed_yearly",
              "nth_weekday",
              "last_weekday",
              "easter_offset"
            ],
            "type": "string"
          },
          "kind_of_day": {
            "enum": [
              "holiday",
              "closure",
              "working"
            ],
            "type": "string"
          },
          "month": {
            "maximum": 12,
            "minimum": 1,
            "type": "integer"
          },
          "name_en": {
            "type": "string"
          },
          "name_pt": {
            "type": "string"
          },
          "observed": {
            "enum": [
              "none",
              "next",
              "previous",
              "nearest"
            ],
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "source_ref": {
            "type": "string"
          },
          "valid_from": {
            "example": "1975-01-01",
            "type": "string"
          },
          "valid_to": {
            "example": "2030-12-31",
            "type": "string"
          },
          "weekday": {
            "maximum": 6,
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "kind",
          "name_pt"
        ],
        "type": "object"
      },
      "CalendarRulePatch": {
        "properties": {
          "day": {
            "maximum": 31,
            "minimum": 1,
            "type": "integer"
          },
          "easter_kind": {
            "enum": [
              "western",
              "orthodox"
            ],
            "type": "string"
          },
          "easter_offset": {
            "type": "integer"
          },
          "kind": {
            "enum": [
              "fixed_yearly",
              "nth_weekday",
              "last_weekday",
              "easter_offset"
            ],
            "type": "string"
          },
          "kind_of_day": {
            "enum": [
              "holiday",
              "closure",
              "working"
            ],
            "type": "string"
          },
          "month": {
            "maximum": 12,
            "minimum": 1,
            "type": "integer"
          },
          "name_en": {
            "type": "string"
          },
          "name_pt": {
            "type": "string"
          },
          "observed": {
            "enum": [
              "none",
              "next",
              "previous",
              "nearest"
            ],
            "type": "string"
          },
          "position": {
            "type": "integer"
          },
          "valid_from": {
            "type": "string"
          },
          "valid_to": {
            "type": "string"
          },
          "weekday": {
            "maximum": 6,
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "CalendarSourceInput": {
        "properties": {
          "auto_apply": {
            "type": "boolean"
          },
          "enabled": {
            "type": "boolean"
          },
          "kind": {
            "enum": [
              "manual",
              "file",
              "url",
              "connector",
              "template_version"
            ],
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "refresh_schedule": {
            "type": "string"
          }
        },
        "required": [
          "kind"
        ],
        "type": "object"
      },
      "CalendarSourcePatch": {
        "properties": {
          "auto_apply": {
            "type": "boolean"
          },
          "enabled": {
            "type": "boolean"
          },
          "kind": {
            "enum": [
              "manual",
              "file",
              "url",
              "connector",
              "template_version"
            ],
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "refresh_schedule": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CalendarUpdate": {
        "properties": {
          "area_id": {
            "type": "string"
          },
          "template_key": {
            "example": "mz",
            "type": "string"
          },
          "template_year": {
            "type": "integer"
          },
          "timezone": {
            "example": "Africa/Maputo",
            "type": "string"
          },
          "working_days": {
            "items": {
              "maximum": 6,
              "minimum": 0,
              "type": "integer"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "CapabilityLabel": {
        "properties": {
          "code": {
            "type": "string"
          },
          "label": {
            "description": "The capability's label in the caller's language",
            "type": "string"
          }
        },
        "required": [
          "code",
          "label"
        ],
        "type": "object"
      },
      "CapabilityReason": {
        "properties": {
          "code": {
            "enum": [
              "requirements_due",
              "requirements_pending",
              "plan_excluded",
              "verification_submission_required",
              "verification_review_pending",
              "verification_rejected"
            ],
            "type": "string"
          },
          "requirements": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "CapabilityRequirementTemplate": {
        "properties": {
          "country_code": {
            "maxLength": 2,
            "minLength": 2,
            "type": "string"
          },
          "key": {
            "type": "string"
          },
          "organization_type": {
            "enum": [
              "utility",
              "authority",
              "operator",
              "regulator",
              "partner",
              "group"
            ],
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "requirements": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "type": "object"
          },
          "verification_requirements": {
            "description": "Requirement keys used to build this context's verification checklist. The most specific matching template replaces the less-specific checklist.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "key",
          "requirements"
        ],
        "type": "object"
      },
      "ChangePasswordRequest": {
        "properties": {
          "current_password": {
            "type": "string"
          },
          "new_password": {
            "maxLength": 128,
            "minLength": 8,
            "type": "string"
          }
        },
        "required": [
          "current_password",
          "new_password"
        ],
        "type": "object"
      },
      "ChangePlanPreview": {
        "properties": {
          "currency": {
            "type": "string"
          },
          "current_period_end": {
            "format": "date-time",
            "type": "string"
          },
          "from_plan_id": {
            "type": "string"
          },
          "proration_cents": {
            "description": "Positive charges and negative credits on the next invoice",
            "type": "integer"
          },
          "to_plan_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ChangePlanRequest": {
        "properties": {
          "plan_id": {
            "type": "string"
          }
        },
        "required": [
          "plan_id"
        ],
        "type": "object"
      },
      "ChangePlanResult": {
        "properties": {
          "from_plan_id": {
            "type": "string"
          },
          "proration_cents": {
            "type": "integer"
          },
          "subscription": {
            "type": "object"
          },
          "to_plan_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ClientSettings": {
        "properties": {
          "challenge": {
            "description": "Present only when security.challenge.provider is not none.",
            "properties": {
              "attribution": {
                "type": "string"
              },
              "challenge_url": {
                "format": "uri",
                "type": "string"
              },
              "provider": {
                "enum": [
                  "builtin",
                  "turnstile",
                  "hcaptcha",
                  "recaptcha"
                ],
                "type": "string"
              },
              "site_key": {
                "type": "string"
              }
            },
            "required": [
              "provider"
            ],
            "type": "object"
          },
          "session": {
            "properties": {
              "refresh_ahead_seconds": {
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "refresh_ahead_seconds"
            ],
            "type": "object"
          },
          "uploads": {
            "properties": {
              "max_file_bytes": {
                "format": "int64",
                "type": "integer"
              }
            },
            "required": [
              "max_file_bytes"
            ],
            "type": "object"
          }
        },
        "required": [
          "uploads",
          "session"
        ],
        "type": "object"
      },
      "CodeIssued": {
        "properties": {
          "dev_code": {
            "description": "Issued code, present only in development mode",
            "type": "string"
          }
        },
        "type": "object"
      },
      "CollectionCase": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "aging_bucket": {
            "enum": [
              "current",
              "30_days",
              "60_days",
              "90_days",
              "120_days_plus"
            ],
            "type": "string"
          },
          "connection_holder_name": {
            "description": "Display name of the customer who holds the referenced connection. Omitted when unknown.",
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "cutoff_order_id": {
            "type": "string"
          },
          "dunning_level": {
            "type": "integer"
          },
          "dunning_status": {
            "enum": [
              "in_notice",
              "cutoff_pending",
              "disconnected",
              "settled"
            ],
            "type": "string"
          },
          "id": {
            "pattern": "^col_",
            "type": "string"
          },
          "note_entries": {
            "description": "The case log as entries, oldest first. A case written before entries existed has its whole notes text as one entry without a code.",
            "items": {
              "$ref": "#/components/schemas/CollectionCaseNote"
            },
            "type": "array"
          },
          "notes": {
            "description": "The case log rendered as text, one note per line. Kept for older clients and search; prefer note_entries.",
            "type": "string"
          },
          "reconnect_order_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "open",
              "notice_sent",
              "payment_plan_active",
              "enforcement_requested",
              "resolved",
              "written_off"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "total_debt_cents": {
            "format": "int64",
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "customer_id",
          "account_id",
          "total_debt_cents",
          "currency",
          "aging_bucket",
          "status",
          "dunning_level",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "CollectionCaseNote": {
        "properties": {
          "actor_id": {
            "type": "string"
          },
          "at": {
            "format": "date-time",
            "type": "string"
          },
          "code": {
            "description": "Stable code of a note the server wrote (collection.case.opened_for_cutoff, collection.case.resolved, collection.case.enforcement_requested, collection.case.reopened_reversal); clients word it and fall back to text. Absent for notes people typed.",
            "type": "string"
          },
          "params": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values the code's wording fills in: reason (resolved, enforcement_requested), payment (reopened_reversal).",
            "type": "object"
          },
          "text": {
            "description": "The note as typed, or the server's wording of code.",
            "type": "string"
          }
        },
        "required": [
          "at",
          "text"
        ],
        "type": "object"
      },
      "CollectionCasePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/CollectionCase"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "CollectionsByHour": {
        "description": "Collections for the utility's local today and yesterday, independent of the requested period",
        "properties": {
          "timezone": {
            "type": "string"
          },
          "today": {
            "$ref": "#/components/schemas/DayCollections"
          },
          "yesterday": {
            "$ref": "#/components/schemas/DayCollections"
          }
        },
        "type": "object"
      },
      "CompleteNotificationDelivery": {
        "properties": {
          "channel": {
            "enum": [
              "email",
              "push",
              "in_app"
            ],
            "type": "string"
          },
          "failure_code": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "provider_receipt_reference": {
            "type": "string"
          },
          "status": {
            "enum": [
              "accepted",
              "sent",
              "delivered",
              "failed"
            ],
            "type": "string"
          }
        },
        "required": [
          "status",
          "idempotency_key"
        ],
        "type": "object"
      },
      "CompleteSiteVisitInput": {
        "properties": {
          "outcome": {
            "maxLength": 2000,
            "type": "string"
          },
          "quote": {
            "$ref": "#/components/schemas/IssueQuoteInput"
          }
        },
        "required": [
          "outcome"
        ],
        "type": "object"
      },
      "ComplianceExport": {
        "properties": {
          "audit_chain_verified": {
            "type": "boolean"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "download_url": {
            "type": "string"
          },
          "error": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "sha256": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "queued",
              "running",
              "completed",
              "failed"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "ConnectionEstimate": {
        "properties": {
          "currency": {
            "type": "string"
          },
          "max_cents": {
            "format": "int64",
            "type": "integer"
          },
          "message": {
            "type": "string"
          },
          "message_code": {
            "enum": [
              "estimate.priced",
              "estimate.range",
              "estimate.unpriced"
            ],
            "type": "string"
          },
          "min_cents": {
            "format": "int64",
            "type": "integer"
          },
          "priced": {
            "description": "False when the utility has not configured a connection price",
            "type": "boolean"
          }
        },
        "required": [
          "priced",
          "message_code",
          "message"
        ],
        "type": "object"
      },
      "ConnectionEstimateRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "connection_type": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "distance_meters": {
            "type": "integer"
          },
          "locality": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ConnectionPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WaterConnection"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ConsumerAccount": {
        "properties": {
          "account_number": {
            "type": "string"
          },
          "billing_organization_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "account_number",
          "status"
        ],
        "type": "object"
      },
      "ConsumerInboxPage": {
        "properties": {
          "data": {
            "description": "Inbox messages addressed to the caller, newest first.",
            "items": {
              "$ref": "#/components/schemas/NotificationInboxItem"
            },
            "type": "array"
          },
          "has_more": {
            "description": "True when another page follows; pass next_cursor as after to read it.",
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Opaque cursor for the next page; present only when has_more is true.",
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ConsumerInspectionRequestSubmission": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "idempotency_key": {
            "maxLength": 160,
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "reason": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "account_id",
          "meter_id",
          "reason",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ConsumerInvoiceDispute": {
        "additionalProperties": false,
        "properties": {
          "charge_code": {
            "description": "Optional charge code being contested; defaults to the line item's charge code when line_item_id is given.",
            "type": "string"
          },
          "line_item_id": {
            "description": "Optional line item being contested; it must be on the invoice.",
            "type": "string"
          },
          "reason": {
            "description": "Why the caller contests the invoice; blank or whitespace-only is refused.",
            "example": "The meter reading on this invoice is higher than the meter shows.",
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "type": "object"
      },
      "ConsumerOnboarding": {
        "properties": {
          "current_terms_version": {
            "type": "string"
          },
          "notification_consent": {
            "type": "boolean"
          },
          "profile": {
            "type": "object"
          },
          "requirements": {
            "$ref": "#/components/schemas/OnboardingRequirements"
          },
          "status": {
            "enum": [
              "not_started",
              "in_progress",
              "complete"
            ],
            "type": "string"
          },
          "terms": {
            "type": "object"
          }
        },
        "type": "object"
      },
      "ConsumerOverview": {
        "properties": {
          "accounts": {
            "items": {
              "properties": {
                "account_id": {
                  "type": "string"
                },
                "account_number": {
                  "type": "string"
                },
                "amount_due_cents": {
                  "type": "integer"
                },
                "consumption_series": {
                  "items": {
                    "$ref": "#/components/schemas/SeriesPoint"
                  },
                  "type": "array"
                },
                "currency": {
                  "type": "string"
                },
                "last_invoice": {
                  "description": "The most recently issued invoice on the account; absent when none was issued",
                  "properties": {
                    "balance_cents": {
                      "type": "integer"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "due_date": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "invoice_number": {
                      "type": "string"
                    },
                    "issued_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "status": {
                      "type": "string"
                    },
                    "total_cents": {
                      "type": "integer"
                    }
                  },
                  "type": "object"
                },
                "latest_reading": {
                  "type": "object"
                },
                "open_invoices": {
                  "type": "integer"
                },
                "tenant_id": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "amount_due_cents": {
            "format": "int64",
            "type": "integer"
          },
          "currency": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "ConsumerPaymentBasket": {
        "properties": {
          "data": {
            "description": "One result per requested invoice, in request order.",
            "items": {
              "$ref": "#/components/schemas/ConsumerPaymentBasketItem"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ConsumerPaymentBasketItem": {
        "properties": {
          "error": {
            "description": "Present instead of session when a payment could not be started for this invoice. The text is generic and does not say why.",
            "example": "Payment could not be started.",
            "type": "string"
          },
          "invoice_id": {
            "description": "The invoice this result is for.",
            "type": "string"
          },
          "session": {
            "$ref": "#/components/schemas/PaymentSession"
          }
        },
        "required": [
          "invoice_id"
        ],
        "type": "object"
      },
      "ConsumerPrepaidPurchaseRequest": {
        "additionalProperties": false,
        "properties": {
          "amount_cents": {
            "maximum": 100000000,
            "minimum": 1,
            "type": "integer"
          },
          "idempotency_key": {
            "minLength": 1,
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "prepaid_meter_id": {
            "pattern": "^ppm_",
            "type": "string"
          }
        },
        "required": [
          "prepaid_meter_id",
          "amount_cents",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ConsumerReadingDisputeSubmission": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "idempotency_key": {
            "maxLength": 160,
            "type": "string"
          },
          "reading_id": {
            "type": "string"
          },
          "reason": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "account_id",
          "reading_id",
          "reason",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ConsumerReadingSubmission": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "client_reading_id": {
            "type": "string"
          },
          "evidence_ids": {
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "type": "array"
          },
          "idempotency_key": {
            "type": "string"
          },
          "measured_at": {
            "format": "date-time",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "account_id",
          "meter_id",
          "value",
          "unit",
          "measured_at",
          "client_reading_id",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ConsumerRelationship": {
        "description": "One entry in the caller's cross-utility relationship list. Account-bound entries come from account memberships (kind holder, delegate, payer, tenant or landlord) and carry the account and the permissions granted on it; utility-only entries (kind requester or follower) carry the subject the caller follows or asked about.",
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "description": "Account of an account-bound entry.",
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "ended_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Membership ID for an account-bound entry, or utility relationship ID (prefix `ulr`) for a utility-only entry. Pass it to the end call.",
            "type": "string"
          },
          "kind": {
            "description": "Relationship kind.",
            "enum": [
              "holder",
              "delegate",
              "payer",
              "tenant",
              "landlord",
              "requester",
              "follower"
            ],
            "type": "string"
          },
          "permissions": {
            "description": "Account permissions the membership grants. Omitted for utility-only entries.",
            "items": {
              "enum": [
                "account.read",
                "invoice.read",
                "payment.create",
                "reading.create",
                "ticket.create",
                "connection.manage",
                "member.invite"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "description": "Current status; a membership past its expiry that was never ended reports expired.",
            "enum": [
              "invited",
              "pending_review",
              "active",
              "suspended",
              "ended",
              "declined",
              "expired"
            ],
            "type": "string"
          },
          "subject_id": {
            "description": "Identifier of the subject of a utility-only entry.",
            "type": "string"
          },
          "subject_label": {
            "description": "Label to show for an account-bound entry; the account number, or the account ID when it has no number.",
            "type": "string"
          },
          "subject_type": {
            "description": "Type of the subject of a utility-only entry, as given when it was created.",
            "type": "string"
          },
          "tenant_id": {
            "description": "Utility the relationship is with.",
            "type": "string"
          },
          "tenant_name": {
            "description": "Display name of the utility; falls back to the tenant ID when the utility has no name.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "kind",
          "status",
          "started_at",
          "created_at"
        ],
        "type": "object"
      },
      "ConsumerRelationshipPage": {
        "properties": {
          "data": {
            "description": "Relationships, newest first.",
            "items": {
              "$ref": "#/components/schemas/ConsumerRelationship"
            },
            "type": "array"
          },
          "has_more": {
            "description": "True when another page follows.",
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Opaque cursor for the next page; present only when has_more is true.",
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ConsumerUtilityRelationship": {
        "description": "A utility-only relationship as stored, returned when one is created.",
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "end_reason": {
            "type": "string"
          },
          "ended_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Relationship ID (prefix `ulr`).",
            "example": "ulr_01J9Z5V7Q3",
            "type": "string"
          },
          "identity_id": {
            "description": "The caller's identity ID.",
            "type": "string"
          },
          "kind": {
            "enum": [
              "requester",
              "follower"
            ],
            "type": "string"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "description": "active for a follower, pending_review for a requester.",
            "enum": [
              "active",
              "pending_review"
            ],
            "type": "string"
          },
          "subject_id": {
            "type": "string"
          },
          "subject_type": {
            "type": "string"
          },
          "tenant_id": {
            "description": "Utility the relationship is with.",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "kind",
          "status",
          "started_at",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "Consumption": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "cycle_id": {
            "type": "string"
          },
          "from_reading_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "method": {
            "enum": [
              "actual",
              "estimated"
            ],
            "type": "string"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "to_reading_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "account_id",
          "meter_id",
          "cycle_id",
          "period_start",
          "period_end",
          "from_reading_id",
          "to_reading_id",
          "value",
          "unit",
          "method",
          "created_at"
        ],
        "type": "object"
      },
      "ConsumptionPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Consumption"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ConsumptionRequest": {
        "properties": {
          "cycle_id": {
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "meter_id",
          "cycle_id",
          "period_start",
          "period_end"
        ],
        "type": "object"
      },
      "CreateAccount": {
        "properties": {
          "customer_id": {
            "type": "string"
          },
          "property_id": {
            "type": "string"
          }
        },
        "required": [
          "customer_id",
          "property_id"
        ],
        "type": "object"
      },
      "CreateAccountLink": {
        "description": "Send code, or tenant_id, account_number and phone.",
        "properties": {
          "account_number": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "CreateAccountMembership": {
        "properties": {
          "expires_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "identity_id": {
            "type": "string"
          },
          "permissions": {
            "items": {
              "enum": [
                "account.read",
                "invoice.read",
                "payment.create",
                "reading.create",
                "ticket.create",
                "connection.manage",
                "member.invite"
              ],
              "type": "string"
            },
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          }
        },
        "required": [
          "identity_id",
          "permissions"
        ],
        "type": "object"
      },
      "CreateAlarmRuleRequest": {
        "properties": {
          "clear_threshold": {
            "type": "number"
          },
          "comparison": {
            "enum": [
              "above",
              "below"
            ],
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "notify_phones": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "parameter": {
            "type": "string"
          },
          "sensor_id": {
            "type": "string"
          },
          "severity": {
            "type": "string"
          },
          "source": {
            "enum": [
              "telemetry",
              "quality"
            ],
            "type": "string"
          },
          "threshold": {
            "type": "number"
          }
        },
        "required": [
          "name",
          "source",
          "comparison",
          "threshold"
        ],
        "type": "object"
      },
      "CreateAssetRequest": {
        "properties": {
          "asset_type": {
            "$ref": "#/components/schemas/AssetType"
          },
          "capacity": {
            "type": "number"
          },
          "code": {
            "type": "string"
          },
          "elevation": {
            "type": "number"
          },
          "installation_date": {
            "format": "date-time",
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "name": {
            "type": "string"
          },
          "properties": {
            "additionalProperties": true,
            "type": "object"
          },
          "service_area_id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/AssetStatus"
          }
        },
        "required": [
          "code",
          "name",
          "asset_type"
        ],
        "type": "object"
      },
      "CreateBusinessInvoiceRequest": {
        "additionalProperties": false,
        "properties": {
          "account_id": {
            "description": "Account the invoice is billed to.",
            "type": "string"
          },
          "billing_run_id": {
            "description": "Billing run to attach the invoice to.",
            "type": "string"
          },
          "consumption_id": {
            "description": "Consumption record the volume comes from.",
            "type": "string"
          },
          "consumption_m3": {
            "description": "Volume to price, in cubic metres.",
            "example": 12.5,
            "type": "number"
          },
          "customer_id": {
            "description": "Customer the invoice is addressed to.",
            "type": "string"
          },
          "due_date": {
            "description": "Due date; defaults to the billing policy's default due days after issue (30 when unset).",
            "format": "date-time",
            "type": "string"
          },
          "from_reading_id": {
            "description": "Reading that opens the billed period.",
            "type": "string"
          },
          "meter_id": {
            "description": "Meter whose consumption is billed.",
            "type": "string"
          },
          "period_end": {
            "description": "End of the billed period; must not be before period_start. Also picks the active tariff when tariff_version_id is omitted.",
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "description": "Start of the billed period.",
            "format": "date-time",
            "type": "string"
          },
          "tariff_version_id": {
            "description": "Tariff version to price with; defaults to the residential tariff active at period_end.",
            "type": "string"
          },
          "to_reading_id": {
            "description": "Reading that closes the billed period.",
            "type": "string"
          }
        },
        "required": [
          "customer_id",
          "account_id"
        ],
        "type": "object"
      },
      "CreateCaseRequest": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "aging_bucket": {
            "enum": [
              "current",
              "30_days",
              "60_days",
              "90_days",
              "120_days_plus"
            ],
            "type": "string"
          },
          "currency": {
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "total_debt_cents": {
            "format": "int64",
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "customer_id",
          "account_id",
          "total_debt_cents",
          "currency",
          "aging_bucket"
        ],
        "type": "object"
      },
      "CreateConnectionRequest": {
        "properties": {
          "address": {
            "type": "string"
          },
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "gps_coordinates": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "pipe_diameter_mm": {
            "type": "integer"
          },
          "pipe_material": {
            "type": "string"
          },
          "pressure_zone_id": {
            "type": "string"
          },
          "property_id": {
            "type": "string"
          }
        },
        "required": [
          "customer_id",
          "property_id"
        ],
        "type": "object"
      },
      "CreateConsumerPaymentBasket": {
        "additionalProperties": false,
        "properties": {
          "items": {
            "description": "One entry per invoice to pay, 1 to 20 entries, each with a distinct invoice_id. Invoices may belong to different utilities.",
            "items": {
              "$ref": "#/components/schemas/CreatePaymentSession"
            },
            "maxItems": 20,
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "items"
        ],
        "type": "object"
      },
      "CreateConsumerRelationship": {
        "additionalProperties": false,
        "properties": {
          "kind": {
            "description": "follower starts an active relationship at once; requester starts one in pending_review for the utility to act on and needs subject_id.",
            "enum": [
              "requester",
              "follower"
            ],
            "type": "string"
          },
          "subject_id": {
            "description": "Identifier of the subject; required when kind is requester.",
            "type": "string"
          },
          "subject_type": {
            "description": "Optional type of the subject the relationship is about, for example a property or service request.",
            "type": "string"
          },
          "tenant_id": {
            "description": "Utility to start the relationship with.",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "kind"
        ],
        "type": "object"
      },
      "CreateCustomer": {
        "properties": {
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "customer_type": {
            "enum": [
              "individual",
              "business"
            ],
            "type": "string"
          },
          "display_name": {
            "minLength": 1,
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "tax_number": {
            "type": "string"
          }
        },
        "required": [
          "customer_type",
          "category",
          "display_name"
        ],
        "type": "object"
      },
      "CreateDMARequest": {
        "properties": {
          "code": {
            "type": "string"
          },
          "inflow_meter_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "outflow_meter_id": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "target_pressure_bar": {
            "type": "number"
          }
        },
        "required": [
          "code",
          "name",
          "service_area_id"
        ],
        "type": "object"
      },
      "CreateDeveloperApiKey": {
        "properties": {
          "allowed_ips": {
            "description": "Optional IPs or CIDRs the key may be used from",
            "items": {
              "type": "string"
            },
            "maxItems": 50,
            "type": "array"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "kind": {
            "description": "Defaults to restricted when scopes are given and secret otherwise",
            "enum": [
              "secret",
              "restricted"
            ],
            "type": "string"
          },
          "mode": {
            "default": "live",
            "enum": [
              "live",
              "test"
            ],
            "type": "string"
          },
          "name": {
            "maxLength": 128,
            "type": "string"
          },
          "scopes": {
            "description": "Required for a restricted key; must be held by the caller",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CreateDeveloperCliSessionRequest": {
        "description": "Options for a CLI session.",
        "properties": {
          "events": {
            "description": "Event types to receive; empty or absent means every type.",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "CreateDeveloperRedelivery": {
        "properties": {
          "dry_run": {
            "type": "boolean"
          },
          "from": {
            "description": "Defaults to 24 hours before to",
            "format": "date-time",
            "type": "string"
          },
          "statuses": {
            "description": "Defaults to failed and paused",
            "items": {
              "enum": [
                "failed",
                "paused",
                "cancelled"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "to": {
            "description": "Defaults to now",
            "format": "date-time",
            "type": "string"
          },
          "types": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "CreateDeveloperWebhook": {
        "properties": {
          "description": {
            "maxLength": 512,
            "type": "string"
          },
          "enabled": {
            "default": true,
            "type": "boolean"
          },
          "events": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "description": "https; private, loopback and link-local targets are refused outside development",
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "url",
          "events"
        ],
        "type": "object"
      },
      "CreateIntegration": {
        "properties": {
          "category": {
            "enum": [
              "payment",
              "identity",
              "notification",
              "smart_meter",
              "gis",
              "scada",
              "document_store",
              "accounting",
              "erp"
            ],
            "type": "string"
          },
          "configuration_reference": {
            "type": "string"
          },
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "provider_key": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "category",
          "provider_key",
          "configuration_reference"
        ],
        "type": "object"
      },
      "CreateInterruptionRequest": {
        "properties": {
          "affected_customers_est": {
            "type": "integer"
          },
          "description": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "end_time": {
            "format": "date-time",
            "type": "string"
          },
          "interruption_type": {
            "enum": [
              "maintenance",
              "emergency",
              "rationing"
            ],
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "start_time": {
            "format": "date-time",
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "title",
          "service_area_id"
        ],
        "type": "object"
      },
      "CreateInventoryItemRequest": {
        "properties": {
          "code": {
            "maxLength": 64,
            "type": "string"
          },
          "description": {
            "maxLength": 500,
            "type": "string"
          },
          "is_meter": {
            "type": "boolean"
          },
          "kind": {
            "default": "bulk",
            "enum": [
              "bulk",
              "serialised"
            ],
            "type": "string"
          },
          "meter_diameter_mm": {
            "type": "integer"
          },
          "meter_manufacturer": {
            "type": "string"
          },
          "meter_model": {
            "type": "string"
          },
          "name": {
            "maxLength": 160,
            "type": "string"
          },
          "reorder_level": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reorder_levels": {
            "items": {
              "$ref": "#/components/schemas/InventoryReorderLevel"
            },
            "type": "array"
          },
          "standard_cost_minor": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "unit": {
            "default": "un",
            "enum": [
              "un",
              "m",
              "kg",
              "l",
              "cx",
              "rolo"
            ],
            "type": "string"
          }
        },
        "required": [
          "code",
          "name"
        ],
        "type": "object"
      },
      "CreateInventoryKitRequest": {
        "properties": {
          "code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryKitLine"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "work_order_type": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "name",
          "lines"
        ],
        "type": "object"
      },
      "CreateInventoryLocationRequest": {
        "properties": {
          "allow_negative": {
            "type": "boolean"
          },
          "code": {
            "maxLength": 64,
            "type": "string"
          },
          "crew_id": {
            "type": "string"
          },
          "kind": {
            "default": "warehouse",
            "enum": [
              "warehouse",
              "area",
              "van"
            ],
            "type": "string"
          },
          "member_user_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "maxLength": 160,
            "type": "string"
          },
          "parent_id": {
            "description": "Parent warehouse of a shelf area",
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "name"
        ],
        "type": "object"
      },
      "CreateInventoryStocktakeRequest": {
        "properties": {
          "location_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "location_id"
        ],
        "type": "object"
      },
      "CreateLinkRequest": {
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "from_node_id": {
            "type": "string"
          },
          "length_meters": {
            "type": "number"
          },
          "link_code": {
            "type": "string"
          },
          "link_type": {
            "$ref": "#/components/schemas/LinkType"
          },
          "roughness_coefficient": {
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/LinkStatus"
          },
          "to_node_id": {
            "type": "string"
          }
        },
        "required": [
          "link_code",
          "from_node_id",
          "to_node_id",
          "link_type"
        ],
        "type": "object"
      },
      "CreateMeter": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "device_status": {
            "description": "A warehouse or testing meter needs no account.",
            "enum": [
              "in_warehouse",
              "in_testing",
              "installed"
            ],
            "type": "string"
          },
          "dial_decimals": {
            "maximum": 3,
            "minimum": 0,
            "type": "integer"
          },
          "dial_digits": {
            "description": "Integer dial digits; derives maximum_reading (99999 for five digits).",
            "maximum": 9,
            "minimum": 1,
            "type": "integer"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "installed_at": {
            "format": "date-time",
            "type": "string"
          },
          "manufacturer": {
            "type": "string"
          },
          "maximum_reading": {
            "description": "Largest dial value; rollover modulus is this plus one smallest dial unit.",
            "type": "string"
          },
          "meter_type": {
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "precision": {
            "maximum": 9,
            "minimum": 0,
            "type": "integer"
          },
          "pulse_multiplier": {
            "type": "string"
          },
          "rollover_value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "account_id",
          "serial_number",
          "unit",
          "precision"
        ],
        "type": "object"
      },
      "CreateMeterCommand": {
        "properties": {
          "idempotency_key": {
            "maxLength": 160,
            "type": "string"
          },
          "parameters": {
            "additionalProperties": true,
            "type": "object"
          },
          "type": {
            "enum": [
              "read",
              "inspect",
              "synchronize",
              "reset-alarm",
              "disconnect",
              "reconnect"
            ],
            "type": "string"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "CreateNodeRequest": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "asset_id": {
            "description": "Existing asset to give a graph role; node_code is then ignored",
            "type": "string"
          },
          "device_id": {
            "type": "string"
          },
          "dma_id": {
            "description": "Required for dma_inlet",
            "type": "string"
          },
          "elevation_meters": {
            "type": "number"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "meter_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "node_code": {
            "description": "Required unless asset_id is set",
            "type": "string"
          },
          "node_type": {
            "$ref": "#/components/schemas/NodeType"
          },
          "service_area_id": {
            "type": "string"
          },
          "storage_capacity_m3": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "node_type"
        ],
        "type": "object"
      },
      "CreateNotificationIntent": {
        "properties": {
          "category": {
            "description": "Notification category used for quiet-hours and opt-out policy.",
            "type": "string"
          },
          "data": {
            "additionalProperties": true,
            "type": "object"
          },
          "delivery_plan": {
            "$ref": "#/components/schemas/NotificationDeliveryPlan"
          },
          "event_type": {
            "type": "string"
          },
          "idempotency_key": {
            "maxLength": 128,
            "type": "string"
          },
          "inbox_body": {
            "description": "Optional in-app message body; requires inbox_title and a consumer or staff recipient.",
            "maxLength": 2000,
            "type": "string"
          },
          "inbox_title": {
            "description": "Optional in-app message title; requires inbox_body and a consumer or staff recipient.",
            "maxLength": 160,
            "type": "string"
          },
          "priority": {
            "enum": [
              "critical",
              "high",
              "normal",
              "low"
            ],
            "type": "string"
          },
          "recipient_id": {
            "type": "string"
          },
          "recipient_type": {
            "maxLength": 32,
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "template_key": {
            "description": "Optional approved template identifier; not channel-specific content.",
            "type": "string"
          }
        },
        "required": [
          "event_type",
          "recipient_type",
          "recipient_id",
          "idempotency_key"
        ],
        "type": "object"
      },
      "CreateOrganization": {
        "properties": {
          "name": {
            "minLength": 1,
            "type": "string"
          },
          "utility_kind": {
            "enum": [
              "authority",
              "municipal",
              "regional",
              "national",
              "rural",
              "private",
              "industrial"
            ],
            "type": "string"
          }
        },
        "required": [
          "name",
          "utility_kind"
        ],
        "type": "object"
      },
      "CreatePaymentPlanRequest": {
        "properties": {
          "case_id": {
            "pattern": "^col_",
            "type": "string"
          },
          "first_due_date": {
            "format": "date-time",
            "type": "string"
          },
          "installment_count": {
            "default": 3,
            "maximum": 60,
            "minimum": 1,
            "type": "integer"
          },
          "interest_basis_points": {
            "minimum": 0,
            "type": "integer"
          },
          "interval_months": {
            "default": 1,
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "case_id"
        ],
        "type": "object"
      },
      "CreatePaymentSession": {
        "description": "Send an Idempotency-Key header to make creation retry-safe.",
        "properties": {
          "invoice_id": {
            "type": "string"
          },
          "method": {
            "description": "A checkout method code, as listed in the utility's checkout_methods in the consumer payment availability. The codes come from the utility's payment connectors; the server keeps no list of providers and refuses a method no live connector offers.",
            "pattern": "^[a-z][a-z0-9_-]{0,63}$",
            "type": "string"
          },
          "phone": {
            "description": "Required when the chosen checkout method has requires_phone set.",
            "type": "string"
          },
          "return_url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "invoice_id",
          "method"
        ],
        "type": "object"
      },
      "CreatePlanRequest": {
        "description": "name is required unless name_i18n has a text; it then defaults to the platform language's text.",
        "properties": {
          "capabilities": {
            "items": {
              "enum": [
                "configure",
                "customers",
                "meters",
                "draft_billing",
                "invoices",
                "payments",
                "messages",
                "public_profile",
                "custom_domain",
                "live_api",
                "sandbox"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "code": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "display_order": {
            "type": "integer"
          },
          "highlighted": {
            "type": "boolean"
          },
          "max_accounts": {
            "description": "Maximum accounts for the organization; 0 means no plan cap",
            "maximum": 1000,
            "minimum": 0,
            "type": "integer"
          },
          "max_connections": {
            "type": "integer"
          },
          "max_sandboxes": {
            "maximum": 50,
            "minimum": 0,
            "type": "integer"
          },
          "max_users": {
            "type": "integer"
          },
          "name": {
            "description": "The default display name",
            "type": "string"
          },
          "name_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "overage_connection_cents": {
            "type": "integer"
          },
          "overage_user_cents": {
            "type": "integer"
          },
          "price_cents": {
            "type": "integer"
          },
          "published": {
            "type": "boolean"
          },
          "tagline": {
            "description": "The default tagline",
            "maxLength": 255,
            "type": "string"
          },
          "tagline_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "trial_days": {
            "type": "integer"
          }
        },
        "required": [
          "code",
          "currency"
        ],
        "type": "object"
      },
      "CreateProperty": {
        "properties": {
          "address_line": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "district": {
            "type": "string"
          },
          "latitude": {
            "maximum": 90,
            "minimum": -90,
            "type": "number"
          },
          "locality": {
            "type": "string"
          },
          "longitude": {
            "maximum": 180,
            "minimum": -180,
            "type": "number"
          },
          "province": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          }
        },
        "required": [
          "customer_id",
          "address_line"
        ],
        "type": "object"
      },
      "CreatePublicContactRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when the challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "connections": {
            "description": "Optional number of service connections your organization runs",
            "minimum": 0,
            "type": "integer"
          },
          "email": {
            "description": "Reply address",
            "format": "email",
            "maxLength": 254,
            "type": "string"
          },
          "locale": {
            "default": "pt",
            "description": "Language to reply in",
            "enum": [
              "pt",
              "en"
            ],
            "type": "string"
          },
          "message": {
            "description": "Your message",
            "maxLength": 2000,
            "type": "string"
          },
          "name": {
            "description": "Your name",
            "maxLength": 120,
            "type": "string"
          },
          "organization": {
            "description": "Organization you represent",
            "maxLength": 160,
            "type": "string"
          },
          "phone": {
            "description": "Optional phone number",
            "maxLength": 40,
            "type": "string"
          },
          "topic": {
            "description": "What the request is about (case-insensitive)",
            "enum": [
              "sales",
              "support",
              "partnership",
              "press",
              "security"
            ],
            "type": "string"
          },
          "website": {
            "description": "Leave empty. Hidden form field; a filled value marks the request as automated and it is not stored",
            "type": "string"
          }
        },
        "required": [
          "topic",
          "name",
          "organization",
          "email",
          "message"
        ],
        "type": "object"
      },
      "CreatePublicDocsFeedback": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when the built-in challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "comment": {
            "description": "Optional comment",
            "maxLength": 500,
            "type": "string"
          },
          "helpful": {
            "description": "True when the page was helpful",
            "type": "boolean"
          },
          "locale": {
            "default": "pt",
            "description": "Language of the page",
            "enum": [
              "pt",
              "en"
            ],
            "type": "string"
          },
          "path": {
            "description": "Documentation page path; starts with / and contains no \"..\", \"?\" or \"#\"",
            "example": "/docs/api/authentication",
            "maxLength": 256,
            "pattern": "^/",
            "type": "string"
          }
        },
        "required": [
          "path",
          "helpful"
        ],
        "type": "object"
      },
      "CreateReadingAssignment": {
        "properties": {
          "due_at": {
            "format": "date-time",
            "type": "string"
          },
          "meter_ids": {
            "items": {
              "type": "string"
            },
            "maxItems": 500,
            "type": "array",
            "uniqueItems": true
          },
          "reader_id": {
            "type": "string"
          },
          "round_id": {
            "type": "string"
          }
        },
        "required": [
          "round_id",
          "reader_id"
        ],
        "type": "object"
      },
      "CreateReadingRound": {
        "properties": {
          "cycle_id": {
            "type": "string"
          },
          "route_id": {
            "type": "string"
          },
          "scheduled_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "route_id",
          "cycle_id",
          "scheduled_at"
        ],
        "type": "object"
      },
      "CreateReadingRoute": {
        "properties": {
          "meter_ids": {
            "items": {
              "type": "string"
            },
            "maxItems": 500,
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          },
          "name": {
            "maxLength": 255,
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "required": [
          "service_area_id",
          "name",
          "meter_ids"
        ],
        "type": "object"
      },
      "CreateSensorRequest": {
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "device_id": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "flow",
              "pressure",
              "level",
              "quality"
            ],
            "type": "string"
          },
          "location": {
            "type": "string"
          },
          "metric": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "code",
          "name",
          "device_id",
          "kind",
          "metric",
          "unit"
        ],
        "type": "object"
      },
      "CreateServiceArea": {
        "properties": {
          "name": {
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "name"
        ],
        "type": "object"
      },
      "CreateTeamInvitation": {
        "properties": {
          "email": {
            "description": "Required when phone is absent",
            "type": "string"
          },
          "full_name": {
            "type": "string"
          },
          "phone": {
            "description": "Required when email is absent",
            "type": "string"
          },
          "roles": {
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "roles"
        ],
        "type": "object"
      },
      "CreateTenant": {
        "properties": {
          "currency": {
            "default": "MZN",
            "type": "string"
          },
          "locale": {
            "default": "pt-MZ",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "owner_organization_id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "timezone": {
            "default": "Africa/Maputo",
            "type": "string"
          }
        },
        "required": [
          "owner_organization_id",
          "slug",
          "name"
        ],
        "type": "object"
      },
      "CreateUtilityTariffRequest": {
        "properties": {
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "charge_components": {
            "items": {
              "$ref": "#/components/schemas/UtilityTariffChargeComponent"
            },
            "type": "array"
          },
          "code": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "effective_from": {
            "format": "date-time",
            "type": "string"
          },
          "fixed_charges": {
            "items": {
              "$ref": "#/components/schemas/UtilityTariffFixedCharge"
            },
            "type": "array"
          },
          "fixed_fee_cents": {
            "format": "int64",
            "type": "integer"
          },
          "min_consumption_m3": {
            "type": "number"
          },
          "minimum_charge_cents": {
            "format": "int64",
            "type": "integer"
          },
          "minor_units": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "sanitation_surcharge_percent": {
            "type": "number"
          },
          "tax_percent": {
            "type": "number"
          },
          "tiers": {
            "items": {
              "$ref": "#/components/schemas/UtilityTariffTier"
            },
            "type": "array"
          }
        },
        "required": [
          "code",
          "name"
        ],
        "type": "object"
      },
      "CreateWaterResultRequest": {
        "properties": {
          "analyzed_at": {
            "format": "date-time",
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "parameter": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "type": "number"
          }
        },
        "required": [
          "parameter",
          "value",
          "unit"
        ],
        "type": "object"
      },
      "CreateWaterSampleRequest": {
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "collected_by": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "laboratory": {
            "type": "string"
          },
          "location_type": {
            "enum": [
              "reservoir",
              "zone"
            ],
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "sampled_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "code",
          "location_type",
          "sampled_at"
        ],
        "type": "object"
      },
      "CreateWorkOrderRequest": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "asset_id": {
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "crew_id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "kit_id": {
            "description": "A kit (kit_), or default for the order type's default kit",
            "type": "string"
          },
          "materials": {
            "items": {
              "$ref": "#/components/schemas/WorkOrderMaterialInput"
            },
            "type": "array"
          },
          "order_type": {
            "type": "string"
          },
          "priority": {
            "type": "string"
          },
          "required_skill": {
            "type": "string"
          },
          "scheduled_at": {
            "format": "date-time",
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "required": [
          "order_type",
          "description"
        ],
        "type": "object"
      },
      "CreditGrant": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "amount_minor": {
            "format": "int64",
            "type": "integer"
          },
          "applies_to": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "approved_by": {
            "type": "string"
          },
          "campaign_id": {
            "type": "string"
          },
          "charge_kinds": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "funding": {
            "enum": [
              "cash",
              "granted"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "proposed_by": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "rejection_reason": {
            "type": "string"
          },
          "remaining_minor": {
            "format": "int64",
            "type": "integer"
          },
          "source": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending_approval",
              "active",
              "exhausted",
              "expired",
              "rejected"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "account_id",
          "funding",
          "source",
          "amount_minor",
          "remaining_minor",
          "currency",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "CurrentSessionView": {
        "description": "The person and contexts of the current session. With a bearer token every field of CurrentUser is present; through the web session cookie only user, contexts and active_context are returned.",
        "properties": {
          "active_context": {
            "$ref": "#/components/schemas/AuthContext"
          },
          "contexts": {
            "items": {
              "$ref": "#/components/schemas/AuthContext"
            },
            "type": "array"
          },
          "organizations": {
            "description": "Organization memberships with no directly accessible workspace; bearer-token responses only.",
            "items": {
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "role": {
                  "description": "Comma-separated organization roles held by this person",
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "type",
                "role"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "roles": {
            "description": "Roles in the active context; bearer-token responses only.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scopes": {
            "description": "Scopes in the active context; bearer-token responses only.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user": {
            "$ref": "#/components/schemas/UserProfile"
          }
        },
        "required": [
          "user",
          "active_context",
          "contexts"
        ],
        "type": "object"
      },
      "CurrentUser": {
        "properties": {
          "active_context": {
            "$ref": "#/components/schemas/AuthContext"
          },
          "contexts": {
            "items": {
              "$ref": "#/components/schemas/AuthContext"
            },
            "type": "array"
          },
          "organizations": {
            "description": "Organization memberships with no directly accessible tenant account; visible account counts remain scoped to contexts.",
            "items": {
              "properties": {
                "id": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "role": {
                  "description": "Comma-separated organization roles held by this person",
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "required": [
                "id",
                "name",
                "type",
                "role"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "roles": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "user": {
            "$ref": "#/components/schemas/UserProfile"
          }
        },
        "required": [
          "user",
          "active_context",
          "contexts",
          "organizations",
          "roles",
          "scopes"
        ],
        "type": "object"
      },
      "CustomRequirementEvidence": {
        "properties": {
          "reason": {
            "type": "string"
          },
          "status": {
            "enum": [
              "submitted",
              "verified",
              "rejected",
              "expired"
            ],
            "type": "string"
          },
          "value": {
            "maxLength": 4000,
            "type": "string"
          }
        },
        "required": [
          "value",
          "status"
        ],
        "type": "object"
      },
      "Customer": {
        "properties": {
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "customer_type": {
            "enum": [
              "individual",
              "business"
            ],
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "email": {
            "format": "email",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "suspended",
              "closed"
            ],
            "type": "string"
          },
          "tax_number": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "customer_type",
          "category",
          "display_name",
          "status"
        ],
        "type": "object"
      },
      "CustomerImportConfirmRequest": {
        "properties": {
          "dry_run_id": {
            "type": "string"
          },
          "idempotency_key": {
            "description": "Or the Idempotency-Key header",
            "maxLength": 128,
            "type": "string"
          }
        },
        "required": [
          "dry_run_id"
        ],
        "type": "object"
      },
      "CustomerImportDryRunRequest": {
        "properties": {
          "csv": {
            "description": "CSV text with the header display_name[,customer_type,category,phone,email,tax_number]",
            "type": "string"
          }
        },
        "required": [
          "csv"
        ],
        "type": "object"
      },
      "CustomerImportResult": {
        "properties": {
          "confirmed": {
            "type": "boolean"
          },
          "created_count": {
            "type": "integer"
          },
          "dry_run_id": {
            "type": "string"
          },
          "error_rows": {
            "type": "integer"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "rows": {
            "items": {
              "properties": {
                "created": {
                  "type": "boolean"
                },
                "customer_id": {
                  "type": "string"
                },
                "data": {
                  "properties": {
                    "category": {
                      "type": "string"
                    },
                    "customer_type": {
                      "enum": [
                        "individual",
                        "business"
                      ],
                      "type": "string"
                    },
                    "display_name": {
                      "type": "string"
                    },
                    "email": {
                      "type": "string"
                    },
                    "phone": {
                      "type": "string"
                    },
                    "tax_number": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "errors": {
                  "items": {
                    "description": "One failed field of a row. reason is a stable code clients translate; code repeats it.",
                    "properties": {
                      "code": {
                        "enum": [
                          "required",
                          "too_long",
                          "invalid",
                          "invalid_customer_type",
                          "invalid_category",
                          "invalid_phone",
                          "invalid_email",
                          "duplicate",
                          "duplicate_in_file"
                        ],
                        "type": "string"
                      },
                      "duplicate_of_row": {
                        "description": "For duplicate_in_file",
                        "the earlier line with the same phone or e-mail": null,
                        "type": "integer"
                      },
                      "field": {
                        "description": "display_name, customer_type, category, phone, email, tax_number or row",
                        "type": "string"
                      },
                      "reason": {
                        "enum": [
                          "required",
                          "too_long",
                          "invalid",
                          "invalid_customer_type",
                          "invalid_category",
                          "invalid_phone",
                          "invalid_email",
                          "duplicate",
                          "duplicate_in_file"
                        ],
                        "type": "string"
                      }
                    },
                    "required": [
                      "field",
                      "reason",
                      "code"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "row": {
                  "description": "Line number in the file (the header is line 1)",
                  "type": "integer"
                }
              },
              "required": [
                "row",
                "data",
                "errors",
                "created"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "total_rows": {
            "type": "integer"
          },
          "valid_rows": {
            "type": "integer"
          }
        },
        "required": [
          "dry_run_id",
          "confirmed",
          "total_rows",
          "valid_rows",
          "error_rows",
          "created_count",
          "expires_at",
          "rows"
        ],
        "type": "object"
      },
      "CustomerPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Customer"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "DMABalance": {
        "properties": {
          "authorised_consumption_liters": {
            "format": "int64",
            "type": "integer"
          },
          "billed_consumption_liters": {
            "format": "int64",
            "type": "integer"
          },
          "consumption": {
            "properties": {
              "attribution": {
                "enum": [
                  "dma_taps",
                  "service_area",
                  "none"
                ],
                "type": "string"
              },
              "billed_records": {
                "type": "integer"
              },
              "meter_count": {
                "type": "integer"
              },
              "prorated": {
                "type": "boolean"
              },
              "skipped_records": {
                "type": "integer"
              },
              "unbilled_records": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "dma_code": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "estimated_consumption_liters": {
            "format": "int64",
            "type": "integer"
          },
          "export": {
            "$ref": "#/components/schemas/VolumeQuality"
          },
          "export_volume_liters": {
            "format": "int64",
            "type": "integer"
          },
          "inflow": {
            "$ref": "#/components/schemas/VolumeQuality"
          },
          "inflow_volume_liters": {
            "format": "int64",
            "type": "integer"
          },
          "loss_basis_points": {
            "format": "int64",
            "type": [
              "integer",
              "null"
            ]
          },
          "mass_conserved": {
            "type": "boolean"
          },
          "node_id": {
            "type": "string"
          },
          "non_revenue_water_liters": {
            "format": "int64",
            "type": "integer"
          },
          "outflow_volume_liters": {
            "description": "Authorised consumption plus export",
            "format": "int64",
            "type": "integer"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "physically_valid": {
            "type": "boolean"
          },
          "status": {
            "enum": [
              "computed",
              "partial_data",
              "insufficient_data"
            ],
            "type": "string"
          },
          "storage": {
            "$ref": "#/components/schemas/VolumeQuality"
          },
          "storage_delta_liters": {
            "format": "int64",
            "type": "integer"
          },
          "tolerance_basis_points": {
            "format": "int64",
            "type": "integer"
          },
          "unaccounted_loss_liters": {
            "format": "int64",
            "type": "integer"
          },
          "unbilled_metered_consumption_liters": {
            "format": "int64",
            "type": "integer"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "DayCollections": {
        "properties": {
          "date": {
            "format": "date",
            "type": "string"
          },
          "hours": {
            "description": "All 24 local hours in order",
            "items": {
              "properties": {
                "collected_cents": {
                  "format": "int64",
                  "type": "integer"
                },
                "hour": {
                  "maximum": 23,
                  "minimum": 0,
                  "type": "integer"
                },
                "payments": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "total_cents": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "DeadJobPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DeadJobView"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "DeadJobView": {
        "properties": {
          "attempts": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "dead_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "last_error": {
            "type": "string"
          },
          "retried_at": {
            "format": "date-time",
            "type": "string"
          },
          "retried_job_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "kind",
          "attempts",
          "dead_at",
          "created_at"
        ],
        "type": "object"
      },
      "DeclineQuoteInput": {
        "properties": {
          "note": {
            "maxLength": 1000,
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeclineReason": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "code": {
            "pattern": "^[a-z0-9_]{1,64}$",
            "type": "string"
          },
          "label": {
            "maxLength": 255,
            "type": "string"
          },
          "position": {
            "type": "integer"
          }
        },
        "required": [
          "code",
          "label",
          "active"
        ],
        "type": "object"
      },
      "DeclineReasonList": {
        "properties": {
          "customized": {
            "description": "False while the tenant still uses the shipped template",
            "type": "boolean"
          },
          "reasons": {
            "items": {
              "$ref": "#/components/schemas/DeclineReason"
            },
            "type": "array"
          }
        },
        "required": [
          "reasons",
          "customized"
        ],
        "type": "object"
      },
      "DeclineServiceRequestInput": {
        "properties": {
          "note": {
            "maxLength": 1000,
            "type": "string"
          },
          "reason": {
            "description": "An active code from GET $BUSINESS_API/service-request-decline-reasons",
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "type": "object"
      },
      "DelegateList": {
        "properties": {
          "data": {
            "items": {
              "properties": {
                "id": {
                  "type": "string"
                },
                "identity_id": {
                  "type": "string"
                },
                "kind": {
                  "enum": [
                    "membership",
                    "invitation"
                  ],
                  "type": "string"
                },
                "permissions": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                },
                "recipient": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "DeveloperApiKey": {
        "properties": {
          "allowed_ips": {
            "description": "IPs or CIDRs the key may be used from; empty allows any",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "secret",
              "restricted"
            ],
            "type": "string"
          },
          "last_four": {
            "type": "string"
          },
          "last_used_at": {
            "format": "date-time",
            "type": "string"
          },
          "last_used_ip": {
            "type": "string"
          },
          "mode": {
            "enum": [
              "live",
              "test"
            ],
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "prefix": {
            "description": "Leading characters shown in listings",
            "example": "sk_live_ab12",
            "type": "string"
          },
          "revoked_at": {
            "format": "date-time",
            "type": "string"
          },
          "rolled_from_id": {
            "type": "string"
          },
          "rolled_to_id": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "secret": {
            "description": "The full key; present only on the create and roll responses. Prefixes: sk_live_, sk_test_, sk_rlive_, sk_rtest_",
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "expired",
              "revoked"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "kind",
          "mode",
          "prefix",
          "last_four",
          "scopes",
          "status",
          "created_by",
          "created_at"
        ],
        "type": "object"
      },
      "DeveloperApiKeyPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DeveloperApiKey"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperCliSession": {
        "description": "A temporary webhook endpoint for the CLI's webhooks listen command.",
        "properties": {
          "created_at": {
            "description": "When the session was opened.",
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "description": "User who opened the session; only they can poll or end it.",
            "type": "string"
          },
          "events": {
            "description": "Event types the session receives; empty means every type.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "expires_at": {
            "description": "When the session ends unless polled again.",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Session identifier, starting with cls_.",
            "type": "string"
          },
          "secret": {
            "description": "The whsec_ signing secret, present only in the response that opens the session.",
            "type": "string"
          },
          "tenant_id": {
            "description": "Tenant the session listens to.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "events",
          "created_by",
          "created_at",
          "expires_at"
        ],
        "type": "object"
      },
      "DeveloperCliSessionEvent": {
        "description": "One event as a webhook endpoint receives it, signed with the session secret.",
        "properties": {
          "created_at": {
            "description": "When the event was published.",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Event identifier.",
            "type": "string"
          },
          "payload": {
            "additionalProperties": true,
            "description": "The event body exactly as webhook endpoints receive it.",
            "type": "object"
          },
          "type": {
            "description": "Event type, for example invoice.paid.",
            "type": "string"
          },
          "webhook_id": {
            "description": "Value for the webhook-id header.",
            "type": "string"
          },
          "webhook_signature": {
            "description": "Value for the webhook-signature header (v1,<base64 HMAC-SHA256>).",
            "type": "string"
          },
          "webhook_timestamp": {
            "description": "Value for the webhook-timestamp header (Unix seconds).",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "type",
          "created_at",
          "payload",
          "webhook_id",
          "webhook_timestamp",
          "webhook_signature"
        ],
        "type": "object"
      },
      "DeveloperCliSessionPoll": {
        "description": "Events handed to a CLI session by one poll.",
        "properties": {
          "data": {
            "description": "Events since the previous poll, oldest first.",
            "items": {
              "$ref": "#/components/schemas/DeveloperCliSessionEvent"
            },
            "type": "array"
          },
          "expires_at": {
            "description": "When the session ends unless polled again.",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "data",
          "expires_at"
        ],
        "type": "object"
      },
      "DeveloperDelivery": {
        "properties": {
          "attempts": {
            "type": "integer"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "duration_ms": {
            "type": "integer"
          },
          "event_id": {
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "history": {
            "items": {
              "properties": {
                "attempt": {
                  "type": "integer"
                },
                "duration_ms": {
                  "type": "integer"
                },
                "error": {
                  "type": "string"
                },
                "occurred_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "response_body": {
                  "type": "string"
                },
                "response_status": {
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "last_error": {
            "type": "string"
          },
          "max_attempts": {
            "type": "integer"
          },
          "next_attempt_at": {
            "format": "date-time",
            "type": "string"
          },
          "payload": {
            "description": "JSON event body; on the detail read",
            "type": "string"
          },
          "response_status": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending",
              "delivering",
              "succeeded",
              "failed",
              "cancelled",
              "paused"
            ],
            "type": "string"
          },
          "url": {
            "type": "string"
          },
          "webhook_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperDeliveryPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DeveloperDelivery"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperEvent": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "deliveries": {
            "items": {
              "$ref": "#/components/schemas/DeveloperDelivery"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "payload": {
            "description": "Signed JSON body; on the detail read",
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperEventPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DeveloperEvent"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperEventTypes": {
        "properties": {
          "data": {
            "items": {
              "properties": {
                "category": {
                  "type": "string"
                },
                "description": {
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "DeveloperOverview": {
        "properties": {
          "active_api_keys": {
            "type": "integer"
          },
          "bucket_seconds": {
            "type": "integer"
          },
          "enabled_webhooks": {
            "type": "integer"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "requests": {
            "properties": {
              "client_errors": {
                "type": "integer"
              },
              "error_rate": {
                "type": "number"
              },
              "p50_ms": {
                "type": "integer"
              },
              "p95_ms": {
                "type": "integer"
              },
              "series": {
                "items": {
                  "properties": {
                    "errors": {
                      "type": "integer"
                    },
                    "requests": {
                      "type": "integer"
                    },
                    "start": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "server_errors": {
                "type": "integer"
              },
              "total": {
                "type": "integer"
              }
            },
            "type": "object"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          },
          "webhooks": {
            "properties": {
              "failed": {
                "type": "integer"
              },
              "pending": {
                "type": "integer"
              },
              "succeeded": {
                "type": "integer"
              },
              "success_rate": {
                "type": "number"
              },
              "total": {
                "type": "integer"
              }
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "DeveloperRedelivery": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "dry_run": {
            "type": "boolean"
          },
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "wrd_ identifier; empty on a dry run",
            "type": "string"
          },
          "requeued": {
            "description": "Deliveries re-queued, or that would be on a dry run",
            "type": "integer"
          },
          "statuses": {
            "items": {
              "enum": [
                "failed",
                "paused",
                "cancelled"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          },
          "types": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "webhook_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperRequestLog": {
        "properties": {
          "api_key_id": {
            "type": "string"
          },
          "api_key_prefix": {
            "type": "string"
          },
          "duration_ms": {
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "ip": {
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "occurred_at": {
            "format": "date-time",
            "type": "string"
          },
          "path": {
            "type": "string"
          },
          "principal_id": {
            "type": "string"
          },
          "principal_type": {
            "type": "string"
          },
          "request_body": {
            "description": "Redacted; on the detail read",
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "response_body": {
            "description": "Redacted; on the detail read",
            "type": "string"
          },
          "status": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "DeveloperRequestLogPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DeveloperRequestLog"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeveloperRoll": {
        "properties": {
          "overlap_seconds": {
            "description": "How long the old key or secret keeps working; default 86400",
            "maximum": 604800,
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "DeveloperScopes": {
        "properties": {
          "data": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "DeveloperWebhook": {
        "properties": {
          "api_version": {
            "type": "string"
          },
          "consecutive_failures": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "events": {
            "description": "Event types, or * for all",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "failing_since": {
            "format": "date-time",
            "type": "string"
          },
          "health": {
            "enum": [
              "healthy",
              "degraded",
              "failing",
              "paused_automatically",
              "paused_by_owner"
            ],
            "type": "string"
          },
          "health_changed_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "paused_reason": {
            "type": "string"
          },
          "previous_secret_expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "secret": {
            "description": "The signing secret; present only on the create and roll responses",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "id",
          "url",
          "description",
          "events",
          "enabled",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "DeveloperWebhookPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DeveloperWebhook"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "DeviceCodeApproval": {
        "properties": {
          "approved": {
            "const": true,
            "type": "boolean"
          },
          "context_id": {
            "description": "Context the device will be signed in to.",
            "type": "string"
          },
          "device_name": {
            "description": "Device name given when the code was requested; empty when none was given.",
            "type": "string"
          },
          "location": {
            "description": "Device location given when the code was requested; empty when none was given.",
            "type": "string"
          },
          "user_code": {
            "description": "The approved user code, normalised.",
            "example": "ABCD-EFGH",
            "type": "string"
          }
        },
        "required": [
          "approved",
          "user_code",
          "device_name",
          "location",
          "context_id"
        ],
        "type": "object"
      },
      "DeviceCodeGrant": {
        "properties": {
          "device_code": {
            "description": "Secret code the device sends to pollDeviceToken. Keep it on the device.",
            "type": "string"
          },
          "expires_in": {
            "description": "Seconds until both codes expire.",
            "example": 300,
            "type": "integer"
          },
          "interval": {
            "description": "Minimum seconds between polls.",
            "example": 5,
            "type": "integer"
          },
          "user_code": {
            "description": "Short code the person enters to approve the sign-in.",
            "example": "ABCD-EFGH",
            "type": "string"
          },
          "verification_uri": {
            "description": "Page where the signed-in person enters the user code.",
            "example": "https://app.example.test/device",
            "type": "string"
          }
        },
        "required": [
          "device_code",
          "user_code",
          "verification_uri",
          "expires_in",
          "interval"
        ],
        "type": "object"
      },
      "DisconnectionNotice": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "case_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "cutoff_date": {
            "format": "date-time",
            "type": "string"
          },
          "delivered_via": {
            "enum": [
              "email",
              "physical"
            ],
            "type": "string"
          },
          "id": {
            "pattern": "^not_",
            "type": "string"
          },
          "notice_date": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "issued",
              "delivered",
              "resolved"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "case_id",
          "account_id",
          "notice_date",
          "cutoff_date",
          "delivered_via",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "DistrictMeteredArea": {
        "properties": {
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "pattern": "^dma_",
            "type": "string"
          },
          "inflow_meter_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "outflow_meter_id": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "target_pressure_bar": {
            "type": "number"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "code",
          "name",
          "service_area_id",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "DistrictMeteredAreaPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/DistrictMeteredArea"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "EmailVerificationConfirm": {
        "properties": {
          "code": {
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        },
        "required": [
          "email",
          "code"
        ],
        "type": "object"
      },
      "EmailVerificationRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "email": {
            "type": "string"
          }
        },
        "required": [
          "email"
        ],
        "type": "object"
      },
      "EnrollPrepaidMeterRequest": {
        "additionalProperties": false,
        "properties": {
          "meter_id": {
            "type": "string"
          },
          "tariff_id": {
            "type": "string"
          },
          "vending_key_ref": {
            "type": "string"
          }
        },
        "required": [
          "meter_id"
        ],
        "type": "object"
      },
      "EnterpriseLdapConnection": {
        "description": "The tenant's directory connection as stored. The service account password is never included; has_bind_password tells whether one is set.",
        "properties": {
          "base_dn": {
            "description": "Search base for user entries.",
            "type": "string"
          },
          "bind_dn": {
            "description": "Distinguished name of the service account, when set.",
            "type": "string"
          },
          "ca_certificate": {
            "description": "PEM-encoded CA certificate trusted for the server, when set.",
            "type": "string"
          },
          "created_at": {
            "description": "When the connection was first saved.",
            "format": "date-time",
            "type": "string"
          },
          "default_roles": {
            "description": "Roles given to users that match no group mapping.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "email_attribute": {
            "description": "Attribute holding the email address.",
            "type": "string"
          },
          "enabled": {
            "description": "Whether directory sign-in and synchronization are active.",
            "type": "boolean"
          },
          "group_base_dn": {
            "description": "Search base for groups, when set.",
            "type": "string"
          },
          "group_mappings": {
            "description": "Directory groups mapped to tenant roles.",
            "items": {
              "$ref": "#/components/schemas/EnterpriseLdapGroupMapping"
            },
            "type": "array"
          },
          "has_bind_password": {
            "description": "Whether a service account password is stored. The password itself is never returned.",
            "type": "boolean"
          },
          "id": {
            "description": "Connection identifier.",
            "example": "ldp_01JD3X8Q7M2N4P5R6S7T8V9W0X",
            "type": "string"
          },
          "last_sync_at": {
            "description": "When the last synchronization finished, if one has run.",
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "description": "Display name for the connection.",
            "type": "string"
          },
          "name_attribute": {
            "description": "Attribute holding the display name.",
            "type": "string"
          },
          "server_url": {
            "description": "Directory server address.",
            "example": "ldaps://dc01.example.com:636",
            "type": "string"
          },
          "start_tls": {
            "description": "Whether an ldap:// connection is upgraded with StartTLS.",
            "type": "boolean"
          },
          "sync_interval_minutes": {
            "description": "Minutes between automatic synchronizations.",
            "type": "integer"
          },
          "tenant_id": {
            "description": "Tenant that owns the connection.",
            "example": "tenant_alpha",
            "type": "string"
          },
          "updated_at": {
            "description": "When the connection was last saved.",
            "format": "date-time",
            "type": "string"
          },
          "user_filter": {
            "description": "Extra LDAP filter clause, when set.",
            "type": "string"
          },
          "username_attribute": {
            "description": "Attribute holding the sign-in name.",
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnterpriseLdapConnectionInput": {
        "description": "Directory (LDAP or Active Directory) settings to save for the caller's tenant. Other fields, such as id, tenant_id or timestamps echoed from a read, are ignored: the connection saved is always the caller's tenant's. bind_password is write-only: send it to set or replace the service account password, or omit it (or send an empty string) to keep the stored one.",
        "properties": {
          "base_dn": {
            "description": "Search base for user entries. Required.",
            "example": "OU=Staff,DC=example,DC=com",
            "type": "string"
          },
          "bind_dn": {
            "description": "Distinguished name of the service account used to search the directory.",
            "example": "CN=svc-sync,OU=Service,DC=example,DC=com",
            "type": "string"
          },
          "bind_password": {
            "description": "Service account password, at most 128 bytes. Write-only: it is stored encrypted and never returned; has_bind_password on a read tells whether one is set. Omit it to keep the stored password.",
            "maxLength": 128,
            "type": "string",
            "writeOnly": true
          },
          "ca_certificate": {
            "description": "PEM-encoded CA certificate used to verify the server's TLS certificate, when it is not publicly trusted.",
            "type": "string"
          },
          "default_roles": {
            "description": "Roles given to synchronized users that match no group mapping. Defaults to [\"operations\"].",
            "example": [
              "operations"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "email_attribute": {
            "description": "Attribute holding the email address. Letters, digits, underscore and hyphen only. Defaults to mail.",
            "example": "mail",
            "type": "string"
          },
          "enabled": {
            "description": "Whether directory sign-in and synchronization are active. Synchronization refuses a disabled connection.",
            "type": "boolean"
          },
          "group_base_dn": {
            "description": "Search base for groups.",
            "type": "string"
          },
          "group_mappings": {
            "description": "Directory groups mapped to tenant roles.",
            "items": {
              "$ref": "#/components/schemas/EnterpriseLdapGroupMapping"
            },
            "type": "array"
          },
          "name": {
            "description": "Display name for the connection.",
            "example": "Head office directory",
            "type": "string"
          },
          "name_attribute": {
            "description": "Attribute holding the display name. Letters, digits, underscore and hyphen only. Defaults to displayName.",
            "example": "displayName",
            "type": "string"
          },
          "server_url": {
            "description": "Directory server address. Must use the ldap:// or ldaps:// scheme and include a host. Outside development, ldap:// requires start_tls true, and internal host names (localhost, *.local, *.internal) and private or link-local addresses are refused.",
            "example": "ldaps://dc01.example.com:636",
            "type": "string"
          },
          "start_tls": {
            "description": "Upgrade an ldap:// connection with StartTLS before binding.",
            "type": "boolean"
          },
          "sync_interval_minutes": {
            "description": "Minutes between automatic synchronizations. Zero or negative values default to 60.",
            "example": 60,
            "type": "integer"
          },
          "user_filter": {
            "description": "Extra LDAP filter clause combined with the built-in user filter, without outer parentheses.",
            "example": "objectClass=user",
            "type": "string"
          },
          "username_attribute": {
            "description": "Attribute holding the sign-in name. Letters, digits, underscore and hyphen only. Defaults to sAMAccountName.",
            "example": "sAMAccountName",
            "type": "string"
          }
        },
        "required": [
          "server_url",
          "base_dn"
        ],
        "type": "object"
      },
      "EnterpriseLdapGroupMapping": {
        "description": "Maps members of one directory group to a tenant role.",
        "properties": {
          "group_dn": {
            "description": "Distinguished name of the directory group.",
            "example": "CN=Billing,OU=Groups,DC=example,DC=com",
            "type": "string"
          },
          "role": {
            "description": "Tenant role granted to members of the group.",
            "example": "finance",
            "type": "string"
          }
        },
        "required": [
          "group_dn",
          "role"
        ],
        "type": "object"
      },
      "EnterpriseLdapSyncResult": {
        "description": "Counts from one directory synchronization run.",
        "properties": {
          "created": {
            "description": "Members created in the tenant.",
            "type": "integer"
          },
          "disabled": {
            "description": "Members suspended because their directory account is disabled or locked out.",
            "type": "integer"
          },
          "duration_ms": {
            "description": "Duration of the run, in milliseconds.",
            "format": "int64",
            "type": "integer"
          },
          "total_found": {
            "description": "Directory entries returned by the search (at most 1000 per run).",
            "example": 214,
            "type": "integer"
          },
          "updated": {
            "description": "Existing members updated from the directory.",
            "type": "integer"
          }
        },
        "required": [
          "total_found",
          "created",
          "updated",
          "disabled",
          "duration_ms"
        ],
        "type": "object"
      },
      "EnterpriseLdapTestResult": {
        "description": "Outcome of a live connectivity test. A failed connection or bind is reported here with success false, not as an error status.",
        "properties": {
          "latency_ms": {
            "description": "Time the test took, in milliseconds.",
            "example": 84,
            "format": "int64",
            "type": "integer"
          },
          "message": {
            "description": "Human-readable result, including the failure reason when success is false.",
            "type": "string"
          },
          "server_type": {
            "description": "Server family detected from the root DSE, for example Generic LDAPv3.",
            "example": "Generic LDAPv3",
            "type": "string"
          },
          "success": {
            "description": "Whether the server was reached and the service account bind (when configured) succeeded.",
            "type": "boolean"
          }
        },
        "required": [
          "success",
          "latency_ms",
          "message"
        ],
        "type": "object"
      },
      "EnterpriseSamlIdpSettings": {
        "description": "Connection settings extracted from SAML identity provider metadata, ready to send in a save request.",
        "properties": {
          "idp_certificate": {
            "description": "Signing certificate from the metadata.",
            "type": "string"
          },
          "idp_entity_id": {
            "description": "Identity provider entity ID.",
            "example": "https://idp.example.com/",
            "type": "string"
          },
          "idp_slo_url": {
            "description": "Single logout URL, when the metadata declares one.",
            "type": "string"
          },
          "idp_sso_url": {
            "description": "Single sign-on URL.",
            "example": "https://idp.example.com/sso",
            "type": "string"
          }
        },
        "required": [
          "idp_entity_id",
          "idp_sso_url",
          "idp_certificate"
        ],
        "type": "object"
      },
      "EnterpriseSamlMetadataRequest": {
        "description": "A SAML identity provider metadata document to parse.",
        "properties": {
          "xml": {
            "description": "The metadata XML document as a string, at most 1 MiB, containing an IDPSSODescriptor.",
            "example": "<EntityDescriptor xmlns=\"urn:oasis:names:tc:SAML:2.0:metadata\" entityID=\"https://idp.example.com/\">...</EntityDescriptor>",
            "type": "string"
          }
        },
        "required": [
          "xml"
        ],
        "type": "object"
      },
      "EnterpriseScimToken": {
        "description": "A SCIM directory token. Its secret cannot be recovered after creation.",
        "properties": {
          "created_at": {
            "description": "When the token was issued.",
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "description": "When the token stops working. Absent for tokens that never expire.",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Token identifier, used to revoke it.",
            "example": "sct_01JD3X8Q7M2N4P5R6S7T8V9W0X",
            "type": "string"
          },
          "last_used_at": {
            "description": "When the token last authenticated a SCIM request.",
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "description": "Label for the token.",
            "type": "string"
          },
          "tenant_id": {
            "description": "Tenant whose directory the token can provision.",
            "example": "tenant_alpha",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "name",
          "created_at"
        ],
        "type": "object"
      },
      "EnterpriseScimTokenCreate": {
        "description": "Options for a new SCIM directory token. An empty object is accepted.",
        "properties": {
          "expires_in_days": {
            "description": "Lifetime in days. 0 or omitted means the token never expires.",
            "example": 90,
            "type": "integer"
          },
          "name": {
            "description": "Label for the token. Defaults to \"Default SCIM Directory Sync\".",
            "example": "Identity provider sync",
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnterpriseScimTokenCreated": {
        "allOf": [
          {
            "$ref": "#/components/schemas/EnterpriseScimToken"
          },
          {
            "properties": {
              "token": {
                "description": "The bearer secret for the SCIM API. Shown only in this response; only its SHA-256 digest is stored, so it cannot be retrieved again.",
                "example": "scim_live_3f9a0c2e7b1d4f6a8c0e2b4d6f8a0c2e4b6d8f0a2c4e6b8d0f2a4c6e8b0d2f4a",
                "type": "string"
              }
            },
            "required": [
              "token"
            ],
            "type": "object"
          }
        ]
      },
      "EnterpriseSsoAttributeMapping": {
        "description": "Names of the identity provider attributes or claims to read. Empty values use the protocol defaults.",
        "properties": {
          "email": {
            "description": "Attribute or claim holding the email address.",
            "example": "email",
            "type": "string"
          },
          "groups": {
            "description": "Attribute or claim holding group memberships.",
            "example": "groups",
            "type": "string"
          },
          "name": {
            "description": "Attribute or claim holding the display name.",
            "example": "name",
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnterpriseSsoConnection": {
        "description": "A tenant's single sign-on connection. Secrets are never included: the OIDC client secret is reported only through has_client_secret, and the service provider private key is never returned.",
        "properties": {
          "attribute_mapping": {
            "$ref": "#/components/schemas/EnterpriseSsoAttributeMapping"
          },
          "client_id": {
            "description": "OIDC client identifier.",
            "type": "string"
          },
          "created_at": {
            "description": "When the connection was created.",
            "format": "date-time",
            "type": "string"
          },
          "default_roles": {
            "description": "Roles given to people who match no group mapping.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "discovery_url": {
            "description": "OIDC issuer discovery URL.",
            "type": "string"
          },
          "domain": {
            "description": "Email domain the connection serves.",
            "example": "example.com",
            "type": "string"
          },
          "domain_verification_token": {
            "description": "Token to publish in the DNS TXT record that proves control of the domain.",
            "type": "string"
          },
          "domain_verified_at": {
            "description": "When control of the domain was proven. Absent until verified.",
            "format": "date-time",
            "type": "string"
          },
          "enabled": {
            "description": "Whether people can sign in through this connection.",
            "type": "boolean"
          },
          "enforce_sso": {
            "description": "Whether password sign-in is refused for addresses in the verified domain.",
            "type": "boolean"
          },
          "group_role_mappings": {
            "description": "Identity provider groups mapped to tenant roles.",
            "items": {
              "$ref": "#/components/schemas/EnterpriseSsoGroupMapping"
            },
            "type": "array"
          },
          "has_client_secret": {
            "description": "Whether an OIDC client secret is stored.",
            "type": "boolean"
          },
          "id": {
            "description": "Connection identifier.",
            "example": "sso_01JD3X8Q7M2N4P5R6S7T8V9W0X",
            "type": "string"
          },
          "idp_certificate": {
            "description": "SAML identity provider signing certificate.",
            "type": "string"
          },
          "idp_entity_id": {
            "description": "SAML identity provider entity ID.",
            "type": "string"
          },
          "idp_slo_url": {
            "description": "SAML single logout URL.",
            "type": "string"
          },
          "idp_sso_url": {
            "description": "SAML single sign-on URL.",
            "type": "string"
          },
          "name": {
            "description": "Display name for the connection.",
            "type": "string"
          },
          "provider_type": {
            "description": "Protocol of the identity provider.",
            "enum": [
              "saml",
              "oidc"
            ],
            "type": "string"
          },
          "sp_certificate": {
            "description": "Service provider certificate generated for SAML connections, to register with the identity provider.",
            "type": "string"
          },
          "sp_entity_id": {
            "description": "Service provider entity ID.",
            "type": "string"
          },
          "tenant_id": {
            "description": "Tenant that owns the connection.",
            "example": "tenant_alpha",
            "type": "string"
          },
          "updated_at": {
            "description": "When the connection was last changed.",
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "EnterpriseSsoConnectionInput": {
        "description": "Single sign-on settings for a tenant, using SAML 2.0 or OpenID Connect. Unknown fields are rejected. client_secret is write-only: send it to set or replace the OIDC client secret, or omit it to keep the stored one.",
        "properties": {
          "attribute_mapping": {
            "$ref": "#/components/schemas/EnterpriseSsoAttributeMapping"
          },
          "client_id": {
            "description": "OIDC client identifier. Required for oidc.",
            "type": "string"
          },
          "client_secret": {
            "description": "OIDC client secret. Write-only: it is encrypted at rest and never returned; reads report has_client_secret instead. Required for oidc unless one is already stored.",
            "type": "string",
            "writeOnly": true
          },
          "default_roles": {
            "description": "Roles given to people signing in who match no group mapping. Defaults to [\"operations\"]; owner is refused.",
            "example": [
              "operations"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "discovery_url": {
            "description": "OIDC issuer discovery URL. Required for oidc; must be a public https address.",
            "example": "https://login.example.com/.well-known/openid-configuration",
            "format": "uri",
            "type": "string"
          },
          "domain": {
            "description": "Email domain the connection serves, as a hostname (stored lower-case). Changing the domain resets its verification.",
            "example": "example.com",
            "type": "string"
          },
          "enabled": {
            "description": "Whether people can sign in through this connection.",
            "type": "boolean"
          },
          "enforce_sso": {
            "description": "When true, password sign-in is refused for addresses in the verified domain.",
            "type": "boolean"
          },
          "group_role_mappings": {
            "description": "Identity provider groups mapped to tenant roles.",
            "items": {
              "$ref": "#/components/schemas/EnterpriseSsoGroupMapping"
            },
            "type": "array"
          },
          "idp_certificate": {
            "description": "PEM or base64 X.509 signing certificate of the SAML identity provider. Required for saml.",
            "type": "string"
          },
          "idp_entity_id": {
            "description": "SAML identity provider entity ID. Required for saml.",
            "type": "string"
          },
          "idp_slo_url": {
            "description": "SAML single logout URL, optional; must be a public https address when set.",
            "format": "uri",
            "type": "string"
          },
          "idp_sso_url": {
            "description": "SAML single sign-on URL. Required for saml; must be a public https address.",
            "format": "uri",
            "type": "string"
          },
          "name": {
            "description": "Display name for the connection.",
            "example": "Corporate sign-in",
            "type": "string"
          },
          "provider_type": {
            "description": "Protocol of the identity provider (case-insensitive).",
            "enum": [
              "saml",
              "oidc"
            ],
            "type": "string"
          },
          "sp_entity_id": {
            "description": "Service provider entity ID to present to the identity provider, when it must differ from the default.",
            "type": "string"
          }
        },
        "required": [
          "provider_type",
          "domain"
        ],
        "type": "object"
      },
      "EnterpriseSsoGroupMapping": {
        "description": "Maps an identity provider group to a tenant role.",
        "properties": {
          "group": {
            "description": "Group name or identifier as the identity provider sends it. Must not be blank.",
            "example": "utility-finance",
            "type": "string"
          },
          "role": {
            "description": "Tenant role granted to members of the group. The owner role cannot be granted this way.",
            "example": "finance",
            "type": "string"
          }
        },
        "required": [
          "group",
          "role"
        ],
        "type": "object"
      },
      "EnterpriseSsoTestCheck": {
        "description": "One check performed against the identity provider.",
        "properties": {
          "detail": {
            "description": "Explanation, usually present when the check failed.",
            "type": "string"
          },
          "name": {
            "description": "Check name, for example domain_verified.",
            "example": "domain_verified",
            "type": "string"
          },
          "passed": {
            "description": "Whether the check passed.",
            "type": "boolean"
          }
        },
        "required": [
          "name",
          "passed"
        ],
        "type": "object"
      },
      "EnterpriseSsoTestResult": {
        "description": "Result of probing the tenant's configured identity provider.",
        "properties": {
          "checks": {
            "description": "Individual checks, starting with domain_verified.",
            "items": {
              "$ref": "#/components/schemas/EnterpriseSsoTestCheck"
            },
            "type": "array"
          },
          "domain": {
            "description": "Domain of the tested connection.",
            "type": "string"
          },
          "enabled": {
            "description": "Whether the connection is enabled.",
            "type": "boolean"
          },
          "name": {
            "description": "Display name of the tested connection.",
            "type": "string"
          },
          "provider_type": {
            "description": "Protocol of the tested connection.",
            "enum": [
              "saml",
              "oidc"
            ],
            "type": "string"
          },
          "valid": {
            "description": "True when every check passed.",
            "type": "boolean"
          }
        },
        "required": [
          "valid",
          "provider_type",
          "domain",
          "name",
          "enabled",
          "checks"
        ],
        "type": "object"
      },
      "FieldVisit": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "assignment_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "cycle_id": {
            "type": "string"
          },
          "evidence_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "outcome": {
            "enum": [
              "read",
              "inaccessible",
              "damaged",
              "not_found"
            ],
            "type": "string"
          },
          "reader_id": {
            "type": "string"
          },
          "reading_id": {
            "type": "string"
          },
          "revisit_reason": {
            "type": "string"
          },
          "revisit_required": {
            "type": "boolean"
          },
          "revisit_scheduled_at": {
            "format": "date-time",
            "type": "string"
          },
          "route_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "visited_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "account_id",
          "reader_id",
          "visited_at",
          "outcome",
          "revisit_required",
          "created_at"
        ],
        "type": "object"
      },
      "FieldVisitPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/FieldVisit"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "FirstRunAbandonRequest": {
        "additionalProperties": false,
        "properties": {
          "journey_id": {
            "description": "Only for the public route",
            "example": "resident_link",
            "type": "string",
            "which has no journey in its anonymous token": null
          },
          "run_token": {
            "description": "Opaque run token",
            "type": "string"
          },
          "step_id": {
            "example": "open_todays_route",
            "type": "string"
          }
        },
        "required": [
          "run_token",
          "step_id"
        ],
        "type": "object"
      },
      "FirstRunActor": {
        "description": "Who changed a step, by actor type and stable user ID",
        "properties": {
          "id": {
            "example": "usr_01",
            "type": "string"
          },
          "type": {
            "example": "utility_staff",
            "type": "string"
          }
        },
        "required": [
          "type",
          "id"
        ],
        "type": "object"
      },
      "FirstRunProgress": {
        "properties": {
          "journey_id": {
            "enum": [
              "platform_setup",
              "utility_test",
              "utility_real",
              "resident_link",
              "resident_connection",
              "staff_field_reader",
              "staff_cashier",
              "staff_finance"
            ],
            "type": "string"
          },
          "run_token": {
            "description": "Opaque funnel run token; absent once the journey is complete",
            "type": "string"
          },
          "steps": {
            "items": {
              "$ref": "#/components/schemas/FirstRunStep"
            },
            "type": "array"
          },
          "subject": {
            "$ref": "#/components/schemas/FirstRunActor"
          },
          "tenant_id": {
            "description": "The utility for utility and staff journeys; null for the platform journey",
            "type": [
              "string",
              "null"
            ]
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "journey_id",
          "subject",
          "tenant_id",
          "updated_at",
          "steps"
        ],
        "type": "object"
      },
      "FirstRunStep": {
        "properties": {
          "allowed_skip_reasons": {
            "items": {
              "enum": [
                "not_needed",
                "later",
                "already_set_up"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "can_skip": {
            "type": "boolean"
          },
          "changed_at": {
            "format": "date-time",
            "type": "string"
          },
          "changed_by": {
            "$ref": "#/components/schemas/FirstRunActor"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "completed_by": {
            "$ref": "#/components/schemas/FirstRunActor"
          },
          "completion_source": {
            "description": "The qualifying domain action that completed the step",
            "example": "service_area.created",
            "type": "string"
          },
          "id": {
            "example": "customer_import",
            "type": "string"
          },
          "reason": {
            "description": "Skip reason code",
            "or the blocking condition code": null,
            "type": "string"
          },
          "responsibility": {
            "description": "Who does the step on a checklist the platform sets up on a utility's behalf",
            "enum": [
              "platform",
              "utility"
            ],
            "type": "string"
          },
          "state": {
            "enum": [
              "todo",
              "done",
              "skipped",
              "blocked"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "state",
          "can_skip",
          "allowed_skip_reasons"
        ],
        "type": "object"
      },
      "FirstRunStepUpdate": {
        "additionalProperties": false,
        "properties": {
          "reason_code": {
            "description": "Required for skipped; one of the step's allowed_skip_reasons",
            "example": "later",
            "type": "string"
          },
          "state": {
            "enum": [
              "skipped",
              "todo"
            ],
            "type": "string"
          }
        },
        "required": [
          "state"
        ],
        "type": "object"
      },
      "IWAWaterBalance": {
        "description": "system_input = billed_authorized + unbilled_authorized + apparent_losses + real_losses. apparent_losses and real_losses are null unless apparent_loss_bp is supplied. Unbilled unmetered consumption is not tracked and sits inside water losses.",
        "properties": {
          "apparent_loss_assumption_bp": {
            "type": "integer"
          },
          "apparent_losses_liters": {
            "type": [
              "integer",
              "null"
            ]
          },
          "authorized_consumption_liters": {
            "type": "integer"
          },
          "billed_authorized_liters": {
            "type": "integer"
          },
          "dma_id": {
            "type": "string"
          },
          "dmas": {
            "items": {
              "$ref": "#/components/schemas/IWAWaterBalance"
            },
            "type": "array"
          },
          "dmas_computed": {
            "type": "integer"
          },
          "dmas_total": {
            "type": "integer"
          },
          "loss_split": {
            "enum": [
              "computed_from_assumption",
              "insufficient_data"
            ],
            "type": "string"
          },
          "non_revenue_water_bp": {
            "type": "integer"
          },
          "non_revenue_water_liters": {
            "type": "integer"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "real_losses_liters": {
            "type": [
              "integer",
              "null"
            ]
          },
          "scope": {
            "enum": [
              "system",
              "dma"
            ],
            "type": "string"
          },
          "status": {
            "enum": [
              "computed",
              "partial_data",
              "insufficient_data"
            ],
            "type": "string"
          },
          "system_input_liters": {
            "type": "integer"
          },
          "unbilled_authorized_liters": {
            "type": "integer"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "water_losses_liters": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "IdentifierRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled. Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "identifier": {
            "description": "E-mail or phone",
            "type": "string"
          }
        },
        "required": [
          "identifier"
        ],
        "type": "object"
      },
      "IngestRequest": {
        "properties": {
          "samples": {
            "items": {
              "properties": {
                "device_id": {
                  "type": "string"
                },
                "external_event_id": {
                  "type": "string"
                },
                "metric": {
                  "type": "string"
                },
                "observed_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "unit": {
                  "type": "string"
                },
                "value": {
                  "type": "number"
                }
              },
              "required": [
                "device_id",
                "value",
                "observed_at"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "samples"
        ],
        "type": "object"
      },
      "IngestResult": {
        "properties": {
          "accepted": {
            "type": "integer"
          },
          "duplicate": {
            "type": "integer"
          },
          "errors": {
            "items": {
              "properties": {
                "index": {
                  "type": "integer"
                },
                "reason": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "late": {
            "type": "integer"
          },
          "rejected": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "InspectionRequestResolution": {
        "properties": {
          "resolution": {
            "maxLength": 500,
            "type": "string"
          },
          "scheduled_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "scheduled",
              "completed",
              "cancelled"
            ],
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "type": "object"
      },
      "Integration": {
        "properties": {
          "category": {
            "enum": [
              "payment",
              "identity",
              "notification",
              "smart_meter",
              "gis",
              "scada",
              "document_store",
              "accounting",
              "erp"
            ],
            "type": "string"
          },
          "configuration_reference": {
            "description": "Opaque secret/configuration reference; never a secret value.",
            "type": "string"
          },
          "health": {
            "enum": [
              "unknown",
              "healthy",
              "degraded",
              "unavailable"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "last_health_check_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "name": {
            "type": "string"
          },
          "provider_key": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "suspended",
              "disabled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "name",
          "category",
          "provider_key",
          "configuration_reference",
          "status",
          "health"
        ],
        "type": "object"
      },
      "IntegrationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Integration"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InvalidParam": {
        "properties": {
          "code": {
            "description": "Stable reason code clients translate",
            "type": "string",
            "when known.": null
          },
          "name": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "name",
          "reason"
        ],
        "type": "object"
      },
      "InventoryAdjustmentRequest": {
        "properties": {
          "lines": {
            "description": "A positive quantity adds stock found; a negative one removes stock missing.",
            "items": {
              "$ref": "#/components/schemas/InventoryMovementLine"
            },
            "type": "array"
          },
          "location_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "location_id",
          "reason",
          "lines"
        ],
        "type": "object"
      },
      "InventoryAlert": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "sal_ identifier",
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "negative_balance",
              "below_reorder",
              "short_for_planned"
            ],
            "type": "string"
          },
          "level": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "location_id": {
            "type": "string"
          },
          "movement_id": {
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "resolved_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "open",
              "resolved"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "kind",
          "item_id",
          "location_id",
          "quantity",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "InventoryAlertPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryAlert"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryAvailability": {
        "properties": {
          "available": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "in_transit": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "item_id": {
            "type": "string"
          },
          "locations": {
            "items": {
              "$ref": "#/components/schemas/InventoryBalance"
            },
            "type": "array"
          },
          "on_hand": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reserved": {
            "$ref": "#/components/schemas/InventoryQuantity"
          }
        },
        "required": [
          "item_id",
          "on_hand",
          "reserved",
          "available",
          "in_transit",
          "locations"
        ],
        "type": "object"
      },
      "InventoryBalance": {
        "properties": {
          "available": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "below_reorder": {
            "description": "Available less planned_short is at or under the reorder level",
            "type": "boolean"
          },
          "in_transit": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "item_code": {
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "item_name": {
            "type": "string"
          },
          "location_id": {
            "type": "string"
          },
          "location_name": {
            "type": "string"
          },
          "on_hand": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "planned_short": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reorder_level": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reserved": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "value_minor": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "tenant_id",
          "item_id",
          "item_code",
          "item_name",
          "unit",
          "location_id",
          "location_name",
          "on_hand",
          "reserved",
          "available",
          "in_transit",
          "below_reorder",
          "value_minor",
          "updated_at"
        ],
        "type": "object"
      },
      "InventoryBalancePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryBalance"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryCountRequest": {
        "properties": {
          "lines": {
            "items": {
              "properties": {
                "counted": {
                  "$ref": "#/components/schemas/InventoryQuantity"
                },
                "item_id": {
                  "type": "string"
                },
                "serials": {
                  "description": "Scanned serials; for a serialised item they are the count.",
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "required": [
                "item_id"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "lines"
        ],
        "type": "object"
      },
      "InventoryCsvImportRequest": {
        "properties": {
          "csv": {
            "description": "The CSV text with a header row",
            "type": "string"
          },
          "dry_run": {
            "type": "boolean"
          },
          "location_id": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          }
        },
        "required": [
          "csv"
        ],
        "type": "object"
      },
      "InventoryImportReport": {
        "properties": {
          "committed": {
            "type": "boolean"
          },
          "created": {
            "type": "integer"
          },
          "dry_run": {
            "type": "boolean"
          },
          "errors": {
            "items": {
              "properties": {
                "code": {
                  "enum": [
                    "item_code_missing",
                    "item_unknown",
                    "item_inactive",
                    "location_unknown",
                    "location_missing",
                    "location_inactive",
                    "quantity_invalid",
                    "unit_cost_invalid",
                    "serials_missing",
                    "serials_count_mismatch",
                    "serial_repeated",
                    "serial_exists",
                    "serials_not_allowed",
                    "quantity_missing",
                    "reference_mismatch",
                    "code_missing",
                    "code_repeated",
                    "reorder_level_invalid",
                    "standard_cost_invalid",
                    "is_meter_invalid",
                    "diameter_invalid",
                    "active_invalid",
                    "name_missing",
                    "unit_invalid",
                    "kind_invalid",
                    "unit_change_not_allowed",
                    "kind_change_not_allowed"
                  ],
                  "type": "string"
                },
                "column": {
                  "type": "string"
                },
                "message": {
                  "deprecated": true,
                  "description": "English compatibility text; use code and parameters for display.",
                  "type": "string"
                },
                "parameters": {
                  "additionalProperties": {
                    "type": "string"
                  },
                  "description": "Stable values for client-localized error text, keyed by parameter name.",
                  "type": "object"
                },
                "row": {
                  "description": "Line number in the file, the header being 1",
                  "type": "integer"
                }
              },
              "required": [
                "row",
                "code"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "meter_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "movements": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovement"
            },
            "type": "array"
          },
          "rows": {
            "type": "integer"
          },
          "updated": {
            "type": "integer"
          },
          "valid": {
            "type": "integer"
          }
        },
        "required": [
          "dry_run",
          "rows",
          "valid",
          "errors",
          "committed"
        ],
        "type": "object"
      },
      "InventoryIssueRequest": {
        "properties": {
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovementLine"
            },
            "type": "array"
          },
          "location_id": {
            "type": "string"
          },
          "occurred_at": {
            "format": "date-time",
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "source_type": {
            "enum": [
              "work_order",
              "connection",
              "other"
            ],
            "type": "string"
          }
        },
        "required": [
          "location_id",
          "reason",
          "lines"
        ],
        "type": "object"
      },
      "InventoryItem": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "average_cost_minor": {
            "description": "Moving weighted average cost per unit, in minor units of the tenant currency",
            "format": "int64",
            "type": "integer"
          },
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "description": "itm_ identifier",
            "type": "string"
          },
          "is_meter": {
            "description": "Units are meters owned by the meter module",
            "type": "boolean"
          },
          "kind": {
            "enum": [
              "bulk",
              "serialised"
            ],
            "type": "string"
          },
          "meter_diameter_mm": {
            "type": "integer"
          },
          "meter_manufacturer": {
            "type": "string"
          },
          "meter_model": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "reorder_level": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reorder_levels": {
            "items": {
              "$ref": "#/components/schemas/InventoryReorderLevel"
            },
            "type": "array"
          },
          "standard_cost_minor": {
            "format": "int64",
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "enum": [
              "un",
              "m",
              "kg",
              "l",
              "cx",
              "rolo"
            ],
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "code",
          "name",
          "unit",
          "kind",
          "is_meter",
          "reorder_level",
          "reorder_levels",
          "standard_cost_minor",
          "average_cost_minor",
          "active",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "InventoryItemPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryItem"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryKit": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "description": "kit_ identifier",
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryKitLine"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "work_order_type": {
            "description": "The work-order type this kit is the default for",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "code",
          "name",
          "active",
          "lines",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "InventoryKitLine": {
        "properties": {
          "item_id": {
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "required": {
            "description": "A field order cannot be dispatched until this line is reserved (batch 2)",
            "type": "boolean"
          }
        },
        "required": [
          "item_id",
          "quantity",
          "required"
        ],
        "type": "object"
      },
      "InventoryKitPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryKit"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryLocation": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "allow_negative": {
            "type": "boolean"
          },
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "crew_id": {
            "type": "string"
          },
          "id": {
            "description": "loc_ identifier",
            "type": "string"
          },
          "is_default": {
            "type": "boolean"
          },
          "kind": {
            "enum": [
              "warehouse",
              "area",
              "van"
            ],
            "type": "string"
          },
          "member_user_ids": {
            "description": "People who may move stock at this van with inventory:van:write.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "parent_id": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "code",
          "name",
          "kind",
          "member_user_ids",
          "allow_negative",
          "is_default",
          "active",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "InventoryLocationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryLocation"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryMovement": {
        "properties": {
          "actor_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "from_location_id": {
            "type": "string"
          },
          "id": {
            "description": "mvt_ identifier",
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "receipt",
              "issue",
              "return",
              "transfer_out",
              "transfer_in",
              "adjustment",
              "scrap"
            ],
            "type": "string"
          },
          "material_line_id": {
            "description": "wml_ work-order material line",
            "type": "string"
          },
          "occurred_at": {
            "format": "date-time",
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reason": {
            "type": "string"
          },
          "reason_code": {
            "description": "Stable code of a reason the server wrote (inventory.meter_installed, inventory.work_order_issue, inventory.stock_transfer, inventory.stocktake_difference, ...); clients word it and fall back to reason. Absent for reasons people typed.",
            "type": "string"
          },
          "reason_params": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values the reason code fills in: stocktake and note for inventory.stocktake_difference.",
            "type": "object"
          },
          "reference": {
            "type": "string"
          },
          "serial_id": {
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "source_type": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "to_location_id": {
            "type": "string"
          },
          "total_cost_minor": {
            "format": "int64",
            "type": "integer"
          },
          "unit_cost_minor": {
            "format": "int64",
            "type": "integer"
          },
          "value_change_minor": {
            "description": "Exact change to the stock value the ledger posts to stock on hand; zero for a transfer.",
            "format": "int64",
            "type": "integer"
          },
          "work_order_id": {
            "description": "Work order whose material line the movement served",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "kind",
          "item_id",
          "quantity",
          "unit_cost_minor",
          "total_cost_minor",
          "actor_id",
          "occurred_at",
          "created_at"
        ],
        "type": "object"
      },
      "InventoryMovementLine": {
        "properties": {
          "item_id": {
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "serials": {
            "description": "Serial numbers of a serialised item; their count is the quantity.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "unit_cost_minor": {
            "description": "Receipts only: cost per unit",
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "item_id"
        ],
        "type": "object"
      },
      "InventoryMovementPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovement"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryMovementResult": {
        "properties": {
          "alerts": {
            "items": {
              "$ref": "#/components/schemas/InventoryAlert"
            },
            "type": "array"
          },
          "meter_ids": {
            "description": "Meters a receipt registered, in line order.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "movements": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovement"
            },
            "type": "array"
          },
          "stocktake": {
            "$ref": "#/components/schemas/InventoryStocktake"
          },
          "transfer": {
            "$ref": "#/components/schemas/InventoryTransfer"
          }
        },
        "required": [
          "movements"
        ],
        "type": "object"
      },
      "InventoryQuantity": {
        "description": "Quantity in the item's unit, with at most three decimals (12.5 metres).",
        "multipleOf": 0.001,
        "type": "number"
      },
      "InventoryReceiptRequest": {
        "properties": {
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovementLine"
            },
            "type": "array"
          },
          "location_id": {
            "type": "string"
          },
          "meter_precision": {
            "type": "integer"
          },
          "meter_unit": {
            "description": "Dial unit of received meters (default m3)",
            "type": "string"
          },
          "occurred_at": {
            "format": "date-time",
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "reference": {
            "description": "Delivery note",
            "type": "string"
          }
        },
        "required": [
          "location_id",
          "lines"
        ],
        "type": "object"
      },
      "InventoryReorderLevel": {
        "properties": {
          "level": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "location_id": {
            "type": "string"
          }
        },
        "required": [
          "location_id",
          "level"
        ],
        "type": "object"
      },
      "InventoryReservation": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "rsv_ identifier",
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "location_id": {
            "type": "string"
          },
          "material_line_id": {
            "description": "wml_ work-order material line",
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "release_reason": {
            "type": "string"
          },
          "released_at": {
            "format": "date-time",
            "type": "string"
          },
          "serial_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "held",
              "issued",
              "released"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "work_order_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "item_id",
          "location_id",
          "quantity",
          "status",
          "created_by",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "InventoryReservationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryReservation"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryReturnRequest": {
        "allOf": [
          {
            "$ref": "#/components/schemas/InventoryIssueRequest"
          }
        ]
      },
      "InventoryScrapRequest": {
        "properties": {
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovementLine"
            },
            "type": "array"
          },
          "location_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "location_id",
          "reason",
          "lines"
        ],
        "type": "object"
      },
      "InventorySerial": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "ser_ identifier",
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "location_id": {
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "source_type": {
            "type": "string"
          },
          "status": {
            "enum": [
              "in_stock",
              "in_transit",
              "issued",
              "installed",
              "in_testing",
              "scrapped",
              "lost"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit_cost_minor": {
            "format": "int64",
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "item_id",
          "serial_number",
          "status",
          "unit_cost_minor",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "InventorySerialHistory": {
        "properties": {
          "item": {
            "$ref": "#/components/schemas/InventoryItem"
          },
          "movements": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovement"
            },
            "type": "array"
          },
          "serial": {
            "$ref": "#/components/schemas/InventorySerial"
          }
        },
        "required": [
          "serial",
          "item",
          "movements"
        ],
        "type": "object"
      },
      "InventorySettings": {
        "properties": {
          "redispatch_hold_days": {
            "description": "Days a failed_access_denied order keeps its reservations before they are released",
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "updated_by": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "redispatch_hold_days"
        ],
        "type": "object"
      },
      "InventoryStocktake": {
        "properties": {
          "approval_reason": {
            "type": "string"
          },
          "approved_at": {
            "format": "date-time",
            "type": "string"
          },
          "approved_by": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "difference_value_minor": {
            "format": "int64",
            "type": "integer"
          },
          "frozen_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "stk_ identifier",
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryStocktakeLine"
            },
            "type": "array"
          },
          "location_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "status": {
            "enum": [
              "counting",
              "approved"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "location_id",
          "status",
          "created_by",
          "frozen_at",
          "lines",
          "difference_value_minor",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "InventoryStocktakeLine": {
        "properties": {
          "counted": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "counted_at": {
            "format": "date-time",
            "type": "string"
          },
          "counted_by": {
            "type": "string"
          },
          "counted_serials": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "difference": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "difference_value_minor": {
            "format": "int64",
            "type": "integer"
          },
          "expected": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "expected_serials": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "item_id": {
            "type": "string"
          },
          "unit_cost_minor": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "item_id",
          "expected",
          "unit_cost_minor",
          "difference_value_minor"
        ],
        "type": "object"
      },
      "InventoryStocktakePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryStocktake"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryTransfer": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "from_location_id": {
            "type": "string"
          },
          "id": {
            "description": "xfr_ identifier",
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryTransferLine"
            },
            "type": "array"
          },
          "reason": {
            "type": "string"
          },
          "received_at": {
            "format": "date-time",
            "type": "string"
          },
          "received_by": {
            "type": "string"
          },
          "status": {
            "enum": [
              "in_transit",
              "received"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "to_location_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "from_location_id",
          "to_location_id",
          "status",
          "lines",
          "created_by",
          "created_at"
        ],
        "type": "object"
      },
      "InventoryTransferLine": {
        "properties": {
          "item_id": {
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "serials": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "item_id",
          "quantity"
        ],
        "type": "object"
      },
      "InventoryTransferPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/InventoryTransfer"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "InventoryTransferRequest": {
        "properties": {
          "from_location_id": {
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/InventoryMovementLine"
            },
            "type": "array"
          },
          "reason": {
            "type": "string"
          },
          "to_location_id": {
            "type": "string"
          }
        },
        "required": [
          "from_location_id",
          "to_location_id",
          "lines"
        ],
        "type": "object"
      },
      "InvitationInput": {
        "description": "Exactly one of phone or email.",
        "properties": {
          "account_id": {
            "description": "Required in bulk requests",
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "expires_in_hours": {
            "description": "Default 168, maximum 720",
            "type": "integer"
          },
          "permissions": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "phone": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "IsolationResult": {
        "properties": {
          "affected_customer_taps": {
            "type": "integer"
          },
          "already_closed": {
            "type": "boolean"
          },
          "closed_valves": {
            "items": {
              "$ref": "#/components/schemas/TopologyLink"
            },
            "type": "array"
          },
          "isolated_nodes": {
            "items": {
              "$ref": "#/components/schemas/TopologyNode"
            },
            "type": "array"
          },
          "link_id": {
            "type": "string"
          },
          "still_supplied_nodes": {
            "items": {
              "$ref": "#/components/schemas/TopologyNode"
            },
            "type": "array"
          },
          "unisolable": {
            "description": "A pipe has an upstream path to a source with no valve",
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "IssueNoticeRequest": {
        "properties": {
          "cutoff_days": {
            "default": 14,
            "minimum": 1,
            "type": "integer"
          },
          "delivered_via": {
            "enum": [
              "email",
              "physical"
            ],
            "type": "string"
          },
          "final_warning": {
            "default": false,
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "IssueQuoteInput": {
        "properties": {
          "lines": {
            "items": {
              "properties": {
                "adjustment_reason": {
                  "maxLength": 255,
                  "type": "string"
                },
                "charge_code": {
                  "description": "A price key from quote-prices; omit for a free line",
                  "type": "string"
                },
                "description": {
                  "maxLength": 255,
                  "type": "string"
                },
                "quantity": {
                  "description": "Defaults to 1",
                  "type": "number"
                },
                "taxable": {
                  "description": "Free lines only; defaults to true",
                  "type": "boolean"
                },
                "unit_price_cents": {
                  "description": "Overrides the tariff price (with a reason) or prices a free line",
                  "format": "int64",
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "maxItems": 50,
            "minItems": 1,
            "type": "array"
          },
          "notes": {
            "maxLength": 2000,
            "type": "string"
          },
          "site_visit_id": {
            "description": "The visit this quote follows",
            "type": "string"
          },
          "valid_until": {
            "description": "Defaults to 30 days from today",
            "format": "date",
            "type": "string"
          }
        },
        "required": [
          "lines"
        ],
        "type": "object"
      },
      "JobPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/JobView"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "JobSummary": {
        "properties": {
          "counts": {
            "additionalProperties": {
              "type": "integer"
            },
            "type": "object"
          },
          "enabled": {
            "description": "False when this installation runs without the job queue",
            "type": "boolean"
          }
        },
        "required": [
          "enabled",
          "counts"
        ],
        "type": "object"
      },
      "JobView": {
        "properties": {
          "attempts": {
            "type": "integer"
          },
          "available_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "finished_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "type": "string"
          },
          "last_error": {
            "type": "string"
          },
          "locked_by": {
            "type": "string"
          },
          "max_attempts": {
            "type": "integer"
          },
          "request_id": {
            "type": "string"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "queued",
              "running",
              "succeeded"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "kind",
          "status",
          "attempts",
          "max_attempts",
          "available_at",
          "created_at"
        ],
        "type": "object"
      },
      "LDAPLoginRequest": {
        "additionalProperties": false,
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when the adaptive login challenge is required. Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "password": {
            "description": "Directory password.",
            "type": "string"
          },
          "tenant_id": {
            "description": "Workspace whose directory connection authenticates the person.",
            "type": "string"
          },
          "username": {
            "description": "Directory username, e-mail address or user principal name.",
            "example": "jdoe",
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "username",
          "password"
        ],
        "type": "object"
      },
      "LeakAllowanceApplication": {
        "additionalProperties": true,
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "invoice_number": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "LeakAllowanceApplicationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/LeakAllowanceApplication"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "LeakAllowanceAssessment": {
        "properties": {
          "consumption_m3": {
            "type": "number"
          },
          "currency": {
            "type": "string"
          },
          "eligible": {
            "type": "boolean"
          },
          "excess_m3": {
            "type": "number"
          },
          "excess_value_cents": {
            "format": "int64",
            "type": "integer"
          },
          "historic_avg_m3": {
            "type": "number"
          },
          "invoice_id": {
            "type": "string"
          },
          "proposed_credit_cents": {
            "format": "int64",
            "type": "integer"
          },
          "reason_code": {
            "description": "Stable refusal code for an ineligible invoice; clients translate the value.",
            "enum": [
              "policy_disabled",
              "invoice_not_open",
              "repair_window_expired",
              "cooldown_active",
              "insufficient_history",
              "below_excess_threshold",
              "no_credit_value"
            ],
            "type": "string"
          },
          "require_proof": {
            "type": "boolean"
          }
        },
        "required": [
          "invoice_id",
          "eligible",
          "consumption_m3",
          "require_proof"
        ],
        "type": "object"
      },
      "LedgerAccount": {
        "properties": {
          "account_name": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "account_type": {
            "enum": [
              "asset",
              "liability",
              "equity",
              "revenue",
              "expense"
            ],
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "is_reconciled": {
            "type": "boolean"
          },
          "role": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "id",
          "account_number",
          "account_name",
          "account_type",
          "currency",
          "is_reconciled",
          "active",
          "created_at"
        ],
        "type": "object"
      },
      "LedgerAccountInput": {
        "properties": {
          "account_name": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "account_type": {
            "enum": [
              "asset",
              "liability",
              "equity",
              "revenue",
              "expense"
            ],
            "type": "string"
          },
          "role": {
            "type": "string"
          }
        },
        "required": [
          "account_number",
          "account_name",
          "account_type"
        ],
        "type": "object"
      },
      "LedgerAccountPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/LedgerAccount"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "LedgerEntry": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "entry_date": {
            "format": "date-time",
            "type": "string"
          },
          "entry_number": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "lines": {
            "items": {
              "properties": {
                "amount_minor": {
                  "format": "int64",
                  "type": "integer"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "currency": {
                  "type": "string"
                },
                "entry_id": {
                  "type": "string"
                },
                "entry_side": {
                  "enum": [
                    "debit",
                    "credit"
                  ],
                  "type": "string"
                },
                "gl_account_id": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "sub_ledger_party_id": {
                  "type": "string"
                },
                "tenant_id": {
                  "type": "string"
                }
              },
              "required": [
                "tenant_id",
                "id",
                "entry_id",
                "gl_account_id",
                "entry_side",
                "amount_minor",
                "currency",
                "created_at"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "posted_by_user_id": {
            "type": "string"
          },
          "reverses_entry_id": {
            "type": "string"
          },
          "source_module": {
            "type": "string"
          },
          "source_reference_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "id",
          "entry_number",
          "entry_date",
          "source_module",
          "source_reference_id",
          "description",
          "posted_by_user_id",
          "created_at"
        ],
        "type": "object"
      },
      "LedgerEntryPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/LedgerEntry"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "LedgerReconciliation": {
        "properties": {
          "balanced": {
            "type": "boolean"
          },
          "currency": {
            "type": "string"
          },
          "receivable_control_minor": {
            "format": "int64",
            "type": "integer"
          },
          "receivable_difference_minor": {
            "format": "int64",
            "type": "integer"
          },
          "receivable_sub_ledger_minor": {
            "format": "int64",
            "type": "integer"
          },
          "stock_control_minor": {
            "description": "Stock on hand account (RFC 0071 phase 4).",
            "format": "int64",
            "type": "integer"
          },
          "stock_difference_minor": {
            "format": "int64",
            "type": "integer"
          },
          "stock_sub_ledger_minor": {
            "description": "Inventory balances, on hand and in transit, at moving average cost.",
            "format": "int64",
            "type": "integer"
          },
          "unallocated_control_minor": {
            "format": "int64",
            "type": "integer"
          },
          "unallocated_difference_minor": {
            "format": "int64",
            "type": "integer"
          },
          "unallocated_sub_ledger_minor": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "LedgerTrialBalance": {
        "properties": {
          "balanced": {
            "type": "boolean"
          },
          "currency": {
            "type": "string"
          },
          "lines": {
            "items": {
              "properties": {
                "account_id": {
                  "type": "string"
                },
                "account_name": {
                  "type": "string"
                },
                "account_number": {
                  "type": "string"
                },
                "account_type": {
                  "type": "string"
                },
                "balance_minor": {
                  "format": "int64",
                  "type": "integer"
                },
                "credit_minor": {
                  "format": "int64",
                  "type": "integer"
                },
                "currency": {
                  "type": "string"
                },
                "debit_minor": {
                  "format": "int64",
                  "type": "integer"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "total_credit_minor": {
            "format": "int64",
            "type": "integer"
          },
          "total_debit_minor": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "LinkStatus": {
        "enum": [
          "open",
          "closed",
          "throttled"
        ],
        "type": "string"
      },
      "LinkType": {
        "enum": [
          "gravity_main",
          "pumping_main",
          "distribution_pipe",
          "control_valve"
        ],
        "type": "string"
      },
      "LinkedConsumerAccount": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "tenant_slug": {
            "description": "The utility's slug, so a client can brand the account",
            "type": "string"
          }
        },
        "type": "object"
      },
      "LocalizedText": {
        "additionalProperties": {
          "maxLength": 255,
          "type": "string"
        },
        "description": "One text per language, keyed by language tag (pt, en, pt-MZ).",
        "example": {
          "en": "Up to 100 customers",
          "pt": "Até 100 clientes"
        },
        "type": "object"
      },
      "LoginRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when adaptive login challenge is required. Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "context_id": {
            "description": "Optional membership to activate",
            "type": "string"
          },
          "identifier": {
            "description": "E-mail or phone",
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "password"
        ],
        "type": "object"
      },
      "MFAChallenge": {
        "properties": {
          "challenge_token": {
            "type": "string"
          },
          "expires_in": {
            "type": "integer"
          },
          "methods": {
            "items": {
              "enum": [
                "totp",
                "recovery_code"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "mfa_required": {
            "type": "boolean"
          }
        },
        "required": [
          "mfa_required",
          "challenge_token",
          "expires_in",
          "methods"
        ],
        "type": "object"
      },
      "MassBalanceEntry": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "inflow_volume_liters": {
            "format": "int64",
            "type": "integer"
          },
          "mass_conserved": {
            "type": "boolean"
          },
          "node_id": {
            "type": "string"
          },
          "outflow_volume_liters": {
            "format": "int64",
            "type": "integer"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "revision": {
            "type": "integer"
          },
          "storage_delta_liters": {
            "format": "int64",
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "tolerance_basis_points": {
            "format": "int64",
            "type": "integer"
          },
          "unaccounted_loss_liters": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "MasterMeterBalance": {
        "properties": {
          "loss_percent": {
            "type": "number"
          },
          "master_consumption_m3": {
            "type": "number"
          },
          "master_meter_id": {
            "type": "string"
          },
          "negative_balance": {
            "type": "boolean"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "submeter_count": {
            "type": "integer"
          },
          "submeters": {
            "items": {
              "$ref": "#/components/schemas/SubmeterBalanceEntry"
            },
            "type": "array"
          },
          "submeters_consumption_m3": {
            "type": "number"
          },
          "unaccounted_loss_m3": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "Measurement": {
        "properties": {
          "device_id": {
            "type": "string"
          },
          "external_event_id": {
            "type": "string"
          },
          "metric": {
            "type": "string"
          },
          "observed_at": {
            "format": "date-time",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "type": "number"
          }
        },
        "required": [
          "tenant_id",
          "device_id",
          "observed_at",
          "metric",
          "value",
          "unit"
        ],
        "type": "object"
      },
      "MetadataEntry": {
        "properties": {
          "metadata": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "MetadataEntryPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/MetadataEntry"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "MetadataPut": {
        "properties": {
          "metadata": {
            "additionalProperties": {
              "maxLength": 500,
              "type": "string"
            },
            "maxProperties": 50,
            "type": "object"
          }
        },
        "required": [
          "metadata"
        ],
        "type": "object"
      },
      "Meter": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "device_status": {
            "enum": [
              "in_warehouse",
              "installed",
              "in_testing",
              "scrapped"
            ],
            "type": "string"
          },
          "dial_decimals": {
            "type": "integer"
          },
          "dial_digits": {
            "type": "integer"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "installed_at": {
            "format": "date-time",
            "type": "string"
          },
          "last_reset_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "last_reset_value": {
            "type": "string"
          },
          "manufacturer": {
            "type": "string"
          },
          "master_billing_mode": {
            "enum": [
              "gross",
              "net_of_submeters",
              "monitor_only"
            ],
            "type": "string"
          },
          "maximum_reading": {
            "type": "string"
          },
          "meter_role": {
            "enum": [
              "standard",
              "master",
              "submeter"
            ],
            "type": "string"
          },
          "meter_type": {
            "enum": [
              "mechanical",
              "ultrasonic",
              "electromagnetic",
              "smart",
              "prepaid"
            ],
            "type": "string"
          },
          "model": {
            "type": "string"
          },
          "parent_meter_id": {
            "type": "string"
          },
          "precision": {
            "maximum": 9,
            "minimum": 0,
            "type": "integer"
          },
          "pulse_multiplier": {
            "type": "string"
          },
          "removed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "rollover_value": {
            "description": "Optional meter modulus used to calculate a reviewed rollover consumption.",
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "inactive",
              "retired"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "unit_of_measure": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "serial_number",
          "unit",
          "precision",
          "status",
          "device_status",
          "installed_at",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "MeterCommand": {
        "properties": {
          "attempt_count": {
            "type": "integer"
          },
          "collector_id": {
            "type": "string"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "failure_reason": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "lease_expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "max_attempts": {
            "type": "integer"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "not_before": {
            "format": "date-time",
            "type": "string"
          },
          "reading_id": {
            "type": "string"
          },
          "requested_by": {
            "type": "string"
          },
          "status": {
            "enum": [
              "queued",
              "leased",
              "succeeded",
              "failed",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "type": {
            "enum": [
              "read",
              "inspect",
              "synchronize",
              "reset-alarm",
              "disconnect",
              "reconnect"
            ],
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "collector_id",
          "type",
          "status",
          "requested_by",
          "idempotency_key",
          "attempt_count",
          "max_attempts",
          "not_before",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "MeterCommandCapability": {
        "properties": {
          "collector_id": {
            "type": "string"
          },
          "has_collector": {
            "type": "boolean"
          }
        },
        "required": [
          "has_collector"
        ],
        "type": "object"
      },
      "MeterCommandPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/MeterCommand"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "MeterDeviceStatusRequest": {
        "properties": {
          "location_id": {
            "description": "Destination warehouse or van of a meter returned in_warehouse (the default warehouse when empty)",
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "status": {
            "enum": [
              "in_warehouse",
              "in_testing",
              "scrapped"
            ],
            "type": "string"
          }
        },
        "required": [
          "status",
          "reason"
        ],
        "type": "object"
      },
      "MeterExchangeInput": {
        "properties": {
          "connection_id": {
            "type": "string"
          },
          "exchange_reason": {
            "type": "string"
          },
          "exchanged_at": {
            "format": "date-time",
            "type": "string"
          },
          "final_reading": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "new_meter_id": {
            "type": "string"
          },
          "new_meter_location_id": {
            "description": "Store or van the new meter is taken from.",
            "type": "string"
          },
          "old_meter_id": {
            "type": "string"
          },
          "old_meter_status": {
            "enum": [
              "in_testing",
              "in_warehouse",
              "scrapped"
            ],
            "type": "string"
          },
          "return_location_id": {
            "description": "Where an old meter returned in_warehouse goes; the default warehouse when empty.",
            "type": "string"
          },
          "security_seal_number": {
            "type": "string"
          },
          "start_reading": {
            "type": "string"
          }
        },
        "required": [
          "connection_id",
          "old_meter_id",
          "new_meter_id",
          "final_reading",
          "start_reading",
          "exchange_reason",
          "idempotency_key"
        ],
        "type": "object"
      },
      "MeterExchangeResult": {
        "properties": {
          "closed_installation": {
            "$ref": "#/components/schemas/MeterInstallation"
          },
          "final_reading": {
            "$ref": "#/components/schemas/Reading"
          },
          "new_installation": {
            "$ref": "#/components/schemas/MeterInstallation"
          },
          "new_meter": {
            "$ref": "#/components/schemas/Meter"
          },
          "old_meter": {
            "$ref": "#/components/schemas/Meter"
          },
          "start_reading": {
            "$ref": "#/components/schemas/Reading"
          }
        },
        "type": "object"
      },
      "MeterInspectionRequest": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "identity_id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "consumer",
              "field_reread"
            ],
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "reading_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "requester_name": {
            "description": "Who filed it, which can differ from the account holder.",
            "type": "string"
          },
          "resolution": {
            "type": "string"
          },
          "resolved_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "resolved_by": {
            "type": "string"
          },
          "scheduled_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "enum": [
              "open",
              "scheduled",
              "completed",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "account_id",
          "meter_id",
          "identity_id",
          "reason",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "MeterInspectionRequestPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/MeterInspectionRequest"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "MeterInstallInput": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "initial_reading": {
            "type": "string"
          },
          "installed_at": {
            "format": "date-time",
            "type": "string"
          },
          "location_id": {
            "description": "Store or van the meter is taken from; inventory refuses the installation when its serial is elsewhere.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "security_seal_number": {
            "type": "string"
          }
        },
        "required": [
          "connection_id",
          "meter_id",
          "initial_reading",
          "idempotency_key"
        ],
        "type": "object"
      },
      "MeterInstallation": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "connection_holder_name": {
            "description": "Display name of the customer who holds the referenced connection. Omitted when unknown.",
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "exchange_reason": {
            "type": "string"
          },
          "final_reading": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "initial_reading": {
            "type": "string"
          },
          "installed_at": {
            "format": "date-time",
            "type": "string"
          },
          "installed_by": {
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "removed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "replaced_installation_id": {
            "type": "string"
          },
          "security_seal_number": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "connection_id",
          "meter_id",
          "installed_at",
          "initial_reading",
          "installed_by",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "MeterInstallationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/MeterInstallation"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "MeterPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Meter"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "MeterReset": {
        "properties": {
          "authorized_by": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "prior_reading_value": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "reset_at": {
            "format": "date-time",
            "type": "string"
          },
          "reset_reading_value": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "reset_at",
          "prior_reading_value",
          "reset_reading_value",
          "reason",
          "authorized_by",
          "idempotency_key",
          "created_at"
        ],
        "type": "object"
      },
      "MeterResetPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/MeterReset"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "MobileMoneyAction": {
        "properties": {
          "instructions": {
            "type": "string"
          },
          "type": {
            "const": "mobile_money_approval"
          }
        },
        "required": [
          "type",
          "instructions"
        ],
        "type": "object"
      },
      "NetworkAsset": {
        "properties": {
          "asset_type": {
            "$ref": "#/components/schemas/AssetType"
          },
          "capacity": {
            "type": "number"
          },
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "device_id": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "elevation": {
            "type": "number"
          },
          "id": {
            "pattern": "^ast_",
            "type": "string"
          },
          "installation_date": {
            "format": "date-time",
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "node_type": {
            "$ref": "#/components/schemas/NodeType"
          },
          "properties": {
            "additionalProperties": true,
            "type": "object"
          },
          "service_area_id": {
            "type": "string"
          },
          "status": {
            "$ref": "#/components/schemas/AssetStatus"
          },
          "storage_capacity_m3": {
            "format": "int64",
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "code",
          "name",
          "asset_type",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "NetworkAssetPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/NetworkAsset"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "NextStep": {
        "properties": {
          "action": {
            "$ref": "#/components/schemas/NextStepAction"
          },
          "blocked_reason": {
            "properties": {
              "code": {
                "example": "review_pending",
                "type": "string"
              },
              "message": {
                "type": "string"
              }
            },
            "type": [
              "object",
              "null"
            ]
          },
          "help": {
            "properties": {
              "article_id": {
                "description": "Help registry category/slug",
                "example": "getting-started/import-customers",
                "type": "string"
              }
            },
            "required": [
              "article_id"
            ],
            "type": "object"
          },
          "id": {
            "example": "customer_import",
            "type": "string"
          },
          "journey_id": {
            "example": "utility_real",
            "type": "string"
          },
          "line": {
            "type": "string"
          },
          "owner": {
            "enum": [
              "you",
              "platform_review",
              "team_member",
              "utility_owner"
            ],
            "type": "string"
          },
          "state": {
            "enum": [
              "todo",
              "blocked"
            ],
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "wait_line": {
            "description": "Optional, localized like line. On the utility's review step (documents) until approval: how long the platform's review usually takes. Present only when the server has a figure: the median of past decided reviews once there are at least 3, else the configured onboarding.review_wait (default 0, meaning absent).",
            "example": "A revisão costuma demorar cerca de 2 dias.",
            "type": "string"
          }
        },
        "required": [
          "id",
          "journey_id",
          "title",
          "line",
          "state",
          "owner",
          "help",
          "blocked_reason"
        ],
        "type": "object"
      },
      "NextStepAction": {
        "properties": {
          "id": {
            "description": "Portable destination intent each client maps to its own screen",
            "example": "utility.real.customer_import",
            "type": "string"
          },
          "label": {
            "description": "Localized action label",
            "type": "string"
          },
          "route": {
            "description": "In-app route on the platform dashboard (platform setup only)",
            "example": "/platform/settings/branding",
            "type": "string"
          }
        },
        "required": [
          "id"
        ],
        "type": "object"
      },
      "NextStepChoice": {
        "properties": {
          "help": {
            "properties": {
              "article_id": {
                "example": "residents/link-resident-account",
                "type": "string"
              }
            },
            "required": [
              "article_id"
            ],
            "type": "object"
          },
          "id": {
            "example": "resident.link-existing-account",
            "type": "string"
          },
          "line": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "line",
          "help"
        ],
        "type": "object"
      },
      "NextSteps": {
        "properties": {
          "actions": {
            "description": "Public utility lookup and request-status actions (public entry only)",
            "items": {
              "$ref": "#/components/schemas/NextStepChoice"
            },
            "type": "array"
          },
          "audience": {
            "enum": [
              "platform",
              "business",
              "consumer",
              "resident"
            ],
            "type": "string"
          },
          "doors": {
            "description": "The two resident entry doors (public entry only)",
            "items": {
              "$ref": "#/components/schemas/NextStepChoice"
            },
            "type": "array"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "locale": {
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "run_token": {
            "description": "Opaque run token for a staff journey or the anonymous resident entry",
            "type": "string"
          },
          "steps": {
            "items": {
              "$ref": "#/components/schemas/NextStep"
            },
            "maxItems": 3,
            "type": "array"
          }
        },
        "required": [
          "audience",
          "locale",
          "generated_at",
          "steps"
        ],
        "type": "object"
      },
      "NightFlowReport": {
        "properties": {
          "device_id": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "nights": {
            "items": {
              "properties": {
                "baseline_lps": {
                  "type": "number"
                },
                "burst_suspected": {
                  "type": "boolean"
                },
                "date": {
                  "format": "date",
                  "type": "string"
                },
                "excess_percent": {
                  "type": "number"
                },
                "mean_flow_lps": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "sample_count": {
                  "type": "integer"
                },
                "status": {
                  "enum": [
                    "ok",
                    "burst_suspected",
                    "insufficient_data"
                  ],
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "threshold_percent": {
            "type": "number"
          },
          "timezone": {
            "type": "string"
          },
          "warnings": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "NoAction": {
        "properties": {
          "type": {
            "const": "none"
          }
        },
        "required": [
          "type"
        ],
        "type": "object"
      },
      "NodeType": {
        "enum": [
          "source_river",
          "source_borehole",
          "treatment_plant",
          "reservoir",
          "dma_inlet",
          "junction",
          "customer_tap"
        ],
        "type": "string"
      },
      "NotificationDelivery": {
        "properties": {
          "attempt": {
            "type": "integer"
          },
          "attempts": {
            "items": {
              "properties": {
                "channel": {
                  "enum": [
                    "email",
                    "push",
                    "in_app"
                  ],
                  "type": "string"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "failure_code": {
                  "type": "string"
                },
                "failure_reason": {
                  "type": "string"
                },
                "idempotency_key": {
                  "type": "string"
                },
                "number": {
                  "type": "integer"
                },
                "provider_receipt_reference": {
                  "type": "string"
                },
                "status": {
                  "enum": [
                    "pending",
                    "leased",
                    "accepted",
                    "sent",
                    "delivered",
                    "failed"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "number",
                "channel",
                "status",
                "idempotency_key",
                "created_at"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "available_at": {
            "format": "date-time",
            "type": "string"
          },
          "channel": {
            "enum": [
              "email",
              "push",
              "in_app"
            ],
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "failure_code": {
            "type": "string"
          },
          "failure_reason": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "intent_id": {
            "type": "string"
          },
          "provider_receipt_reference": {
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "leased",
              "accepted",
              "sent",
              "delivered",
              "failed"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "intent_id",
          "status",
          "attempt",
          "idempotency_key",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "NotificationDeliveryPlan": {
        "description": "Durable outbound channel order and rendered message content. Recipients must contain a non-empty destination for every listed channel.",
        "properties": {
          "channels": {
            "items": {
              "enum": [
                "email",
                "push"
              ],
              "type": "string"
            },
            "maxItems": 4,
            "minItems": 1,
            "type": "array",
            "uniqueItems": true
          },
          "html": {
            "maxLength": 16000,
            "type": "string"
          },
          "recipients": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "subject": {
            "maxLength": 200,
            "type": "string"
          },
          "text": {
            "maxLength": 4000,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "channels",
          "recipients",
          "text"
        ],
        "type": "object"
      },
      "NotificationInboxItem": {
        "properties": {
          "archived_at": {
            "format": "date-time",
            "type": "string"
          },
          "body": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "event_type": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "intent_id": {
            "type": "string"
          },
          "read_at": {
            "format": "date-time",
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "template_key": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "intent_id",
          "event_type",
          "title",
          "body",
          "created_at"
        ],
        "type": "object"
      },
      "NotificationIntent": {
        "properties": {
          "category": {
            "description": "Notification category used for recipient policy.",
            "type": "string"
          },
          "data": {
            "additionalProperties": true,
            "type": "object"
          },
          "delivery": {
            "$ref": "#/components/schemas/NotificationDelivery"
          },
          "delivery_plan": {
            "$ref": "#/components/schemas/NotificationDeliveryPlan"
          },
          "event_type": {
            "examples": [
              "invoice.issued"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "inbox_body": {
            "description": "Optional in-app message body; requires inbox_title and a consumer or staff recipient.",
            "maxLength": 2000,
            "type": "string"
          },
          "inbox_title": {
            "description": "Optional in-app message title; requires inbox_body and a consumer or staff recipient.",
            "maxLength": 160,
            "type": "string"
          },
          "locale": {
            "description": "Recipient locale captured when the intent was created; defaults to pt-MZ.",
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "priority": {
            "enum": [
              "critical",
              "high",
              "normal",
              "low"
            ],
            "type": "string"
          },
          "recipient_id": {
            "type": "string"
          },
          "recipient_type": {
            "type": "string"
          },
          "resource_id": {
            "type": "string"
          },
          "resource_type": {
            "type": "string"
          },
          "scheduled_at": {
            "description": "Next allowed delivery time after recipient quiet hours; urgent categories are not delayed.",
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "accepted",
              "sent",
              "delivered",
              "failed"
            ],
            "type": "string"
          },
          "template_key": {
            "description": "Optional approved template identifier; not channel-specific content.",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "event_type",
          "recipient_type",
          "recipient_id",
          "resource_type",
          "resource_id",
          "locale",
          "status"
        ],
        "type": "object"
      },
      "NotificationIntentPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/NotificationIntent"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "NotificationPreference": {
        "properties": {
          "channels": {
            "additionalProperties": {
              "type": "boolean"
            },
            "type": "object"
          },
          "consent_status": {
            "enum": [
              "granted",
              "withdrawn",
              "required_notice_only"
            ],
            "type": "string"
          },
          "events": {
            "additionalProperties": {
              "type": "boolean"
            },
            "type": "object"
          },
          "id": {
            "type": "string"
          },
          "preferred_locale": {
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "quiet_hours_end": {
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "type": "string"
          },
          "quiet_hours_start": {
            "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
            "type": "string"
          },
          "recipient_id": {
            "type": "string"
          },
          "recipient_type": {
            "maxLength": 32,
            "type": "string"
          },
          "timezone": {
            "description": "IANA time zone for the recipient's quiet hours",
            "type": "string"
          }
        },
        "required": [
          "id",
          "recipient_type",
          "recipient_id",
          "consent_status"
        ],
        "type": "object"
      },
      "NotificationPreferencePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/NotificationPreference"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OnBehalfServiceAreaRequest": {
        "properties": {
          "name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OnboardingApplication": {
        "properties": {
          "applicant_name": {
            "description": "The applicant utility's name as given at sign-up or invitation; on platform reads only",
            "type": "string"
          },
          "business_profile": {
            "type": "object"
          },
          "capabilities": {
            "$ref": "#/components/schemas/OnboardingCapabilities"
          },
          "collection_channels": {
            "items": {
              "type": "object"
            },
            "type": "array"
          },
          "current_terms_version": {
            "type": "string"
          },
          "custom_requirement_evidence": {
            "additionalProperties": {
              "$ref": "#/components/schemas/CustomRequirementEvidence"
            },
            "type": "object"
          },
          "documents": {
            "items": {
              "$ref": "#/components/schemas/OnboardingDocument"
            },
            "type": "array"
          },
          "history": {
            "description": "Review events, on platform responses only",
            "items": {
              "properties": {
                "action": {
                  "type": "string"
                },
                "actor": {
                  "type": "string"
                },
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "detail": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "type": "string"
          },
          "rejection_reason": {
            "type": "string"
          },
          "representative": {
            "type": "object"
          },
          "requirements": {
            "$ref": "#/components/schemas/OnboardingRequirements"
          },
          "reviewed_at": {
            "format": "date-time",
            "type": "string"
          },
          "settlement_account": {
            "type": "object"
          },
          "status": {
            "enum": [
              "not_started",
              "in_progress",
              "submitted",
              "under_review",
              "action_required",
              "approved",
              "rejected"
            ],
            "type": "string"
          },
          "submitted_at": {
            "format": "date-time",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "terms": {
            "type": "object"
          },
          "verification_requirements": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "OnboardingApplicationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/OnboardingApplication"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "OnboardingCapabilities": {
        "properties": {
          "billing": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "configure": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "custom_domain": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "customers": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "draft_billing": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "field_operations": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "invoices": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "live_api": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "messages": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "meters": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "payments": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "public_profile": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "reasons": {
            "additionalProperties": {
              "$ref": "#/components/schemas/CapabilityReason"
            },
            "description": "Actionable reason for each non-active capability.",
            "type": "object"
          },
          "sandbox": {
            "enum": [
              "inactive",
              "pending",
              "active",
              "restricted"
            ],
            "type": "string"
          },
          "states": {
            "additionalProperties": {
              "enum": [
                "inactive",
                "pending",
                "active",
                "restricted"
              ],
              "type": "string"
            },
            "type": "object"
          }
        },
        "type": "object"
      },
      "OnboardingDocument": {
        "properties": {
          "content_type": {
            "type": "string"
          },
          "file_name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "rejection_reason": {
            "type": "string"
          },
          "size_bytes": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending",
              "accepted",
              "rejected"
            ],
            "type": "string"
          },
          "type": {
            "enum": [
              "incorporation",
              "tax_certificate",
              "concession_licence",
              "representative_id"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "OnboardingDocumentList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/OnboardingDocument"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "OnboardingDocumentUpload": {
        "properties": {
          "file": {
            "format": "binary",
            "type": "string"
          },
          "type": {
            "enum": [
              "incorporation",
              "tax_certificate",
              "concession_licence",
              "representative_id"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "file"
        ],
        "type": "object"
      },
      "OnboardingRequirements": {
        "properties": {
          "currently_due": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "errors": {
            "items": {
              "properties": {
                "code": {
                  "enum": [
                    "information_requested",
                    "document_rejected"
                  ],
                  "type": "string"
                },
                "reason": {
                  "type": "string"
                },
                "requirement": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "eventually_due": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "past_due": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "pending_verification": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "Organization": {
        "properties": {
          "billing_mode": {
            "enum": [
              "account",
              "organization"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "type": {
            "enum": [
              "utility",
              "authority",
              "operator",
              "regulator",
              "partner",
              "group"
            ],
            "type": "string"
          },
          "utility_kind": {
            "enum": [
              "authority",
              "municipal",
              "regional",
              "national",
              "rural",
              "private",
              "industrial"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "name",
          "type",
          "status",
          "billing_mode"
        ],
        "type": "object"
      },
      "OrganizationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Organization"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "OrganizationPortfolio": {
        "properties": {
          "account_count": {
            "minimum": 0,
            "type": "integer"
          },
          "by_status": {
            "additionalProperties": {
              "minimum": 0,
              "type": "integer"
            },
            "type": "object"
          },
          "organization_id": {
            "type": "string"
          }
        },
        "required": [
          "organization_id",
          "account_count",
          "by_status",
          "by_workspace_state"
        ],
        "type": "object"
      },
      "OrganizationSubscription": {
        "properties": {
          "by_workspace_state": {
            "additionalProperties": {
              "minimum": 0,
              "type": "integer"
            },
            "type": "object"
          },
          "cancel_at_period_end": {
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "current_period_end": {
            "format": "date-time",
            "type": "string"
          },
          "current_period_start": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "past_due_since": {
            "format": "date-time",
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "trialing",
              "active",
              "past_due",
              "suspended",
              "cancelled"
            ],
            "type": "string"
          },
          "suspended_at": {
            "format": "date-time",
            "type": "string"
          },
          "trial_ends_at": {
            "format": "date-time",
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "organization_id",
          "plan_id",
          "status",
          "current_period_start",
          "current_period_end",
          "cancel_at_period_end"
        ],
        "type": "object"
      },
      "OrganizationTemplate": {
        "allOf": [
          {
            "$ref": "#/components/schemas/OrganizationTemplateDraft"
          },
          {
            "properties": {
              "created_at": {
                "format": "date-time",
                "type": "string"
              },
              "created_by": {
                "type": "string"
              },
              "id": {
                "type": "string"
              },
              "organization_id": {
                "type": "string"
              },
              "published_at": {
                "format": "date-time",
                "type": "string"
              },
              "published_by": {
                "type": "string"
              },
              "state": {
                "enum": [
                  "draft",
                  "published"
                ],
                "type": "string"
              }
            },
            "required": [
              "id",
              "organization_id",
              "state",
              "created_by",
              "created_at"
            ],
            "type": "object"
          }
        ]
      },
      "OrganizationTemplateAdoption": {
        "properties": {
          "accepted_at": {
            "format": "date-time",
            "type": "string"
          },
          "accepted_by": {
            "type": "string"
          },
          "applied_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "detached_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "state": {
            "enum": [
              "pending_acceptance",
              "active",
              "detached"
            ],
            "type": "string"
          },
          "template_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "template_id",
          "organization_id",
          "tenant_id",
          "version",
          "state",
          "created_at"
        ],
        "type": "object"
      },
      "OrganizationTemplateDraft": {
        "additionalProperties": false,
        "properties": {
          "description": {
            "maxLength": 1000,
            "type": "string"
          },
          "key": {
            "pattern": "^[a-z][a-z0-9-]{1,62}$",
            "type": "string"
          },
          "name": {
            "maxLength": 160,
            "minLength": 1,
            "type": "string"
          },
          "settings": {
            "additionalProperties": true,
            "description": "Portable setting snapshots. Implemented kinds are tariffs, billing_schedules, automation_rules, notification_templates, and connector_definitions. Secret references, health state, customer data, and other tenant records are rejected or omitted; connectors are created disabled and schedules remain paused.",
            "minProperties": 1,
            "type": "object"
          },
          "version": {
            "maxLength": 40,
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "key",
          "version",
          "name",
          "settings"
        ],
        "type": "object"
      },
      "OrganizationTenantLink": {
        "properties": {
          "added_by": {
            "type": "string"
          },
          "consent_approved_at": {
            "format": "date-time",
            "type": "string"
          },
          "consent_approved_by": {
            "type": "string"
          },
          "grants": {
            "additionalProperties": {
              "items": {
                "type": "string"
              },
              "type": "array"
            },
            "type": "object"
          },
          "id": {
            "type": "string"
          },
          "notice_period_until": {
            "format": "date-time",
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "state": {
            "enum": [
              "pending_consent",
              "active",
              "removal_pending",
              "removed",
              "owned"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "tenant_name": {
            "type": "string"
          },
          "tenant_slug": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "organization_id",
          "tenant_id",
          "state",
          "consent_approved_by",
          "added_by",
          "grants"
        ],
        "type": "object"
      },
      "PaginatedReceivables": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Receivable"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "PasskeyRegistrationOptions": {
        "properties": {
          "challenge": {
            "description": "One-time registration challenge, valid for 5 minutes.",
            "type": "string"
          },
          "rp": {
            "description": "Relying party to register the passkey with.",
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "description": "Product brand name shown by the authenticator",
                "type": "string"
              }
            },
            "required": [
              "id",
              "name"
            ],
            "type": "object"
          },
          "user": {
            "description": "The person the passkey is registered for.",
            "properties": {
              "displayName": {
                "description": "The person's full name",
                "type": "string"
              },
              "id": {
                "description": "Person identifier",
                "type": "string",
                "used as the user handle": null
              },
              "name": {
                "description": "The person's e-mail address or phone number",
                "type": "string"
              }
            },
            "required": [
              "id",
              "name",
              "displayName"
            ],
            "type": "object"
          }
        },
        "required": [
          "challenge",
          "rp",
          "user"
        ],
        "type": "object"
      },
      "PaymentAllocation": {
        "properties": {
          "account_holder_name": {
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "type": "string"
          },
          "amount_cents": {
            "format": "int64",
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "invoice_number": {
            "description": "The invoice's display number",
            "type": "string"
          },
          "invoice_status": {
            "description": "The invoice's current status, read when the response is written; omitted when the invoice cannot be read",
            "type": "string"
          },
          "payment_id": {
            "type": "string"
          },
          "reversed_at": {
            "format": "date-time",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "payment_id",
          "invoice_id",
          "amount_cents",
          "currency",
          "created_at"
        ],
        "type": "object"
      },
      "PaymentConfirmation": {
        "properties": {
          "amount": {
            "format": "int64",
            "minimum": 1,
            "type": "integer"
          },
          "confirmed_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "payment_session_id": {
            "type": "string"
          },
          "provider_reference": {
            "description": "Opaque provider reference; no provider payload or credentials.",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "payment_session_id",
          "provider_reference",
          "amount",
          "currency",
          "confirmed_at",
          "idempotency_key"
        ],
        "type": "object"
      },
      "PaymentJobRequest": {
        "description": "Optional body of a payment job request; an empty or unreadable body is treated as empty.",
        "properties": {
          "currency": {
            "description": "Currency to lease jobs for; defaults to the connector's registered currency.",
            "type": "string"
          },
          "operational_methods": {
            "description": "When present, replaces the connector's declaration of which registered methods are operational now (methods it did not register are dropped). Absent leaves the declaration unchanged; an empty list declares none operational.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "supported_methods": {
            "description": "Methods to lease jobs for; defaults to the methods the connector registered.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "wait_timeout_seconds": {
            "description": "Seconds to wait for a job before answering 204; values above 50 are capped and negative values mean no wait.",
            "maximum": 50,
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PaymentPlan": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "case_id": {
            "pattern": "^col_",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "pattern": "^pln_",
            "type": "string"
          },
          "installment_amount_cents": {
            "format": "int64",
            "type": "integer"
          },
          "installment_count": {
            "minimum": 1,
            "type": "integer"
          },
          "installments": {
            "items": {
              "$ref": "#/components/schemas/PlanInstallment"
            },
            "type": "array"
          },
          "interest_amount_cents": {
            "format": "int64",
            "type": "integer"
          },
          "interest_basis_points": {
            "type": "integer"
          },
          "next_due_date": {
            "format": "date-time",
            "type": "string"
          },
          "remaining_amount_cents": {
            "format": "int64",
            "type": "integer"
          },
          "status": {
            "enum": [
              "active",
              "completed",
              "defaulted",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "total_amount_cents": {
            "format": "int64",
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "case_id",
          "account_id",
          "total_amount_cents",
          "installment_count",
          "installment_amount_cents",
          "remaining_amount_cents",
          "next_due_date",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "PaymentPlanPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/PaymentPlan"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "PaymentReceipt": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "amount_cents": {
            "description": "Amount received, in minor units.",
            "format": "int64",
            "type": "integer"
          },
          "currency": {
            "example": "MZN",
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "invoice_id": {
            "description": "Invoice the payment was applied to.",
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": "string"
          },
          "payment_id": {
            "description": "Payment the receipt was issued for.",
            "type": "string"
          },
          "receipt_number": {
            "description": "Receipt number, unique within the tenant.",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "receipt_number",
          "tenant_id",
          "payment_id",
          "invoice_id",
          "customer_id",
          "account_id",
          "amount_cents",
          "currency",
          "issued_at"
        ],
        "type": "object"
      },
      "PaymentSession": {
        "properties": {
          "amount": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          },
          "currency": {
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "next_action": {
            "discriminator": {
              "propertyName": "type"
            },
            "oneOf": [
              {
                "$ref": "#/components/schemas/RedirectAction"
              },
              {
                "$ref": "#/components/schemas/MobileMoneyAction"
              },
              {
                "$ref": "#/components/schemas/QRCodeAction"
              },
              {
                "$ref": "#/components/schemas/NoAction"
              }
            ]
          },
          "status": {
            "enum": [
              "pending",
              "confirmed",
              "failed",
              "expired",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "invoice_id",
          "amount",
          "currency",
          "status",
          "next_action"
        ],
        "type": "object"
      },
      "PhoneVerificationConfirm": {
        "properties": {
          "code": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "phone",
          "code"
        ],
        "type": "object"
      },
      "PhoneVerificationRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "phone": {
            "type": "string"
          }
        },
        "required": [
          "phone"
        ],
        "type": "object"
      },
      "Plan": {
        "properties": {
          "capabilities": {
            "items": {
              "enum": [
                "configure",
                "customers",
                "meters",
                "draft_billing",
                "invoices",
                "payments",
                "messages",
                "public_profile",
                "custom_domain",
                "live_api",
                "sandbox"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "capability_labels": {
            "description": "The capabilities labelled in the caller's language (reads)",
            "items": {
              "$ref": "#/components/schemas/CapabilityLabel"
            },
            "type": "array"
          },
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "default_name": {
            "description": "Platform plan list only; the default name behind a localised name",
            "type": "string"
          },
          "default_tagline": {
            "description": "Platform plan list only; the default tagline",
            "type": "string"
          },
          "display_order": {
            "type": "integer"
          },
          "highlighted": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "max_accounts": {
            "description": "Maximum accounts owned by the subscribed organization's legal entity; 0 means no plan cap",
            "type": "integer"
          },
          "max_connections": {
            "type": "integer"
          },
          "max_sandboxes": {
            "type": "integer"
          },
          "max_users": {
            "type": "integer"
          },
          "name": {
            "description": "Display name in the caller's language on reads",
            "else the plan's default": null,
            "type": "string"
          },
          "name_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "overage_connection_cents": {
            "type": "integer"
          },
          "overage_user_cents": {
            "type": "integer"
          },
          "price_cents": {
            "type": "integer"
          },
          "published": {
            "type": "boolean"
          },
          "tagline": {
            "description": "Tagline in the caller's language on reads",
            "else the plan's default": null,
            "type": "string"
          },
          "tagline_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "trial_days": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PlanInstallment": {
        "properties": {
          "amount_cents": {
            "format": "int64",
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "due_date": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "pattern": "^ins_",
            "type": "string"
          },
          "number": {
            "minimum": 1,
            "type": "integer"
          },
          "paid_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "plan_id": {
            "pattern": "^pln_",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "paid",
              "overdue"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "plan_id",
          "number",
          "due_date",
          "amount_cents",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "PlanOffer": {
        "description": "A choice listed beside the plans that is not a plan. Code custom is the offer past the largest published plan, and what the limit error's next_plan_code custom points to; it is configured by the operator (subscription.custom_offer).",
        "properties": {
          "above_connections": {
            "description": "The active connection count the offer starts above",
            "type": "integer"
          },
          "code": {
            "example": "custom",
            "type": "string"
          },
          "contact_path": {
            "description": "Path on the public site to contact sales",
            "example": "/contact?topic=sales",
            "type": "string"
          },
          "cta": {
            "description": "The link's wording in the caller's language",
            "type": "string"
          },
          "cta_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "label": {
            "description": "Title in the caller's language",
            "type": "string"
          },
          "label_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "text": {
            "description": "One line in the caller's language",
            "type": "string",
            "with the size filled in": null
          },
          "text_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          }
        },
        "required": [
          "code",
          "label",
          "text",
          "cta",
          "contact_path",
          "above_connections"
        ],
        "type": "object"
      },
      "PlatformBranding": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Branding"
          },
          {
            "properties": {
              "configured": {
                "description": "The configured values a reset returns to, in the public shape without asset URLs.",
                "type": "object"
              },
              "sources": {
                "properties": {
                  "accent": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "brand": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "brand_foreground": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "copyright": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "icon": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "legal_name": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "logo": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "logo_dark": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "name": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "privacy_url": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "short_name": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "support_email": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "support_phone": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "support_url": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "terms_url": {
                    "$ref": "#/components/schemas/BrandingSource"
                  },
                  "website_url": {
                    "$ref": "#/components/schemas/BrandingSource"
                  }
                },
                "type": "object"
              }
            },
            "required": [
              "sources",
              "configured"
            ],
            "type": "object"
          }
        ]
      },
      "PlatformContactRequest": {
        "properties": {
          "connections": {
            "description": "Optional number of service connections the organization runs; omitted when not given",
            "minimum": 0,
            "type": "integer"
          },
          "created_at": {
            "description": "When the request was submitted",
            "format": "date-time",
            "type": "string"
          },
          "email": {
            "description": "Reply address",
            "format": "email",
            "stored in lower case": null,
            "type": "string"
          },
          "id": {
            "description": "Contact request identifier",
            "example": "crq_01JD3M5Q7Z8K2N4P6R8T0V2X4Y",
            "type": "string"
          },
          "locale": {
            "description": "Language the person wrote from",
            "enum": [
              "pt",
              "en"
            ],
            "type": "string"
          },
          "message": {
            "description": "The message text",
            "type": "string"
          },
          "name": {
            "description": "Name of the person who wrote",
            "example": "Ana Matsinhe",
            "type": "string"
          },
          "organization": {
            "description": "Organization the person represents",
            "type": "string"
          },
          "phone": {
            "description": "Optional phone number; omitted when not given",
            "type": "string"
          },
          "status": {
            "description": "Follow-up status set by the platform team",
            "enum": [
              "new",
              "contacted",
              "closed"
            ],
            "type": "string"
          },
          "topic": {
            "description": "What the request is about",
            "enum": [
              "sales",
              "support",
              "partnership",
              "press",
              "security"
            ],
            "type": "string"
          },
          "updated_at": {
            "description": "When the request or its status last changed",
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "topic",
          "name",
          "organization",
          "email",
          "message",
          "locale",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "PlatformContactRequestPage": {
        "properties": {
          "data": {
            "description": "Contact requests",
            "items": {
              "$ref": "#/components/schemas/PlatformContactRequest"
            },
            "newest first": null,
            "type": "array"
          },
          "has_more": {
            "description": "True when another page follows",
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Pass as cursor to get the next page; empty on the last page",
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more",
          "next_cursor"
        ],
        "type": "object"
      },
      "PlatformDocsFeedback": {
        "properties": {
          "comment": {
            "description": "Optional comment; omitted when empty",
            "type": "string"
          },
          "created_at": {
            "description": "When the vote was recorded",
            "format": "date-time",
            "type": "string"
          },
          "helpful": {
            "description": "True when the reader found the page helpful",
            "type": "boolean"
          },
          "id": {
            "description": "Feedback identifier",
            "example": "dfb_01JD3M5Q7Z8K2N4P6R8T0V2X4Y",
            "type": "string"
          },
          "locale": {
            "description": "Language of the page the reader voted on",
            "enum": [
              "pt",
              "en"
            ],
            "type": "string"
          },
          "path": {
            "description": "Documentation page path the vote is about",
            "example": "/docs/api/authentication",
            "type": "string"
          }
        },
        "required": [
          "id",
          "path",
          "helpful",
          "locale",
          "created_at"
        ],
        "type": "object"
      },
      "PlatformDocsFeedbackPage": {
        "properties": {
          "data": {
            "description": "Feedback",
            "items": {
              "$ref": "#/components/schemas/PlatformDocsFeedback"
            },
            "newest first": null,
            "type": "array"
          },
          "has_more": {
            "description": "True when another page follows",
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Pass as cursor to get the next page; empty on the last page",
            "type": "string"
          },
          "summary": {
            "description": "Vote totals per path, sorted by path, over all feedback (or the filtered path), ignoring the helpful filter and paging.",
            "items": {
              "$ref": "#/components/schemas/PlatformDocsFeedbackSummary"
            },
            "type": "array"
          }
        },
        "required": [
          "data",
          "summary",
          "has_more",
          "next_cursor"
        ],
        "type": "object"
      },
      "PlatformDocsFeedbackSummary": {
        "properties": {
          "helpful_count": {
            "description": "Number of helpful votes on the path",
            "format": "int64",
            "type": "integer"
          },
          "path": {
            "description": "Documentation page path",
            "type": "string"
          },
          "unhelpful_count": {
            "description": "Number of unhelpful votes on the path",
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "path",
          "helpful_count",
          "unhelpful_count"
        ],
        "type": "object"
      },
      "PlatformDomainCheck": {
        "properties": {
          "checked_at": {
            "format": "date-time",
            "type": "string"
          },
          "ok": {
            "type": "boolean"
          },
          "origins": {
            "items": {
              "properties": {
                "checked_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "key": {
                  "example": "clients.site.external_url",
                  "type": "string"
                },
                "name": {
                  "enum": [
                    "site",
                    "dashboard",
                    "api"
                  ],
                  "type": "string"
                },
                "ok": {
                  "type": "boolean"
                },
                "origin": {
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "reason": {
                  "description": "http_5xx is any other server error status",
                  "enum": [
                    "not_configured",
                    "unreachable",
                    "invalid_url",
                    "http_500",
                    "http_502",
                    "http_503",
                    "http_504",
                    "http_5xx"
                  ],
                  "type": "string"
                }
              },
              "required": [
                "name",
                "key",
                "origin",
                "ok",
                "checked_at"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "checked_at",
          "ok",
          "origins"
        ],
        "type": "object"
      },
      "PlatformFunnel": {
        "properties": {
          "from": {
            "format": "date-time",
            "type": "string"
          },
          "journeys": {
            "items": {
              "properties": {
                "from": {
                  "format": "date-time",
                  "type": "string"
                },
                "journey_id": {
                  "enum": [
                    "platform_setup",
                    "utility_test",
                    "utility_real",
                    "resident_link",
                    "resident_connection",
                    "staff_field_reader",
                    "staff_cashier",
                    "staff_finance"
                  ],
                  "type": "string"
                },
                "median_sample_count": {
                  "type": "integer"
                },
                "median_seconds_to_value": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "steps": {
                  "items": {
                    "properties": {
                      "abandoned_count": {
                        "type": "integer"
                      },
                      "completed_count": {
                        "type": "integer"
                      },
                      "skipped_count": {
                        "type": "integer"
                      },
                      "started_count": {
                        "type": "integer"
                      },
                      "step_id": {
                        "type": "string"
                      }
                    },
                    "required": [
                      "step_id",
                      "started_count",
                      "completed_count",
                      "skipped_count",
                      "abandoned_count"
                    ],
                    "type": "object"
                  },
                  "type": "array"
                },
                "to": {
                  "format": "date-time",
                  "type": "string"
                },
                "value_step_id": {
                  "description": "The step whose completion is the moment of value",
                  "example": "run_billing",
                  "type": "string"
                }
              },
              "required": [
                "journey_id",
                "from",
                "to",
                "value_step_id",
                "steps",
                "median_seconds_to_value",
                "median_sample_count"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "to": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "from",
          "to",
          "journeys"
        ],
        "type": "object"
      },
      "PlatformHealth": {
        "properties": {
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "items": {
            "items": {
              "properties": {
                "checked_at": {
                  "format": "date-time",
                  "type": [
                    "string",
                    "null"
                  ]
                },
                "id": {
                  "enum": [
                    "connectors",
                    "delivery",
                    "payment",
                    "error_rate",
                    "backup"
                  ],
                  "type": "string"
                },
                "interval": {
                  "type": "string"
                },
                "last_success_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "reason": {
                  "description": "Stable code: connectors no_connector, some_offline or all_offline; delivery no_connector, no_recent_delivery or recent_failures; payment not_tested or the last payment test code; error_rate and backup telemetry_unavailable",
                  "enum": [
                    "no_connector",
                    "some_offline",
                    "all_offline",
                    "no_recent_delivery",
                    "recent_failures",
                    "not_tested",
                    "telemetry_unavailable",
                    "no_payment_connector",
                    "no_test_account",
                    "connector_misconfigured",
                    "connector_unreachable",
                    "no_operational_method"
                  ],
                  "example": "telemetry_unavailable",
                  "type": "string"
                },
                "route": {
                  "type": "string"
                },
                "state": {
                  "enum": [
                    "healthy",
                    "degraded",
                    "down",
                    "unknown"
                  ],
                  "type": "string"
                },
                "title": {
                  "type": "string"
                },
                "value": {
                  "description": "Measured value",
                  "example": "2/2",
                  "only when measured": null,
                  "type": "string"
                }
              },
              "required": [
                "id",
                "title",
                "state",
                "checked_at"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "generated_at",
          "items"
        ],
        "type": "object"
      },
      "PlatformInvoice": {
        "properties": {
          "balance_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "due_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/PlatformInvoiceLine"
            },
            "type": "array"
          },
          "number": {
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "paid_at": {
            "format": "date-time",
            "type": "string"
          },
          "payment_methods": {
            "description": "The payment methods the platform accepts for this invoice; recording or proving a payment by any other is refused with payment.method_not_configured.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "open",
              "paid",
              "void"
            ],
            "type": "string"
          },
          "subscription_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "total_cents": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PlatformInvoiceLine": {
        "properties": {
          "amount_cents": {
            "type": "integer"
          },
          "code": {
            "description": "Stable line code: plan, account_plan, overage_connections, overage_users, proration. Clients word it with params and fall back to description.",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "params": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values the code's wording fills in: plan; plan, account, pro_rata; over, included (account, pro_rata); from, to.",
            "type": "object"
          },
          "plan_id": {
            "description": "Plan applied to this account",
            "type": "string"
          },
          "quantity": {
            "type": "number"
          },
          "tenant_id": {
            "description": "Account covered by this line",
            "type": "string"
          },
          "unit_price_cents": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PlatformInvoicePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/PlatformInvoice"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlatformOverview": {
        "properties": {
          "active_utilities": {
            "type": "integer"
          },
          "arr_cents": {
            "format": "int64",
            "type": "integer"
          },
          "churn_rate": {
            "type": "number"
          },
          "connections_under_management": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "meters_under_management": {
            "type": "integer"
          },
          "mrr_cents": {
            "format": "int64",
            "type": "integer"
          },
          "mrr_series": {
            "description": "MRR at the end of each of the last 12 months (the last point is today), rebuilt from subscription start and cancellation times at each plan's price. Trialing subscriptions are excluded.",
            "items": {
              "$ref": "#/components/schemas/SeriesPoint"
            },
            "type": "array"
          },
          "new_subscriptions_series": {
            "items": {
              "$ref": "#/components/schemas/SeriesPoint"
            },
            "type": "array"
          },
          "onboarding_pipeline": {
            "additionalProperties": {
              "type": "integer"
            },
            "type": "object"
          },
          "past_due_utilities": {
            "type": "integer"
          },
          "trialing_utilities": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PlatformPaymentTest": {
        "properties": {
          "checked_at": {
            "format": "date-time",
            "type": "string"
          },
          "code": {
            "enum": [
              "no_payment_connector",
              "no_test_account",
              "connector_misconfigured",
              "connector_unreachable",
              "no_operational_method"
            ],
            "type": "string"
          },
          "connector": {
            "type": "string"
          },
          "message": {
            "type": "string"
          },
          "next_action": {
            "properties": {
              "id": {
                "type": "string"
              },
              "route": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "outcome": {
            "enum": [
              "succeeded",
              "failed",
              "pending"
            ],
            "type": "string"
          },
          "retryable": {
            "type": "boolean"
          }
        },
        "required": [
          "outcome",
          "message",
          "checked_at",
          "retryable"
        ],
        "type": "object"
      },
      "PlatformPaymentTestRequest": {
        "additionalProperties": false,
        "properties": {
          "connector": {
            "description": "Name of a connectors.payments[] entry; the first when omitted",
            "type": "string"
          }
        },
        "type": "object"
      },
      "PlatformSetup": {
        "properties": {
          "complete": {
            "description": "Every item is done or explicitly skipped",
            "type": "boolean"
          },
          "generated_at": {
            "format": "date-time",
            "type": "string"
          },
          "items": {
            "items": {
              "$ref": "#/components/schemas/PlatformSetupItem"
            },
            "type": "array"
          },
          "locale": {
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "settings": {
            "items": {
              "$ref": "#/components/schemas/PlatformSetupSetting"
            },
            "type": "array"
          }
        },
        "required": [
          "locale",
          "generated_at",
          "items",
          "settings",
          "complete"
        ],
        "type": "object"
      },
      "PlatformSetupItem": {
        "properties": {
          "action": {
            "properties": {
              "id": {
                "example": "platform.setup.domains",
                "type": "string"
              },
              "route": {
                "example": "/platform/onboarding?step=domains",
                "type": "string"
              }
            },
            "required": [
              "id",
              "route"
            ],
            "type": "object"
          },
          "checked_at": {
            "format": "date-time",
            "type": "string"
          },
          "help_article_id": {
            "example": "getting-started/platform-health",
            "type": "string"
          },
          "id": {
            "enum": [
              "brand",
              "domains",
              "messaging_connector",
              "payment_connector",
              "plans",
              "first_utility"
            ],
            "type": "string"
          },
          "line": {
            "type": "string"
          },
          "reason": {
            "description": "Stable code: why the item is blocked (origin_unset, no_messaging_connector, no_payment_connector), waiting_for_owner, the skip reason (not_needed, later, already_set_up), or the last failed check (origin_unreachable, test_message_failed, test_message_expired, or a payment test code)",
            "enum": [
              "origin_unset",
              "no_messaging_connector",
              "no_payment_connector",
              "waiting_for_owner",
              "not_needed",
              "later",
              "already_set_up",
              "origin_unreachable",
              "test_message_failed",
              "test_message_expired",
              "no_test_account",
              "connector_misconfigured",
              "connector_unreachable",
              "no_operational_method"
            ],
            "example": "origin_unset",
            "type": "string"
          },
          "settings": {
            "items": {
              "$ref": "#/components/schemas/PlatformSetupSetting"
            },
            "type": "array"
          },
          "state": {
            "enum": [
              "todo",
              "done",
              "skipped",
              "blocked"
            ],
            "type": "string"
          },
          "title": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "title",
          "line",
          "state",
          "action"
        ],
        "type": "object"
      },
      "PlatformSetupSetting": {
        "properties": {
          "editable": {
            "type": "boolean"
          },
          "how_to": {
            "description": "How to change a file-only setting",
            "type": "string"
          },
          "key": {
            "example": "server.http.public.external_url",
            "type": "string"
          },
          "label": {
            "type": "string"
          },
          "route": {
            "description": "In-app route for a run-time setting",
            "type": "string"
          },
          "secret_configured": {
            "description": "For connector tokens",
            "type": "boolean",
            "whether one is configured; never the value": null
          },
          "source": {
            "enum": [
              "runtime",
              "file"
            ],
            "type": "string"
          },
          "value": {
            "description": "Current non-secret value; null when unset",
            "type": [
              "string",
              "null"
            ]
          }
        },
        "required": [
          "key",
          "label",
          "source",
          "value",
          "editable"
        ],
        "type": "object"
      },
      "PrepaidMeter": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "balance_cents": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "id": {
            "pattern": "^ppm_",
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "suspended"
            ],
            "type": "string"
          },
          "tariff_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "vending_key_ref": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "account_id",
          "status",
          "balance_cents",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "PrepaidMeterPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/PrepaidMeter"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "PrepaidQuote": {
        "properties": {
          "currency": {
            "type": "string"
          },
          "litres": {
            "type": "integer"
          },
          "net_cents": {
            "type": "integer"
          },
          "remainder_cents": {
            "type": "integer"
          },
          "sanitation_cents": {
            "type": "integer"
          },
          "tariff_id": {
            "type": "string"
          },
          "tax_cents": {
            "type": "integer"
          }
        },
        "required": [
          "litres",
          "net_cents",
          "sanitation_cents",
          "tax_cents",
          "remainder_cents",
          "currency",
          "tariff_id"
        ],
        "type": "object"
      },
      "PrepaidVend": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "amount_cents": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "failure_reason": {
            "type": "string"
          },
          "id": {
            "pattern": "^vnd_",
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": "string"
          },
          "litres": {
            "type": "integer"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "net_cents": {
            "type": "integer"
          },
          "payment_id": {
            "type": "string"
          },
          "payment_session_id": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "prepaid_meter_id": {
            "pattern": "^ppm_",
            "type": "string"
          },
          "receipt_number": {
            "type": "string"
          },
          "remainder_cents": {
            "type": "integer"
          },
          "sanitation_cents": {
            "type": "integer"
          },
          "status": {
            "enum": [
              "pending_payment",
              "issued",
              "failed"
            ],
            "type": "string"
          },
          "tariff_id": {
            "type": "string"
          },
          "tax_cents": {
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "token": {
            "type": "string"
          },
          "token_is_dev_stub": {
            "type": "boolean"
          },
          "token_provider": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "prepaid_meter_id",
          "meter_id",
          "account_id",
          "status",
          "amount_cents",
          "token_is_dev_stub",
          "idempotency_key",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "PrepaidVendPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/PrepaidVend"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "PrepaidWalletEntry": {
        "properties": {
          "amount_cents": {
            "type": "integer"
          },
          "balance_after_cents": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "pattern": "^wen_",
            "type": "string"
          },
          "kind": {
            "enum": [
              "credit",
              "debit"
            ],
            "type": "string"
          },
          "prepaid_meter_id": {
            "pattern": "^ppm_",
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "prepaid_meter_id",
          "kind",
          "amount_cents",
          "balance_after_cents",
          "reference",
          "created_at"
        ],
        "type": "object"
      },
      "PrepaidWalletPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/PrepaidWalletEntry"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ProblemDetails": {
        "properties": {
          "code": {
            "description": "Stable machine-readable error code.",
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "error_code": {
            "description": "Stable, specific error code clients translate (lowercase and dotted, for example validation.field_required, state.invalid_transition, subscription.suspended). Codes are listed in pkg/apierror and never change once shipped; detail stays the fallback text for codes a client does not know. When the error has no more specific code it names the problem kind (request.invalid, resource.not_found, resource.conflict, auth.forbidden, ...).",
            "example": "proof.already_reviewed",
            "type": "string"
          },
          "instance": {
            "type": "string"
          },
          "invalid_params": {
            "items": {
              "$ref": "#/components/schemas/InvalidParam"
            },
            "type": "array"
          },
          "params": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values for the error_code message: field (the API field, or several joined by commas) and, for bounded codes such as validation.too_long or validation.out_of_range, min and max; import codes carry line, column or max.",
            "example": {
              "field": "currency"
            },
            "type": "object"
          },
          "status": {
            "type": "integer"
          },
          "title": {
            "type": "string"
          },
          "type": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "type",
          "title",
          "status",
          "detail",
          "code"
        ],
        "type": "object"
      },
      "Property": {
        "properties": {
          "address_line": {
            "type": "string"
          },
          "address_line_2": {
            "type": "string"
          },
          "cadastral_code": {
            "description": "Unique per tenant.",
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "district": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "latitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "locality": {
            "type": "string"
          },
          "longitude": {
            "type": [
              "number",
              "null"
            ]
          },
          "neighbourhood": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "premise_type": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government",
              "mixed",
              "other"
            ],
            "type": "string"
          },
          "province": {
            "type": "string"
          },
          "reference": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "customer_id",
          "address_line",
          "status"
        ],
        "type": "object"
      },
      "PropertyDetails": {
        "properties": {
          "address_line_2": {
            "type": "string"
          },
          "cadastral_code": {
            "type": "string"
          },
          "city": {
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "neighbourhood": {
            "type": "string"
          },
          "postal_code": {
            "type": "string"
          },
          "premise_type": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "PropertyPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Property"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "PublicAreaListing": {
        "properties": {
          "contact_phone": {
            "description": "Optional public contact phone",
            "type": "string"
          },
          "coverage_note": {
            "description": "Optional note about coverage in the area",
            "type": "string"
          },
          "currency": {
            "description": "Currency of the estimate",
            "type": "string",
            "when one is given": null
          },
          "estimate_max_cents": {
            "description": "Optional upper bound of a new connection estimate",
            "format": "int64",
            "in minor units": null,
            "type": "integer"
          },
          "estimate_min_cents": {
            "description": "Optional lower bound of a new connection estimate",
            "format": "int64",
            "in minor units": null,
            "type": "integer"
          },
          "locality": {
            "description": "Name of the matching service area",
            "example": "Machava",
            "type": "string"
          },
          "profiled": {
            "description": "Whether the utility has a public profile; basic listings are false",
            "type": "boolean"
          },
          "tenant_id": {
            "description": "Identifier of the utility serving the area",
            "type": "string"
          },
          "tenant_slug": {
            "description": "Utility slug for its public brand files (GET /branding/tenants/{slug}/assets/{kind})",
            "type": "string"
          },
          "utility_name": {
            "description": "The utility's trading name",
            "or its registered name when it has none": null,
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "utility_name",
          "locality",
          "profiled"
        ],
        "type": "object"
      },
      "PublicAreaSearchResponse": {
        "properties": {
          "data": {
            "at most limit": null,
            "description": "Matching listings",
            "items": {
              "$ref": "#/components/schemas/PublicAreaListing"
            },
            "type": "array"
          },
          "query": {
            "description": "The trimmed search text",
            "type": "string"
          }
        },
        "required": [
          "data",
          "query"
        ],
        "type": "object"
      },
      "PublicConnector": {
        "properties": {
          "capabilities": {
            "as named by the connector": null,
            "description": "What the connector supports",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "description": {
            "description": "Short description for an integrations directory",
            "type": "string"
          },
          "key": {
            "description": "Stable connector key",
            "lower case": null,
            "type": "string"
          },
          "kind": {
            "description": "Connector kind, for example payment, messaging or meter",
            "type": "string"
          },
          "mark": {
            "description": "URL path of the connector's mark image; omitted when it has none",
            "type": "string"
          },
          "name": {
            "description": "Display name",
            "type": "string"
          }
        },
        "required": [
          "key",
          "kind",
          "name",
          "description",
          "capabilities"
        ],
        "type": "object"
      },
      "PublicConnectorList": {
        "properties": {
          "data": {
            "description": "Enabled connectors sorted by kind",
            "items": {
              "$ref": "#/components/schemas/PublicConnector"
            },
            "then key": null,
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "PublicContactRequestReceipt": {
        "properties": {
          "created_at": {
            "description": "When the request was received",
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "description": "Contact request identifier",
            "type": "string"
          },
          "status": {
            "description": "Always new for a fresh request",
            "enum": [
              "new"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "PublicDocsFeedbackReceipt": {
        "properties": {
          "created_at": {
            "description": "When the vote was recorded",
            "format": "date-time",
            "type": "string"
          },
          "helpful": {
            "description": "The recorded vote",
            "type": "boolean"
          },
          "id": {
            "description": "Feedback identifier",
            "type": "string"
          },
          "path": {
            "description": "Documentation page path",
            "type": "string"
          }
        },
        "required": [
          "id",
          "path",
          "helpful",
          "created_at"
        ],
        "type": "object"
      },
      "PublicPaymentInstruction": {
        "properties": {
          "label": {
            "as configured by the operator": null,
            "description": "What the value is",
            "example": "Account number",
            "type": "string"
          },
          "value": {
            "description": "The value to use when paying",
            "type": "string"
          }
        },
        "required": [
          "label",
          "value"
        ],
        "type": "object"
      },
      "PublicPaymentInstructions": {
        "properties": {
          "instructions": {
            "description": "Operator-configured payment details; empty when none",
            "items": {
              "$ref": "#/components/schemas/PublicPaymentInstruction"
            },
            "type": "array"
          },
          "methods": {
            "as named by the enabled connectors": null,
            "description": "Payment method keys accepted for platform invoices",
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "methods",
          "instructions"
        ],
        "type": "object"
      },
      "PublicPlan": {
        "properties": {
          "capabilities": {
            "items": {
              "enum": [
                "configure",
                "customers",
                "meters",
                "draft_billing",
                "invoices",
                "payments",
                "messages",
                "public_profile",
                "custom_domain",
                "live_api",
                "sandbox"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "capability_labels": {
            "items": {
              "$ref": "#/components/schemas/CapabilityLabel"
            },
            "type": "array"
          },
          "code": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "display_order": {
            "type": "integer"
          },
          "highlighted": {
            "type": "boolean"
          },
          "max_accounts": {
            "type": "integer"
          },
          "max_connections": {
            "description": "0 means no limit",
            "type": "integer"
          },
          "max_sandboxes": {
            "type": "integer"
          },
          "max_users": {
            "description": "0 means no limit",
            "type": "integer"
          },
          "name": {
            "description": "Display name in the caller's language",
            "else the plan's default": null,
            "type": "string"
          },
          "name_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "overage_connection_cents": {
            "type": "integer"
          },
          "overage_user_cents": {
            "type": "integer"
          },
          "price_cents": {
            "type": "integer"
          },
          "tagline": {
            "description": "Tagline in the caller's language",
            "else the plan's default": null,
            "type": "string"
          },
          "tagline_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "trial_days": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "PublicPlanList": {
        "properties": {
          "data": {
            "description": "Published plans",
            "items": {
              "$ref": "#/components/schemas/PublicPlan"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "PublicServiceRequest": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "estimate_max_cents": {
            "format": "int64",
            "type": "integer"
          },
          "estimate_min_cents": {
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "pattern": "^sqr_",
            "type": "string"
          },
          "priced": {
            "type": "boolean"
          },
          "status": {
            "enum": [
              "submitted",
              "accepted",
              "visit_scheduled",
              "quoted",
              "payment_pending",
              "scheduled",
              "completed",
              "declined",
              "withdrawn"
            ],
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "status",
          "priced",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "PublicServiceRequestInput": {
        "properties": {
          "address": {
            "description": "Required unless plus_code is given",
            "maxLength": 255,
            "type": "string"
          },
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "connection_type": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "full_name": {
            "maxLength": 255,
            "type": "string"
          },
          "landmark": {
            "maxLength": 255,
            "type": "string"
          },
          "locality": {
            "maxLength": 128,
            "type": "string"
          },
          "otp_code": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "plus_code": {
            "maxLength": 64,
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "tenant_id",
          "phone",
          "otp_code"
        ],
        "type": "object"
      },
      "PutQualityStandardRequest": {
        "properties": {
          "max_value": {
            "type": "number"
          },
          "min_value": {
            "type": "number"
          },
          "source": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "unit"
        ],
        "type": "object"
      },
      "QRCodeAction": {
        "properties": {
          "payload": {
            "type": "string"
          },
          "type": {
            "const": "qr_code"
          }
        },
        "required": [
          "type",
          "payload"
        ],
        "type": "object"
      },
      "QualityStandard": {
        "properties": {
          "id": {
            "type": "string"
          },
          "max_value": {
            "type": "number"
          },
          "min_value": {
            "type": "number"
          },
          "parameter": {
            "enum": [
              "residual_chlorine",
              "ph",
              "turbidity",
              "e_coli",
              "coliforms"
            ],
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "parameter",
          "unit"
        ],
        "type": "object"
      },
      "QualityStandardList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/QualityStandard"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "QuotePrepaidVendRequest": {
        "additionalProperties": false,
        "properties": {
          "amount_cents": {
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "amount_cents"
        ],
        "type": "object"
      },
      "QuotePriceList": {
        "properties": {
          "currency": {
            "type": "string"
          },
          "prices": {
            "items": {
              "properties": {
                "amount_cents": {
                  "format": "int64",
                  "type": "integer"
                },
                "code": {
                  "type": "string"
                },
                "diameter_mm": {
                  "type": "integer"
                },
                "key": {
                  "description": "Names the price on a quote line; code",
                  "or code": "diameter",
                  "type": "string"
                },
                "kind": {
                  "enum": [
                    "connection_fee",
                    "material",
                    "labour"
                  ],
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "one_time": {
                  "type": "boolean"
                },
                "taxable": {
                  "type": "boolean"
                }
              },
              "required": [
                "key",
                "code",
                "name",
                "kind",
                "amount_cents",
                "taxable",
                "one_time"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "tariff_version_id": {
            "type": "string"
          },
          "tax_percent": {
            "type": "number"
          }
        },
        "required": [
          "tax_percent",
          "prices"
        ],
        "type": "object"
      },
      "Reading": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "assignment_id": {
            "type": "string"
          },
          "client_reading_id": {
            "type": "string"
          },
          "connection_holder_name": {
            "description": "Display name of the customer who holds the referenced connection. Omitted when unknown.",
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "correction_reason": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "cycle_id": {
            "type": "string"
          },
          "estimate_reason": {
            "type": "string"
          },
          "evidence_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "external_id": {
            "type": "string"
          },
          "has_rollover": {
            "type": "boolean"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "is_billed": {
            "type": "boolean"
          },
          "measured_at": {
            "format": "date-time",
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "The meter's serial number; present on consumer reading listings",
            "type": "string"
          },
          "method": {
            "enum": [
              "manual",
              "consumer",
              "remote",
              "imported",
              "estimated"
            ],
            "type": "string"
          },
          "photo_evidence": {
            "type": "string"
          },
          "plausibility_status": {
            "enum": [
              "passed",
              "flagged_high",
              "flagged_negative",
              "flagged_zero",
              "verified_manual"
            ],
            "type": "string"
          },
          "previous_value": {
            "type": "string"
          },
          "raw_consumption": {
            "description": "Advance since previous_value in the meter unit; a plausible decrease is treated as a rollover.",
            "type": "string"
          },
          "raw_consumption_microlitres": {
            "format": "int64",
            "type": "integer"
          },
          "received_at": {
            "format": "date-time",
            "type": "string"
          },
          "rejection_reason": {
            "type": "string"
          },
          "review_reason": {
            "type": "string"
          },
          "review_reason_code": {
            "description": "Stable code of the plausibility check that sent the reading to review (reading_review.below_reset_baseline, reading_review.earlier_than_latest, reading_review.earlier_or_lower, reading_review.zero_with_recent_usage, reading_review.above_three_month_average); clients word it and fall back to review_reason.",
            "type": "string"
          },
          "reviewed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "reviewed_by": {
            "type": "string"
          },
          "route_id": {
            "type": "string"
          },
          "source": {
            "enum": [
              "mobile_reader",
              "customer_self_reading",
              "ami_interval",
              "office_estimate"
            ],
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "submitted",
              "validating",
              "accepted",
              "review_required",
              "rejected",
              "superseded"
            ],
            "type": "string"
          },
          "submitted_by": {
            "type": "string"
          },
          "superseded_by_id": {
            "type": "string"
          },
          "supersedes_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "account_id",
          "value",
          "unit",
          "measured_at",
          "received_at",
          "method",
          "submitted_by",
          "client_reading_id",
          "idempotency_key",
          "status",
          "created_at"
        ],
        "type": "object"
      },
      "ReadingAssignment": {
        "properties": {
          "assigned_at": {
            "format": "date-time",
            "type": "string"
          },
          "assigned_by": {
            "type": "string"
          },
          "cancelled_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "completed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "due_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "meter_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "reader_id": {
            "type": "string"
          },
          "round_id": {
            "type": "string"
          },
          "started_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "enum": [
              "assigned",
              "in_progress",
              "completed",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "round_id",
          "reader_id",
          "meter_ids",
          "status",
          "assigned_by",
          "assigned_at",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ReadingCorrectionInput": {
        "properties": {
          "idempotency_key": {
            "maxLength": 160,
            "type": "string"
          },
          "reason": {
            "maxLength": 500,
            "minLength": 1,
            "type": "string"
          },
          "value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          }
        },
        "required": [
          "value",
          "reason",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ReadingCycle": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "billing_frequency": {
            "enum": [
              "monthly",
              "bimonthly",
              "quarterly",
              "semiannual",
              "annual"
            ],
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "schedule_day_of_month": {
            "maximum": 28,
            "minimum": 1,
            "type": "integer"
          }
        },
        "required": [
          "code",
          "billing_frequency",
          "schedule_day_of_month"
        ],
        "type": "object"
      },
      "ReadingDispute": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "identity_id": {
            "type": "string"
          },
          "reading_id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "requester_name": {
            "description": "Who filed it, which can differ from the account holder.",
            "type": "string"
          },
          "resolution": {
            "type": "string"
          },
          "resolved_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "resolved_by": {
            "type": "string"
          },
          "status": {
            "enum": [
              "open",
              "in_review",
              "resolved",
              "rejected"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "account_id",
          "reading_id",
          "identity_id",
          "reason",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ReadingDisputePage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ReadingDispute"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ReadingImportRequest": {
        "properties": {
          "batch_id": {
            "maxLength": 120,
            "type": "string"
          },
          "rows": {
            "items": {
              "properties": {
                "estimate_reason": {
                  "type": "string"
                },
                "evidence_ids": {
                  "items": {
                    "type": "string"
                  },
                  "maxItems": 19,
                  "type": "array"
                },
                "measured_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "meter_id": {
                  "type": "string"
                },
                "row_id": {
                  "maxLength": 120,
                  "type": "string"
                },
                "unit": {
                  "type": "string"
                },
                "value": {
                  "pattern": "^\\d+(\\.\\d+)?$",
                  "type": "string"
                }
              },
              "required": [
                "row_id",
                "meter_id",
                "value",
                "unit",
                "measured_at"
              ],
              "type": "object"
            },
            "maxItems": 500,
            "minItems": 1,
            "type": "array"
          },
          "source_file_reference": {
            "maxLength": 500,
            "type": "string"
          }
        },
        "required": [
          "batch_id",
          "source_file_reference",
          "rows"
        ],
        "type": "object"
      },
      "ReadingPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Reading"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ReadingRequest": {
        "properties": {
          "attempt_count": {
            "minimum": 0,
            "type": "integer"
          },
          "completed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "due_at": {
            "format": "date-time",
            "type": "string"
          },
          "failure_reason": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "idempotency_key": {
            "type": "string"
          },
          "leased_until": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "reading_id": {
            "type": "string"
          },
          "requested_at": {
            "format": "date-time",
            "type": "string"
          },
          "requested_by": {
            "type": "string"
          },
          "schedule_id": {
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "requested",
              "assigned",
              "acquired",
              "failed",
              "expired"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "source_id",
          "requested_by",
          "idempotency_key",
          "status",
          "requested_at",
          "due_at",
          "attempt_count",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ReadingRequestInput": {
        "properties": {
          "due_at": {
            "format": "date-time",
            "type": "string"
          },
          "idempotency_key": {
            "maxLength": 160,
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "source_id": {
            "type": "string"
          }
        },
        "required": [
          "meter_id",
          "source_id",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ReadingRound": {
        "properties": {
          "cancelled_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "completed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "cycle_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "opened_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "route_id": {
            "type": "string"
          },
          "scheduled_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "planned",
              "open",
              "in_progress",
              "completed",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "route_id",
          "cycle_id",
          "scheduled_at",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ReadingRoute": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "meter_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "service_area_id",
          "name",
          "status",
          "meter_ids",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ReadingSchedule": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "interval_seconds": {
            "maximum": 31536000,
            "minimum": 60,
            "type": "integer"
          },
          "last_requested_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "next_run_at": {
            "format": "date-time",
            "type": "string"
          },
          "source_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "active",
              "paused"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "meter_id",
          "source_id",
          "interval_seconds",
          "next_run_at",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ReadingScheduleInput": {
        "properties": {
          "interval_seconds": {
            "maximum": 31536000,
            "minimum": 60,
            "type": "integer"
          },
          "meter_id": {
            "type": "string"
          },
          "next_run_at": {
            "format": "date-time",
            "type": "string"
          },
          "source_id": {
            "type": "string"
          }
        },
        "required": [
          "meter_id",
          "source_id",
          "interval_seconds"
        ],
        "type": "object"
      },
      "ReadingSubmission": {
        "properties": {
          "assignment_id": {
            "description": "Optional in-progress assignment that authorizes this field reading and supplies route/cycle provenance.",
            "type": "string"
          },
          "client_reading_id": {
            "type": "string"
          },
          "estimate_reason": {
            "type": "string"
          },
          "evidence_ids": {
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "type": "array"
          },
          "idempotency_key": {
            "type": "string"
          },
          "measured_at": {
            "format": "date-time",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          }
        },
        "required": [
          "meter_id",
          "value",
          "unit",
          "measured_at",
          "client_reading_id",
          "idempotency_key"
        ],
        "type": "object"
      },
      "ReasonRequest": {
        "properties": {
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "type": "object"
      },
      "Receivable": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "ageing_bucket": {
            "enum": [
              "current",
              "1_30",
              "31_60",
              "61_90",
              "over_90"
            ],
            "type": "string"
          },
          "balance_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "days_overdue": {
            "type": "integer"
          },
          "due_date": {
            "format": "date-time",
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "invoice_number": {
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "open",
              "partially_paid"
            ],
            "type": "string"
          },
          "total_cents": {
            "type": "integer"
          }
        },
        "required": [
          "invoice_id",
          "invoice_number",
          "customer_id",
          "account_id",
          "balance_cents",
          "total_cents",
          "currency",
          "status",
          "due_date",
          "issued_at",
          "days_overdue",
          "ageing_bucket"
        ],
        "type": "object"
      },
      "ReconcileConsumptionResult": {
        "properties": {
          "adjustment": {
            "$ref": "#/components/schemas/BillingAdjustment"
          },
          "delta_cents": {
            "type": "integer"
          },
          "invoice": {
            "$ref": "#/components/schemas/BillingInvoice"
          }
        },
        "required": [
          "invoice",
          "delta_cents"
        ],
        "type": "object"
      },
      "RecordedPayment": {
        "additionalProperties": true,
        "description": "A recorded payment. Account and customer references carry the holder's name so a row can be told apart without another lookup.",
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "amount_cents": {
            "type": "integer"
          },
          "currency": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "paid_at": {
            "format": "date-time",
            "type": "string"
          },
          "receipt_number": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "RecordedPaymentPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/RecordedPayment"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "RedirectAction": {
        "properties": {
          "type": {
            "const": "redirect"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "required": [
          "type",
          "url"
        ],
        "type": "object"
      },
      "RefreshRequest": {
        "properties": {
          "refresh_token": {
            "type": "string"
          }
        },
        "required": [
          "refresh_token"
        ],
        "type": "object"
      },
      "ReleaseInventoryReservationRequest": {
        "properties": {
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "reason"
        ],
        "type": "object"
      },
      "RemoteReadingBatch": {
        "properties": {
          "events": {
            "items": {
              "$ref": "#/components/schemas/RemoteReadingSubmission"
            },
            "maxItems": 500,
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "events"
        ],
        "type": "object"
      },
      "RemoteReadingSubmission": {
        "properties": {
          "event_id": {
            "maxLength": 160,
            "type": "string"
          },
          "evidence_ids": {
            "items": {
              "type": "string"
            },
            "maxItems": 20,
            "type": "array"
          },
          "measured_at": {
            "format": "date-time",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "request_id": {
            "description": "Optional leased request fulfilled by this event.",
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "pattern": "^\\d+(\\.\\d+)?$",
            "type": "string"
          }
        },
        "required": [
          "meter_id",
          "event_id",
          "value",
          "unit",
          "measured_at"
        ],
        "type": "object"
      },
      "ReportExecution": {
        "properties": {
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "definition_id": {
            "type": "string"
          },
          "download_url": {
            "type": "string"
          },
          "error_message": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "locale": {
            "description": "The requester's language, captured when the export is queued. The CSV download and the PDF label columns and enum values in it. Absent for API keys and system runs, whose CSV keeps the snake_case column keys and raw values.",
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "parameters": {
            "additionalProperties": true,
            "type": "object"
          },
          "row_count": {
            "type": "integer"
          },
          "started_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "pending",
              "running",
              "completed",
              "failed"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "triggered_by": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "definition_id",
          "status",
          "parameters",
          "row_count",
          "created_at"
        ],
        "type": "object"
      },
      "ReportExecutionPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ReportExecution"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "RequestInformation": {
        "properties": {
          "requests": {
            "items": {
              "properties": {
                "message": {
                  "type": "string"
                },
                "requirement": {
                  "type": "string"
                }
              },
              "required": [
                "requirement",
                "message"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "requests"
        ],
        "type": "object"
      },
      "ResetPasswordRequest": {
        "properties": {
          "code": {
            "type": "string"
          },
          "identifier": {
            "type": "string"
          },
          "new_password": {
            "maxLength": 128,
            "minLength": 8,
            "type": "string"
          }
        },
        "required": [
          "identifier",
          "code",
          "new_password"
        ],
        "type": "object"
      },
      "ResolveRunExceptionRequest": {
        "properties": {
          "resolution_note": {
            "type": "string"
          },
          "status": {
            "enum": [
              "resolved",
              "dismissed"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "RetentionClass": {
        "properties": {
          "class": {
            "enum": [
              "audit_logs",
              "readings",
              "invoices",
              "sessions"
            ],
            "type": "string"
          },
          "expired_before": {
            "format": "date-time",
            "type": "string"
          },
          "expired_count": {
            "type": "integer"
          },
          "is_default": {
            "type": "boolean"
          },
          "marked_at": {
            "format": "date-time",
            "type": "string"
          },
          "retention_days": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "RetentionList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/RetentionClass"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "RetentionUpdate": {
        "properties": {
          "classes": {
            "items": {
              "properties": {
                "class": {
                  "type": "string"
                },
                "retention_days": {
                  "type": "integer"
                }
              },
              "required": [
                "class",
                "retention_days"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "classes"
        ],
        "type": "object"
      },
      "ReviewConnectionRequest": {
        "properties": {
          "approved": {
            "type": "boolean"
          },
          "currency": {
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "estimated_cost_cents": {
            "format": "int64",
            "type": "integer"
          },
          "notes": {
            "type": "string"
          },
          "rejection_reason": {
            "type": "string"
          }
        },
        "required": [
          "approved"
        ],
        "type": "object"
      },
      "RevokedCount": {
        "properties": {
          "revoked": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "RoleCatalog": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/RoleDefinition"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "RoleDefinition": {
        "properties": {
          "context": {
            "enum": [
              "platform",
              "tenant",
              "consumer"
            ],
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "scopes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "name",
          "context",
          "description",
          "scopes"
        ],
        "type": "object"
      },
      "RunException": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "detail": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "reason": {
            "enum": [
              "already_billed",
              "no_consumption",
              "no_reading",
              "no_consumption_history",
              "reading_under_review",
              "no_active_tariff",
              "account_resolution_failed",
              "billing_failed",
              "reconciliation_credit_exceeds_bill"
            ],
            "type": "string"
          },
          "run_id": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "run_id",
          "account_id",
          "reason",
          "created_at"
        ],
        "type": "object"
      },
      "RunExceptionPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/RunException"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          },
          "total_count": {
            "type": "integer"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "SCIMEmail": {
        "properties": {
          "primary": {
            "type": "boolean"
          },
          "type": {
            "type": "string"
          },
          "value": {
            "format": "email",
            "type": "string"
          }
        },
        "required": [
          "value"
        ],
        "type": "object"
      },
      "SCIMError": {
        "properties": {
          "detail": {
            "type": "string"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "scimType": {
            "type": "string"
          },
          "status": {
            "type": "string"
          }
        },
        "required": [
          "schemas",
          "status",
          "detail"
        ],
        "type": "object"
      },
      "SCIMListResponse": {
        "properties": {
          "Resources": {
            "items": {
              "$ref": "#/components/schemas/SCIMUser"
            },
            "type": "array"
          },
          "itemsPerPage": {
            "minimum": 0,
            "type": "integer"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "startIndex": {
            "minimum": 1,
            "type": "integer"
          },
          "totalResults": {
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "schemas",
          "totalResults",
          "startIndex",
          "itemsPerPage",
          "Resources"
        ],
        "type": "object"
      },
      "SCIMMeta": {
        "properties": {
          "created": {
            "format": "date-time",
            "type": "string"
          },
          "lastModified": {
            "format": "date-time",
            "type": "string"
          },
          "location": {
            "format": "uri-reference",
            "type": "string"
          },
          "resourceType": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SCIMName": {
        "properties": {
          "familyName": {
            "type": "string"
          },
          "formatted": {
            "type": "string"
          },
          "givenName": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SCIMPatchRequest": {
        "properties": {
          "Operations": {
            "items": {
              "properties": {
                "op": {
                  "enum": [
                    "add",
                    "replace",
                    "remove"
                  ],
                  "type": "string"
                },
                "path": {
                  "type": "string"
                },
                "value": {}
              },
              "required": [
                "op"
              ],
              "type": "object"
            },
            "minItems": 1,
            "type": "array"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "schemas",
          "Operations"
        ],
        "type": "object"
      },
      "SCIMResourceTypeList": {
        "properties": {
          "Resources": {
            "items": {
              "properties": {
                "endpoint": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "meta": {
                  "$ref": "#/components/schemas/SCIMMeta"
                },
                "name": {
                  "type": "string"
                },
                "schema": {
                  "type": "string"
                },
                "schemas": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "itemsPerPage": {
            "type": "integer"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "startIndex": {
            "type": "integer"
          },
          "totalResults": {
            "type": "integer"
          }
        },
        "required": [
          "schemas",
          "totalResults",
          "startIndex",
          "itemsPerPage",
          "Resources"
        ],
        "type": "object"
      },
      "SCIMSchemaList": {
        "properties": {
          "Resources": {
            "items": {
              "properties": {
                "attributes": {
                  "items": {
                    "type": "object"
                  },
                  "type": "array"
                },
                "description": {
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "meta": {
                  "$ref": "#/components/schemas/SCIMMeta"
                },
                "name": {
                  "type": "string"
                },
                "schemas": {
                  "items": {
                    "type": "string"
                  },
                  "type": "array"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "itemsPerPage": {
            "type": "integer"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "startIndex": {
            "type": "integer"
          },
          "totalResults": {
            "type": "integer"
          }
        },
        "required": [
          "schemas",
          "totalResults",
          "startIndex",
          "itemsPerPage",
          "Resources"
        ],
        "type": "object"
      },
      "SCIMServiceProviderConfig": {
        "properties": {
          "authenticationSchemes": {
            "items": {
              "properties": {
                "description": {
                  "type": "string"
                },
                "name": {
                  "type": "string"
                },
                "primary": {
                  "type": "boolean"
                },
                "specUri": {
                  "format": "uri",
                  "type": "string"
                },
                "type": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "bulk": {
            "properties": {
              "maxOperations": {
                "type": "integer"
              },
              "maxPayloadSize": {
                "type": "integer"
              },
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "changePassword": {
            "properties": {
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "etag": {
            "properties": {
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "filter": {
            "properties": {
              "maxResults": {
                "type": "integer"
              },
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "meta": {
            "$ref": "#/components/schemas/SCIMMeta"
          },
          "patch": {
            "properties": {
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "sort": {
            "properties": {
              "supported": {
                "type": "boolean"
              }
            },
            "type": "object"
          }
        },
        "required": [
          "schemas",
          "patch",
          "bulk",
          "filter",
          "changePassword",
          "sort",
          "etag",
          "authenticationSchemes",
          "meta"
        ],
        "type": "object"
      },
      "SCIMUser": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "displayName": {
            "type": "string"
          },
          "emails": {
            "items": {
              "$ref": "#/components/schemas/SCIMEmail"
            },
            "type": "array"
          },
          "externalId": {
            "type": "string"
          },
          "id": {
            "readOnly": true,
            "type": "string"
          },
          "meta": {
            "$ref": "#/components/schemas/SCIMMeta"
          },
          "name": {
            "$ref": "#/components/schemas/SCIMName"
          },
          "schemas": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "userName": {
            "minLength": 1,
            "type": "string"
          }
        },
        "required": [
          "userName"
        ],
        "type": "object"
      },
      "SandboxAdvanceResult": {
        "properties": {
          "advanced_payments": {
            "description": "Simulated payment sessions moved by this call; empty when none were pending.",
            "items": {
              "properties": {
                "invoice_id": {
                  "description": "Invoice the session pays, when it pays one.",
                  "type": "string"
                },
                "reference": {
                  "description": "Reference of the simulated payment session.",
                  "type": "string"
                },
                "status": {
                  "enum": [
                    "confirmed",
                    "failed",
                    "expired"
                  ],
                  "type": "string"
                },
                "transaction_id": {
                  "description": "Simulated transaction reference, set when confirmed.",
                  "type": "string"
                }
              },
              "required": [
                "reference",
                "status"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "generated_readings": {
            "description": "Meter readings generated; 0 unless readings was true.",
            "minimum": 0,
            "type": "integer"
          }
        },
        "required": [
          "advanced_payments",
          "generated_readings"
        ],
        "type": "object"
      },
      "SearchResponse": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/SearchResult"
            },
            "type": "array"
          },
          "partial": {
            "description": "True when at least one source failed and its results are missing.",
            "type": "boolean"
          },
          "query": {
            "description": "The trimmed search text.",
            "type": "string"
          }
        },
        "required": [
          "data",
          "query",
          "partial"
        ],
        "type": "object"
      },
      "SearchResult": {
        "properties": {
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "subtitle": {
            "description": "One line of context.",
            "type": "string"
          },
          "title": {
            "description": "What a person recognises, such as a name, invoice number or serial.",
            "type": "string"
          },
          "type": {
            "enum": [
              "customer",
              "account",
              "property",
              "meter",
              "connection",
              "invoice",
              "payment",
              "ticket",
              "work_order",
              "incident",
              "reading_route",
              "organization",
              "subscription"
            ],
            "type": "string"
          }
        },
        "required": [
          "type",
          "id",
          "title",
          "subtitle",
          "status"
        ],
        "type": "object"
      },
      "SecurityPolicy": {
        "properties": {
          "allowed_ip_ranges": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "client_ip": {
            "description": "The client address the server sees",
            "type": "string"
          },
          "enforce_2fa": {
            "type": "boolean"
          },
          "enforce_ip_on_platform_staff": {
            "type": "boolean"
          },
          "idle_timeout_minutes": {
            "description": "0 turns the idle timeout off",
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "updated_by": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SecurityPolicyUpdate": {
        "properties": {
          "allowed_ip_ranges": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "confirm_lockout": {
            "description": "Save a policy that excludes the caller's current address",
            "type": "boolean"
          },
          "enforce_2fa": {
            "type": "boolean"
          },
          "enforce_ip_on_platform_staff": {
            "type": "boolean"
          },
          "idle_timeout_minutes": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "Sensor": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "asset_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "device_id": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "flow",
              "pressure",
              "level",
              "quality"
            ],
            "type": "string"
          },
          "location": {
            "enum": [
              "abstraction_point",
              "treatment_plant",
              "reservoir",
              "distribution"
            ],
            "type": "string"
          },
          "metric": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SensorList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Sensor"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SeriesPoint": {
        "properties": {
          "date": {
            "format": "date",
            "type": "string"
          },
          "value": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "ServiceArea": {
        "properties": {
          "id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "name",
          "status"
        ],
        "type": "object"
      },
      "ServiceAreaPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ServiceArea"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "ServiceIndicatorReport": {
        "properties": {
          "indicators": {
            "items": {
              "properties": {
                "coverage": {
                  "type": "string"
                },
                "denominator": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "formula": {
                  "type": "string"
                },
                "key": {
                  "enum": [
                    "continuity_of_service",
                    "collection_efficiency",
                    "billing_efficiency",
                    "water_quality_compliance",
                    "staff_per_1000_connections"
                  ],
                  "type": "string"
                },
                "label": {
                  "type": "string"
                },
                "numerator": {
                  "type": [
                    "number",
                    "null"
                  ]
                },
                "reason": {
                  "type": "string"
                },
                "status": {
                  "enum": [
                    "ok",
                    "insufficient_data"
                  ],
                  "type": "string"
                },
                "unit": {
                  "type": "string"
                },
                "value": {
                  "type": [
                    "number",
                    "null"
                  ]
                }
              },
              "required": [
                "key",
                "label",
                "unit",
                "status",
                "value",
                "formula",
                "numerator",
                "denominator",
                "coverage"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "period_end": {
            "format": "date-time",
            "type": "string"
          },
          "period_start": {
            "format": "date-time",
            "type": "string"
          },
          "quarter": {
            "type": "integer"
          },
          "year": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "ServiceQuote": {
        "properties": {
          "accepted_at": {
            "format": "date-time",
            "type": "string"
          },
          "automatic": {
            "description": "Priced at once from the tariff without staff",
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "decline_note": {
            "type": "string"
          },
          "declined_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "pattern": "^sqt_",
            "type": "string"
          },
          "invoice_id": {
            "type": "string"
          },
          "invoice_number": {
            "type": "string"
          },
          "issued_at": {
            "format": "date-time",
            "type": "string"
          },
          "issued_by": {
            "type": "string"
          },
          "lines": {
            "items": {
              "$ref": "#/components/schemas/ServiceQuoteLine"
            },
            "type": "array"
          },
          "notes": {
            "type": "string"
          },
          "paid_at": {
            "format": "date-time",
            "type": "string"
          },
          "payment_id": {
            "type": "string"
          },
          "receipt_number": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "site_visit_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "issued",
              "accepted",
              "declined",
              "superseded",
              "expired",
              "paid",
              "cancelled"
            ],
            "type": "string"
          },
          "subtotal_cents": {
            "format": "int64",
            "type": "integer"
          },
          "tariff_version_id": {
            "type": "string"
          },
          "tax_cents": {
            "format": "int64",
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "total_cents": {
            "format": "int64",
            "type": "integer"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "valid_until": {
            "description": "Last day the quote can be accepted",
            "format": "date-time",
            "type": "string"
          },
          "version": {
            "type": "integer"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "request_id",
          "version",
          "status",
          "automatic",
          "lines",
          "subtotal_cents",
          "tax_cents",
          "total_cents",
          "currency",
          "valid_until",
          "issued_at"
        ],
        "type": "object"
      },
      "ServiceQuoteLine": {
        "properties": {
          "adjustment_reason": {
            "type": "string"
          },
          "charge_code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "pattern": "^sqi_",
            "type": "string"
          },
          "kind": {
            "enum": [
              "connection_fee",
              "material",
              "labour",
              "other"
            ],
            "type": "string"
          },
          "list_price_cents": {
            "description": "The tariff's unit price when the line came from it",
            "format": "int64",
            "type": "integer"
          },
          "position": {
            "type": "integer"
          },
          "quantity": {
            "type": "number"
          },
          "tax_cents": {
            "format": "int64",
            "type": "integer"
          },
          "taxable": {
            "type": "boolean"
          },
          "total_cents": {
            "before tax": null,
            "description": "Quantity times unit price",
            "format": "int64",
            "type": "integer"
          },
          "unit_price_cents": {
            "format": "int64",
            "type": "integer"
          }
        },
        "required": [
          "id",
          "position",
          "kind",
          "description",
          "quantity",
          "unit_price_cents",
          "taxable",
          "total_cents",
          "tax_cents"
        ],
        "type": "object"
      },
      "ServiceQuoteList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ServiceQuote"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "ServiceRequest": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "description": "Account the connection was installed on; the requester is linked to it",
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "can_book_visit": {
            "description": "The requester may book a site visit from the offered days",
            "type": "boolean"
          },
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "connection_holder_name": {
            "description": "Display name of the customer who holds the referenced connection. Omitted when unknown.",
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "connection_status": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "decided_at": {
            "format": "date-time",
            "type": "string"
          },
          "decided_by": {
            "type": "string"
          },
          "decline_note": {
            "type": "string"
          },
          "decline_reason": {
            "description": "Code from the tenant's configured decline reasons",
            "type": "string"
          },
          "decline_reason_label": {
            "description": "The tenant's wording of the reason when it was chosen",
            "type": "string"
          },
          "estimate_max_cents": {
            "format": "int64",
            "type": "integer"
          },
          "estimate_min_cents": {
            "format": "int64",
            "type": "integer"
          },
          "full_name": {
            "type": "string"
          },
          "id": {
            "pattern": "^sqr_",
            "type": "string"
          },
          "installation_date": {
            "format": "date",
            "type": "string"
          },
          "invoice_id": {
            "description": "Invoice the accepted quote is paid through",
            "type": "string"
          },
          "landmark": {
            "type": "string"
          },
          "locality": {
            "type": "string"
          },
          "payment_id": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "plus_code": {
            "type": "string"
          },
          "priced": {
            "type": "boolean"
          },
          "property_address": {
            "description": "Address line of the referenced property. Omitted when unknown.",
            "type": "string"
          },
          "property_holder_name": {
            "description": "Display name of the customer who holds the referenced property. Omitted when unknown.",
            "type": "string"
          },
          "property_id": {
            "type": "string"
          },
          "quote": {
            "$ref": "#/components/schemas/ServiceQuote"
          },
          "quote_id": {
            "description": "The current quote",
            "pattern": "^sqt_",
            "type": "string"
          },
          "receipt_number": {
            "type": "string"
          },
          "service_type": {
            "enum": [
              "new_connection"
            ],
            "type": "string"
          },
          "site_visit": {
            "$ref": "#/components/schemas/SiteVisit"
          },
          "site_visit_id": {
            "description": "The current site visit",
            "pattern": "^svv_",
            "type": "string"
          },
          "status": {
            "enum": [
              "submitted",
              "accepted",
              "visit_scheduled",
              "quoted",
              "payment_pending",
              "scheduled",
              "completed",
              "declined",
              "withdrawn"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "work_order_id": {
            "description": "Installation work order booked once paid",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "phone",
          "address",
          "service_type",
          "category",
          "status",
          "priced",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "ServiceRequestPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/ServiceRequest"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "Session": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "device_name": {
            "description": "Parsed label such as \"Chrome 128 on macOS\" or \"Mobile app on Android\"",
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "ip_address": {
            "type": "string"
          },
          "is_current": {
            "type": "boolean"
          },
          "last_active_at": {
            "format": "date-time",
            "type": "string"
          },
          "user_agent": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SessionList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/Session"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "SetPrepaidMeterStatusRequest": {
        "additionalProperties": false,
        "properties": {
          "status": {
            "enum": [
              "active",
              "suspended"
            ],
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "type": "object"
      },
      "SignupConsumerRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled. Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "email": {
            "description": "Required when phone is absent",
            "type": "string"
          },
          "full_name": {
            "type": "string"
          },
          "locale": {
            "default": "pt-MZ",
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "password": {
            "maxLength": 128,
            "minLength": 8,
            "type": "string"
          },
          "phone": {
            "description": "Required when email is absent",
            "type": "string"
          }
        },
        "required": [
          "full_name",
          "password"
        ],
        "type": "object"
      },
      "SignupUtilityRequest": {
        "properties": {
          "challenge_token": {
            "description": "Bot-challenge token when security.challenge is enabled. Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
            "type": "string"
          },
          "country_code": {
            "description": "ISO 3166-1 alpha-2 account country; defaults to the deployment country",
            "pattern": "^[A-Z]{2}$",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "device_fingerprint": {
            "description": "Opaque client-generated installation token used only as an account-creation abuse signal",
            "maxLength": 128,
            "type": "string"
          },
          "email": {
            "description": "Required when phone is absent",
            "type": "string"
          },
          "full_name": {
            "type": "string"
          },
          "locale": {
            "default": "pt-MZ",
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "organization_name": {
            "type": "string"
          },
          "password": {
            "maxLength": 128,
            "minLength": 8,
            "type": "string"
          },
          "phone": {
            "description": "Required when email is absent",
            "type": "string"
          },
          "tenant_name": {
            "type": "string"
          },
          "tenant_slug": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "type": {
            "description": "Account type from the deployment's configured workspace type catalogue",
            "enum": [
              "utility",
              "authority",
              "operator",
              "partner"
            ],
            "type": "string"
          },
          "utility_kind": {
            "enum": [
              "authority",
              "municipal",
              "regional",
              "national",
              "rural",
              "private",
              "industrial"
            ],
            "type": "string"
          }
        },
        "required": [
          "organization_name",
          "full_name",
          "password"
        ],
        "type": "object"
      },
      "SiteVisit": {
        "properties": {
          "booked_by": {
            "enum": [
              "consumer",
              "staff"
            ],
            "type": "string"
          },
          "cancelled_at": {
            "format": "date-time",
            "type": "string"
          },
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "pattern": "^svv_",
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "outcome": {
            "type": "string"
          },
          "quote_id": {
            "type": "string"
          },
          "request_id": {
            "type": "string"
          },
          "status": {
            "enum": [
              "scheduled",
              "completed",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "visit_date": {
            "format": "date",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "request_id",
          "status",
          "visit_date",
          "booked_by",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "StaffPrepaidVendRequest": {
        "additionalProperties": false,
        "properties": {
          "amount_cents": {
            "maximum": 100000000,
            "minimum": 1,
            "type": "integer"
          },
          "idempotency_key": {
            "minLength": 1,
            "type": "string"
          },
          "method": {
            "type": "string"
          },
          "prepaid_meter_id": {
            "pattern": "^ppm_",
            "type": "string"
          }
        },
        "required": [
          "prepaid_meter_id",
          "amount_cents",
          "idempotency_key"
        ],
        "type": "object"
      },
      "SubmeterBalanceEntry": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "consumption_m3": {
            "type": "number"
          },
          "meter_id": {
            "type": "string"
          },
          "serial_number": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Subscription": {
        "properties": {
          "cancel_at_period_end": {
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "current_period_end": {
            "format": "date-time",
            "type": "string"
          },
          "current_period_start": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "type": "object"
      },
      "SubscriptionUsage": {
        "properties": {
          "active_connections": {
            "description": "Connections in status active",
            "example": 87,
            "type": "integer"
          },
          "max_connections": {
            "description": "Plan limit; 0 means none",
            "example": 100,
            "type": "integer"
          },
          "max_users": {
            "description": "Plan limit; 0 means none",
            "example": 0,
            "type": "integer"
          },
          "plan_code": {
            "example": "C100",
            "type": "string"
          },
          "users": {
            "description": "Active team members",
            "example": 3,
            "type": "integer"
          }
        },
        "required": [
          "plan_code",
          "active_connections",
          "max_connections",
          "users",
          "max_users"
        ],
        "type": "object"
      },
      "SupplyInterruption": {
        "properties": {
          "affected_customers_est": {
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "end_time": {
            "format": "date-time",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "interruption_type": {
            "enum": [
              "maintenance",
              "emergency",
              "rationing"
            ],
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "start_time": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "planned",
              "active",
              "completed",
              "cancelled"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "title": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "title",
          "interruption_type",
          "status",
          "service_area_id",
          "start_time",
          "end_time",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "SupplyInterruptionPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/SupplyInterruption"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "SupportTicket": {
        "additionalProperties": true,
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "category": {
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "subject": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "SupportTicketPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/SupportTicket"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "SwitchContextRequest": {
        "properties": {
          "context_id": {
            "type": "string"
          },
          "refresh_token": {
            "description": "Current refresh token to close when switching",
            "type": "string"
          }
        },
        "required": [
          "context_id"
        ],
        "type": "object"
      },
      "SystemInfo": {
        "properties": {
          "account_types": {
            "description": "Account types enabled for self-service workspace creation.",
            "items": {
              "enum": [
                "utility",
                "authority",
                "operator",
                "partner"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "build_date": {
            "type": "string"
          },
          "country_codes": {
            "description": "Countries configured for new account creation, sorted by code.",
            "items": {
              "pattern": "^[A-Z]{2}$",
              "type": "string"
            },
            "type": "array"
          },
          "default_country": {
            "description": "ISO 3166-1 alpha-2 deployment country.",
            "examples": [
              "MZ"
            ],
            "type": "string"
          },
          "default_currency": {
            "description": "ISO 4217 utility currency.",
            "examples": [
              "MZN"
            ],
            "type": "string"
          },
          "default_locale": {
            "description": "BCP 47 locale tag.",
            "examples": [
              "pt-MZ"
            ],
            "type": "string"
          },
          "default_timezone": {
            "examples": [
              "Africa/Maputo"
            ],
            "type": "string"
          },
          "git_commit": {
            "type": "string"
          },
          "platform": {
            "const": "Gota Water Supply Management System",
            "description": "The distribution's product name and tagline.",
            "type": "string"
          },
          "status": {
            "enum": [
              "implementation_in_progress",
              "operational"
            ],
            "type": "string"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "platform",
          "version",
          "default_country",
          "country_codes",
          "account_types",
          "default_currency",
          "default_locale",
          "default_timezone",
          "status"
        ],
        "type": "object"
      },
      "TariffTemplateApply": {
        "properties": {
          "activate": {
            "type": "boolean"
          },
          "code": {
            "maxLength": 64,
            "type": "string"
          },
          "effective_from": {
            "format": "date-time",
            "type": "string"
          },
          "name": {
            "maxLength": 200,
            "type": "string"
          }
        },
        "type": "object"
      },
      "TariffTemplateCatalogue": {
        "properties": {
          "available": {
            "type": "boolean"
          },
          "country_code": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "reason": {
            "enum": [
              "no_template_for_country",
              "country_unset"
            ],
            "type": "string"
          },
          "templates": {
            "items": {
              "properties": {
                "category": {
                  "enum": [
                    "residential",
                    "commercial",
                    "industrial",
                    "institutional",
                    "government"
                  ],
                  "type": "string"
                },
                "code": {
                  "type": "string"
                },
                "currency": {
                  "type": "string"
                },
                "fixed_fee_cents": {
                  "type": "integer"
                },
                "id": {
                  "example": "mz.dom",
                  "type": "string"
                },
                "min_consumption_m3": {
                  "type": "number"
                },
                "name": {
                  "type": "string"
                },
                "sanitation_surcharge_percent": {
                  "type": "number"
                },
                "tax_percent": {
                  "type": "number"
                },
                "tiers": {
                  "items": {
                    "properties": {
                      "max_m3": {
                        "description": "0 means no upper bound",
                        "type": "number"
                      },
                      "min_m3": {
                        "type": "number"
                      },
                      "rate_per_m3_cents": {
                        "type": "integer"
                      }
                    },
                    "type": "object"
                  },
                  "type": "array"
                }
              },
              "required": [
                "id",
                "code",
                "name",
                "category",
                "currency",
                "fixed_fee_cents",
                "min_consumption_m3",
                "sanitation_surcharge_percent",
                "tax_percent",
                "tiers"
              ],
              "type": "object"
            },
            "type": "array"
          }
        },
        "required": [
          "country_code",
          "available",
          "templates"
        ],
        "type": "object"
      },
      "TeamInvitation": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "dev_code": {
            "description": "Invitation token echoed only in development mode",
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "full_name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "roles": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "enum": [
              "pending",
              "accepted",
              "revoked",
              "expired"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "roles",
          "status",
          "expires_at",
          "created_at"
        ],
        "type": "object"
      },
      "TeamInvitationPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/TeamInvitation"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "TeamMember": {
        "properties": {
          "id": {
            "type": "string"
          },
          "joined_at": {
            "format": "date-time",
            "type": "string"
          },
          "roles": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "status": {
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserProfile"
          }
        },
        "required": [
          "id",
          "user",
          "roles",
          "status",
          "joined_at"
        ],
        "type": "object"
      },
      "TeamMemberPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/TeamMember"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "TemporalFact": {
        "properties": {
          "created_by_user_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "reason": {
            "type": "string"
          },
          "subject_id": {
            "type": "string"
          },
          "superseded_by_user_id": {
            "type": "string"
          },
          "system_created_at": {
            "format": "date-time",
            "type": "string"
          },
          "system_superseded_at": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "valid_from": {
            "format": "date-time",
            "type": "string"
          },
          "valid_to": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "value_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "Tenant": {
        "properties": {
          "closed_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "copied_from_tenant_id": {
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "deletion_due_at": {
            "format": "date-time",
            "type": [
              "string",
              "null"
            ]
          },
          "id": {
            "type": "string"
          },
          "kind": {
            "enum": [
              "live",
              "sandbox"
            ],
            "type": "string"
          },
          "locale": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "owner_organization_id": {
            "type": "string"
          },
          "parent_tenant_id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "enum": [
              "provisioning",
              "active",
              "suspended",
              "closed"
            ],
            "type": "string"
          },
          "template_key": {
            "type": "string"
          },
          "timezone": {
            "type": "string"
          },
          "workspace_state": {
            "enum": [
              "sandbox_only",
              "unverified",
              "verifying",
              "live",
              "restricted",
              "suspended",
              "closed",
              "sandbox"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "owner_organization_id",
          "slug",
          "name",
          "status",
          "kind",
          "workspace_state",
          "locale",
          "currency",
          "timezone"
        ],
        "type": "object"
      },
      "TenantBranding": {
        "allOf": [
          {
            "$ref": "#/components/schemas/Branding"
          },
          {
            "properties": {
              "platform": {
                "properties": {
                  "icon_url": {
                    "type": [
                      "string",
                      "null"
                    ]
                  },
                  "name": {
                    "type": "string"
                  },
                  "short_name": {
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "short_name",
                  "icon_url"
                ],
                "type": "object"
              },
              "receipt_footer": {
                "type": "string"
              },
              "tenant": {
                "properties": {
                  "id": {
                    "type": "string"
                  },
                  "slug": {
                    "type": "string"
                  }
                },
                "required": [
                  "id",
                  "slug"
                ],
                "type": "object"
              }
            },
            "required": [
              "receipt_footer",
              "tenant",
              "platform"
            ],
            "type": "object"
          }
        ]
      },
      "TenantBrandingAdmin": {
        "allOf": [
          {
            "$ref": "#/components/schemas/TenantBranding"
          },
          {
            "properties": {
              "sources": {
                "additionalProperties": {
                  "$ref": "#/components/schemas/TenantBrandingSource"
                },
                "description": "The platform source keys plus receipt_footer.",
                "type": "object"
              }
            },
            "required": [
              "sources"
            ],
            "type": "object"
          }
        ]
      },
      "TenantBrandingPatch": {
        "allOf": [
          {
            "$ref": "#/components/schemas/BrandingPatch"
          },
          {
            "properties": {
              "receipt_footer": {
                "maxLength": 300,
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "type": "object"
          }
        ]
      },
      "TenantBrandingSource": {
        "description": "Where a value comes from. Files (logo, logo_dark, icon) are only custom, configured or none: a utility never inherits the platform's files, which may show the platform's name.",
        "enum": [
          "custom",
          "configured",
          "profile",
          "platform",
          "none"
        ],
        "type": "string"
      },
      "TenantUsage": {
        "properties": {
          "connections": {
            "description": "Connections in status active",
            "format": "int64",
            "type": "integer"
          },
          "customers": {
            "format": "int64",
            "type": "integer"
          },
          "max_connections": {
            "description": "Plan limit; 0 means none",
            "type": "integer"
          },
          "max_users": {
            "description": "Plan limit; 0 means none",
            "type": "integer"
          },
          "meters": {
            "format": "int64",
            "type": "integer"
          },
          "plan_id": {
            "type": "string"
          },
          "plan_name": {
            "type": "string"
          },
          "subscription_status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "users": {
            "description": "Active team members",
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "TopologyLink": {
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "from_node_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "length_meters": {
            "type": "number"
          },
          "link_code": {
            "type": "string"
          },
          "link_type": {
            "$ref": "#/components/schemas/LinkType"
          },
          "roughness_coefficient": {
            "default 130": null,
            "description": "Hazen-Williams C",
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/LinkStatus"
          },
          "tenant_id": {
            "type": "string"
          },
          "to_node_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "link_code",
          "from_node_id",
          "to_node_id",
          "link_type",
          "length_meters",
          "diameter_mm",
          "roughness_coefficient",
          "status",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "TopologyNode": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "device_id": {
            "description": "Level or flow device reporting measurements",
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "elevation_meters": {
            "type": "number"
          },
          "id": {
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "description": "Customer meter attributed to a customer_tap",
            "type": "string"
          },
          "meter_serial": {
            "description": "Serial number of the referenced meter. Omitted when unknown.",
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "node_code": {
            "type": "string"
          },
          "node_type": {
            "$ref": "#/components/schemas/NodeType"
          },
          "service_area_id": {
            "type": "string"
          },
          "storage_capacity_m3": {
            "format": "int64",
            "type": "integer"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "node_code",
          "name",
          "node_type",
          "elevation_meters",
          "storage_capacity_m3",
          "latitude",
          "longitude",
          "active",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "TraceResult": {
        "properties": {
          "direction": {
            "enum": [
              "upstream",
              "downstream"
            ],
            "type": "string"
          },
          "include_closed": {
            "type": "boolean"
          },
          "links": {
            "items": {
              "$ref": "#/components/schemas/TopologyLink"
            },
            "type": "array"
          },
          "nodes": {
            "items": {
              "allOf": [
                {
                  "$ref": "#/components/schemas/TopologyNode"
                },
                {
                  "properties": {
                    "depth": {
                      "type": "integer"
                    }
                  },
                  "type": "object"
                }
              ]
            },
            "type": "array"
          },
          "start_node_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TwoFactorChallengeRequest": {
        "properties": {
          "challenge_token": {
            "type": "string"
          },
          "code": {
            "description": "A 6-digit TOTP code or a recovery code XXXX-XXXX-XXXX",
            "type": "string"
          }
        },
        "required": [
          "challenge_token",
          "code"
        ],
        "type": "object"
      },
      "TwoFactorCodeRequest": {
        "properties": {
          "code": {
            "type": "string"
          }
        },
        "required": [
          "code"
        ],
        "type": "object"
      },
      "TwoFactorConfirmation": {
        "properties": {
          "enabled": {
            "type": "boolean"
          },
          "recovery_codes": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "type": "object"
      },
      "TwoFactorDisableRequest": {
        "properties": {
          "code": {
            "type": "string"
          },
          "password": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TwoFactorEnrollment": {
        "properties": {
          "otpauth_uri": {
            "type": "string"
          },
          "secret_masked": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "TwoFactorStatus": {
        "properties": {
          "confirmed_at": {
            "format": "date-time",
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "pending": {
            "type": "boolean"
          },
          "recovery_codes_remaining": {
            "type": "integer"
          },
          "required_by_policy": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "UpdateAssetRequest": {
        "properties": {
          "capacity": {
            "type": "number"
          },
          "elevation": {
            "type": "number"
          },
          "installation_date": {
            "format": "date-time",
            "type": "string"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "name": {
            "type": "string"
          },
          "properties": {
            "additionalProperties": true,
            "type": "object"
          },
          "status": {
            "$ref": "#/components/schemas/AssetStatus"
          }
        },
        "type": "object"
      },
      "UpdateConnectionRequest": {
        "properties": {
          "account_id": {
            "type": "string"
          },
          "gps_coordinates": {
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "pipe_diameter_mm": {
            "type": "integer"
          },
          "pipe_material": {
            "type": "string"
          },
          "pressure_zone_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateConsumerOnboarding": {
        "properties": {
          "notification_consent": {
            "type": "boolean"
          },
          "profile": {
            "properties": {
              "email": {
                "type": "string"
              },
              "full_name": {
                "type": "string"
              },
              "preferred_language": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "terms": {
            "properties": {
              "accepted": {
                "type": "boolean"
              },
              "version": {
                "type": "string"
              }
            },
            "required": [
              "accepted",
              "version"
            ],
            "type": "object"
          }
        },
        "type": "object"
      },
      "UpdateDMARequest": {
        "properties": {
          "inflow_meter_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "outflow_meter_id": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "target_pressure_bar": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "UpdateDeveloperWebhook": {
        "properties": {
          "description": {
            "maxLength": 512,
            "type": "string"
          },
          "enabled": {
            "type": "boolean"
          },
          "events": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "url": {
            "format": "uri",
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateInventoryItemRequest": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          },
          "meter_diameter_mm": {
            "type": "integer"
          },
          "meter_manufacturer": {
            "type": "string"
          },
          "meter_model": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "reorder_level": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reorder_levels": {
            "description": "Replaces every per-location override.",
            "items": {
              "$ref": "#/components/schemas/InventoryReorderLevel"
            },
            "type": "array"
          },
          "standard_cost_minor": {
            "format": "int64",
            "minimum": 0,
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UpdateInventoryKitRequest": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "description": {
            "type": "string"
          },
          "lines": {
            "description": "Replaces the kit's lines.",
            "items": {
              "$ref": "#/components/schemas/InventoryKitLine"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "work_order_type": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateInventoryLocationRequest": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "allow_negative": {
            "type": "boolean"
          },
          "crew_id": {
            "type": "string"
          },
          "member_user_ids": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "name": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateLinkRequest": {
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "length_meters": {
            "type": "number"
          },
          "link_type": {
            "$ref": "#/components/schemas/LinkType"
          },
          "roughness_coefficient": {
            "type": "integer"
          },
          "status": {
            "$ref": "#/components/schemas/LinkStatus"
          }
        },
        "type": "object"
      },
      "UpdateNodeRequest": {
        "properties": {
          "active": {
            "type": "boolean"
          },
          "device_id": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "elevation_meters": {
            "type": "number"
          },
          "latitude": {
            "type": "number"
          },
          "longitude": {
            "type": "number"
          },
          "meter_id": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "storage_capacity_m3": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UpdateOnboarding": {
        "description": "Each section is optional; a field set to an empty string is cleared.",
        "properties": {
          "business_profile": {
            "properties": {
              "address": {
                "type": "string"
              },
              "legal_name": {
                "type": "string"
              },
              "licence_reference": {
                "type": "string"
              },
              "nuit": {
                "description": "Nine-digit Mozambican NUIT including the Modulo 11 check digit",
                "pattern": "^[0-9]{9}$",
                "type": "string"
              },
              "phone": {
                "type": "string"
              },
              "registration_number": {
                "type": "string"
              },
              "support_contact": {
                "description": "E-mail or phone",
                "type": "string"
              },
              "trading_name": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "collection_channel_types": {
            "description": "The channel types the server accepts; configuration forms offer these.",
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "collection_channels": {
            "items": {
              "properties": {
                "reference": {
                  "type": "string"
                },
                "type": {
                  "description": "One of collection_channel_types.",
                  "type": "string"
                }
              },
              "required": [
                "type",
                "reference"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "representative": {
            "properties": {
              "contact": {
                "type": "string"
              },
              "date_of_birth": {
                "format": "date",
                "type": "string"
              },
              "id_document_number": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "role": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "settlement_account": {
            "properties": {
              "account_holder": {
                "type": "string"
              },
              "account_number": {
                "description": "21-digit NIB or IBAN; returned masked",
                "type": "string"
              },
              "bank": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "terms": {
            "properties": {
              "accepted": {
                "type": "boolean"
              },
              "version": {
                "description": "Must equal current_terms_version",
                "type": "string"
              }
            },
            "required": [
              "accepted",
              "version"
            ],
            "type": "object"
          }
        },
        "type": "object"
      },
      "UpdatePlanRequest": {
        "properties": {
          "capabilities": {
            "items": {
              "enum": [
                "configure",
                "customers",
                "meters",
                "draft_billing",
                "invoices",
                "payments",
                "messages",
                "public_profile",
                "custom_domain",
                "live_api",
                "sandbox"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "display_order": {
            "type": "integer"
          },
          "highlighted": {
            "type": "boolean"
          },
          "max_accounts": {
            "maximum": 1000,
            "minimum": 0,
            "type": "integer"
          },
          "max_connections": {
            "type": "integer"
          },
          "max_sandboxes": {
            "maximum": 50,
            "minimum": 0,
            "type": "integer"
          },
          "max_users": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "name_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "overage_connection_cents": {
            "type": "integer"
          },
          "overage_user_cents": {
            "type": "integer"
          },
          "price_cents": {
            "type": "integer"
          },
          "published": {
            "type": "boolean"
          },
          "tagline": {
            "maxLength": 255,
            "type": "string"
          },
          "tagline_i18n": {
            "$ref": "#/components/schemas/LocalizedText"
          },
          "trial_days": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UpdatePlatformContactRequest": {
        "properties": {
          "status": {
            "description": "New follow-up status (case-insensitive)",
            "enum": [
              "new",
              "contacted",
              "closed"
            ],
            "example": "contacted",
            "type": "string"
          }
        },
        "required": [
          "status"
        ],
        "type": "object"
      },
      "UpdatePlatformPlanRequest": {
        "additionalProperties": false,
        "description": "Fields to change; omitted fields keep their value.",
        "properties": {
          "capabilities": {
            "description": "Replaces the plan's capability list",
            "items": {
              "enum": [
                "configure",
                "customers",
                "meters",
                "draft_billing",
                "invoices",
                "payments",
                "messages",
                "public_profile",
                "custom_domain",
                "live_api",
                "sandbox"
              ],
              "type": "string"
            },
            "type": "array",
            "uniqueItems": true
          },
          "display_order": {
            "description": "Position in the public plan list",
            "type": "integer"
          },
          "highlighted": {
            "description": "Marks the plan as the recommended one; only one published plan can be highlighted",
            "type": "boolean"
          },
          "max_accounts": {
            "description": "Maximum accounts for the organization; 0 means no plan cap",
            "maximum": 1000,
            "minimum": 0,
            "type": "integer"
          },
          "max_connections": {
            "description": "Included service connections",
            "type": "integer"
          },
          "max_sandboxes": {
            "description": "Maximum sandboxes",
            "maximum": 50,
            "minimum": 0,
            "type": "integer"
          },
          "max_users": {
            "description": "Included team members",
            "type": "integer"
          },
          "name": {
            "description": "Display name; cannot be blank",
            "minLength": 1,
            "type": "string"
          },
          "overage_connection_cents": {
            "description": "Price per connection over the limit in a billed period",
            "format": "int64",
            "type": "integer"
          },
          "overage_user_cents": {
            "description": "Price per user over the limit in a billed period",
            "format": "int64",
            "type": "integer"
          },
          "price_cents": {
            "description": "Price per billing period in the plan currency's minor unit",
            "format": "int64",
            "type": "integer"
          },
          "published": {
            "description": "Whether the plan appears in the public plan list",
            "type": "boolean"
          },
          "tagline": {
            "description": "Short line shown under the name on the pricing page",
            "maxLength": 255,
            "type": "string"
          },
          "trial_days": {
            "description": "Trial length for new subscriptions",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UpdateProfileRequest": {
        "properties": {
          "full_name": {
            "type": "string"
          },
          "locale": {
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "UpdateTeamMemberRoles": {
        "properties": {
          "roles": {
            "items": {
              "type": "string"
            },
            "minItems": 1,
            "type": "array"
          }
        },
        "required": [
          "roles"
        ],
        "type": "object"
      },
      "UpdateUtilityBillingPolicyRequest": {
        "properties": {
          "clear_default_missing_reading": {
            "type": "boolean"
          },
          "default_due_days": {
            "minimum": 0,
            "type": "integer"
          },
          "default_missing_reading_m3": {
            "minimum": 0,
            "nullable": true,
            "type": "number"
          },
          "exclude_disputed_from_penalty": {
            "type": "boolean"
          },
          "exclude_payment_plan_from_penalty": {
            "type": "boolean"
          },
          "grace_period_days": {
            "minimum": 0,
            "type": "integer"
          },
          "late_penalty_amount_minor": {
            "format": "int64",
            "type": "integer"
          },
          "late_penalty_cap_minor": {
            "format": "int64",
            "type": "integer"
          },
          "late_penalty_compound": {
            "type": "boolean"
          },
          "late_penalty_enabled": {
            "type": "boolean"
          },
          "late_penalty_frequency": {
            "type": "string"
          },
          "late_penalty_interval_days": {
            "type": "integer"
          },
          "late_penalty_kind": {
            "type": "string"
          },
          "late_penalty_rate_basis_points": {
            "format": "int64",
            "type": "integer"
          },
          "late_penalty_taxable": {
            "type": "boolean"
          }
        },
        "type": "object"
      },
      "UpdateWorkOrderMaterialLineRequest": {
        "properties": {
          "description": {
            "type": "string"
          },
          "item_id": {
            "description": "Maps a free-text line to a catalogue item",
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "required": {
            "type": "boolean"
          },
          "source_location_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UserProfile": {
        "properties": {
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "email_verified": {
            "type": "boolean"
          },
          "full_name": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "locale": {
            "enum": [
              "pt-MZ",
              "en-US"
            ],
            "type": "string"
          },
          "phone": {
            "type": "string"
          },
          "phone_verified": {
            "type": "boolean"
          },
          "status": {
            "enum": [
              "active",
              "disabled"
            ],
            "type": "string"
          }
        },
        "required": [
          "id",
          "full_name",
          "locale",
          "status",
          "email_verified",
          "phone_verified",
          "created_at"
        ],
        "type": "object"
      },
      "UtilityBillingPolicy": {
        "properties": {
          "default_due_days": {
            "type": "integer"
          },
          "default_missing_reading_m3": {
            "description": "Default consumption in m3 used when a reading is missing and no history exists.",
            "minimum": 0,
            "nullable": true,
            "type": "number"
          },
          "exclude_disputed_from_penalty": {
            "type": "boolean"
          },
          "exclude_payment_plan_from_penalty": {
            "type": "boolean"
          },
          "grace_period_days": {
            "type": "integer"
          },
          "late_penalty_amount_minor": {
            "format": "int64",
            "type": "integer"
          },
          "late_penalty_cap_minor": {
            "format": "int64",
            "type": "integer"
          },
          "late_penalty_compound": {
            "type": "boolean"
          },
          "late_penalty_enabled": {
            "type": "boolean"
          },
          "late_penalty_frequency": {
            "type": "string"
          },
          "late_penalty_interval_days": {
            "type": "integer"
          },
          "late_penalty_kind": {
            "type": "string"
          },
          "late_penalty_rate_basis_points": {
            "format": "int64",
            "type": "integer"
          },
          "late_penalty_taxable": {
            "type": "boolean"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "version": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UtilityHandoverSummary": {
        "properties": {
          "completed": {
            "items": {
              "properties": {
                "completed_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "completed_by_name": {
                  "type": "string"
                },
                "responsibility": {
                  "enum": [
                    "platform",
                    "utility"
                  ],
                  "type": "string"
                },
                "step_id": {
                  "example": "service_areas",
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "handover": {
            "properties": {
              "accepted_at": {
                "format": "date-time",
                "type": "string"
              },
              "state": {
                "enum": [
                  "not_required",
                  "pending_owner_acceptance",
                  "accepted"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "invitation_id": {
            "type": "string"
          },
          "outstanding": {
            "example": [
              "company_details",
              "documents"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "tenant_id": {
            "type": "string"
          },
          "utility_name": {
            "type": "string"
          }
        },
        "required": [
          "invitation_id",
          "tenant_id",
          "utility_name",
          "handover",
          "completed",
          "outstanding"
        ],
        "type": "object"
      },
      "UtilityInvitation": {
        "properties": {
          "accepted_at": {
            "format": "date-time",
            "type": "string"
          },
          "contact_kind": {
            "enum": [
              "email",
              "phone"
            ],
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "deliveries": {
            "items": {
              "$ref": "#/components/schemas/UtilityInvitationDelivery"
            },
            "type": "array"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "handover": {
            "properties": {
              "accepted_at": {
                "format": "date-time",
                "type": "string"
              },
              "state": {
                "enum": [
                  "not_required",
                  "pending_owner_acceptance",
                  "accepted"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "id": {
            "example": "uinv_0123456789abcdef01234567",
            "type": "string"
          },
          "last_sent_at": {
            "format": "date-time",
            "type": "string"
          },
          "offer_id": {
            "type": "string"
          },
          "opened_at": {
            "format": "date-time",
            "type": "string"
          },
          "owner_contact": {
            "description": "Full contact; detail and create responses only",
            "type": "string"
          },
          "owner_contact_masked": {
            "example": "o****@example.com",
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "resend_count": {
            "type": "integer"
          },
          "setup_mode": {
            "enum": [
              "invite",
              "platform_managed"
            ],
            "type": "string"
          },
          "setup_steps": {
            "items": {
              "$ref": "#/components/schemas/UtilityInvitationSetupStep"
            },
            "type": "array"
          },
          "state": {
            "enum": [
              "sent",
              "opened",
              "accepted",
              "expired",
              "revoked"
            ],
            "type": "string"
          },
          "tenant_id": {
            "type": [
              "string",
              "null"
            ]
          },
          "utility_name": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "state",
          "setup_mode",
          "handover",
          "utility_name",
          "country_code",
          "owner_contact_masked",
          "expires_at",
          "created_at",
          "last_sent_at",
          "resend_count"
        ],
        "type": "object"
      },
      "UtilityInvitationAccept": {
        "additionalProperties": false,
        "properties": {
          "full_name": {
            "description": "Required for a new account",
            "type": "string"
          },
          "password": {
            "format": "password",
            "type": "string"
          },
          "token": {
            "type": "string"
          }
        },
        "required": [
          "token",
          "password"
        ],
        "type": "object"
      },
      "UtilityInvitationAcceptResult": {
        "properties": {
          "handover": {
            "properties": {
              "state": {
                "enum": [
                  "not_required",
                  "pending_owner_acceptance",
                  "accepted"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "handover_summary": {
            "$ref": "#/components/schemas/UtilityHandoverSummary"
          },
          "invitation_state": {
            "enum": [
              "accepted"
            ],
            "type": "string"
          },
          "session": {
            "additionalProperties": true,
            "description": "The owner's own session",
            "the same shape as sign-in": null,
            "type": "object"
          },
          "setup_mode": {
            "enum": [
              "invite",
              "platform_managed"
            ],
            "type": "string"
          }
        },
        "required": [
          "invitation_state",
          "setup_mode",
          "handover",
          "session"
        ],
        "type": "object"
      },
      "UtilityInvitationAcceptSession": {
        "description": "The sign-in session fields at the top level beside the invitation outcome. Through the dashboard listener the token fields are absent.",
        "properties": {
          "access_token": {
            "type": "string"
          },
          "active_context": {
            "$ref": "#/components/schemas/AuthContext"
          },
          "contexts": {
            "items": {
              "$ref": "#/components/schemas/AuthContext"
            },
            "type": "array"
          },
          "expires_in": {
            "type": "integer"
          },
          "handover": {
            "properties": {
              "state": {
                "enum": [
                  "not_required",
                  "pending_owner_acceptance",
                  "accepted"
                ],
                "type": "string"
              }
            },
            "type": "object"
          },
          "handover_summary": {
            "$ref": "#/components/schemas/UtilityHandoverSummary"
          },
          "invitation_state": {
            "enum": [
              "accepted"
            ],
            "type": "string"
          },
          "refresh_token": {
            "type": "string"
          },
          "setup_mode": {
            "enum": [
              "invite",
              "platform_managed"
            ],
            "type": "string"
          },
          "token_type": {
            "enum": [
              "Bearer"
            ],
            "type": "string"
          },
          "user": {
            "$ref": "#/components/schemas/UserProfile"
          }
        },
        "required": [
          "invitation_state",
          "setup_mode",
          "handover",
          "user",
          "active_context",
          "contexts"
        ],
        "type": "object"
      },
      "UtilityInvitationBulkResult": {
        "properties": {
          "confirmed": {
            "type": "boolean"
          },
          "dry_run_id": {
            "type": "string"
          },
          "invalid_count": {
            "type": "integer"
          },
          "rows": {
            "items": {
              "properties": {
                "country_code": {
                  "type": "string"
                },
                "created": {
                  "type": "boolean"
                },
                "errors": {
                  "items": {
                    "$ref": "#/components/schemas/UtilityInvitationFieldError"
                  },
                  "type": "array"
                },
                "invitation_id": {
                  "type": "string"
                },
                "owner_contact_masked": {
                  "type": "string"
                },
                "row": {
                  "type": "integer"
                },
                "utility_name": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "valid_count": {
            "type": "integer"
          }
        },
        "type": "object"
      },
      "UtilityInvitationConfirmRequest": {
        "additionalProperties": false,
        "properties": {
          "dry_run_id": {
            "type": "string"
          },
          "idempotency_key": {
            "maxLength": 128,
            "type": "string"
          }
        },
        "required": [
          "dry_run_id",
          "idempotency_key"
        ],
        "type": "object"
      },
      "UtilityInvitationCreate": {
        "additionalProperties": false,
        "properties": {
          "country_code": {
            "example": "MZ",
            "type": "string"
          },
          "locale": {
            "description": "Language of the message",
            "example": "pt-MZ",
            "type": "string"
          },
          "note": {
            "description": "Personal note; never written to the audit log",
            "maxLength": 1000,
            "type": "string"
          },
          "offer_id": {
            "description": "An allowed trial or credit offer ID",
            "type": "string"
          },
          "owner_contact": {
            "description": "One e-mail address or phone number",
            "example": "owner@example.com",
            "type": "string"
          },
          "plan_id": {
            "description": "A published plan code from the server",
            "type": "string"
          },
          "setup_mode": {
            "default": "invite",
            "enum": [
              "invite",
              "platform_managed"
            ],
            "type": "string"
          },
          "utility_name": {
            "example": "Águas do Norte",
            "maxLength": 200,
            "type": "string"
          }
        },
        "required": [
          "utility_name",
          "country_code",
          "owner_contact"
        ],
        "type": "object"
      },
      "UtilityInvitationDelivery": {
        "properties": {
          "at": {
            "format": "date-time",
            "type": "string"
          },
          "channel": {
            "example": "email",
            "type": "string"
          },
          "outcome": {
            "enum": [
              "queued",
              "failed"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "UtilityInvitationDryRunRequest": {
        "additionalProperties": false,
        "properties": {
          "csv": {
            "example": "utility_name,country_code,owner_contact\nÁguas do Norte,MZ,owner@example.com\n",
            "type": "string"
          }
        },
        "required": [
          "csv"
        ],
        "type": "object"
      },
      "UtilityInvitationFieldError": {
        "description": "One failed field of an invitation or bulk row. Code is stable and clients translate it; reason is an English detail. The dry run checks the country against the server's supported countries (localization.countries and the default country) and refuses a row whose utility already exists or is invited, or whose owner already owns a utility or accepted an invitation. Confirmation never sends a row with errors.",
        "properties": {
          "code": {
            "enum": [
              "invalid_utility_name",
              "invalid_country",
              "unsupported_country",
              "invalid_contact",
              "pending_invitation",
              "owner_exists",
              "utility_exists",
              "duplicate_row",
              "invalid_setup_mode",
              "unknown_plan",
              "unknown_offer",
              "note_too_long",
              "invalid_csv",
              "invalid_idempotency_key",
              "create_failed"
            ],
            "type": "string"
          },
          "duplicate_of_row": {
            "description": "For duplicate_row",
            "the earlier row this one repeats": null,
            "type": "integer"
          },
          "field": {
            "description": "utility_name, country_code, owner_contact, plan_id, offer_id, note, setup_mode, csv, idempotency_key or row",
            "type": "string"
          },
          "reason": {
            "type": "string"
          }
        },
        "required": [
          "field",
          "code",
          "reason"
        ],
        "type": "object"
      },
      "UtilityInvitationList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/UtilityInvitation"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "description": "Pass as after for the next page",
            "type": "string"
          }
        },
        "type": "object"
      },
      "UtilityInvitationPreview": {
        "properties": {
          "contact_kind": {
            "enum": [
              "email",
              "phone"
            ],
            "type": "string"
          },
          "country_code": {
            "type": "string"
          },
          "expires_at": {
            "format": "date-time",
            "type": "string"
          },
          "owner_contact_masked": {
            "type": "string"
          },
          "setup_mode": {
            "enum": [
              "invite",
              "platform_managed"
            ],
            "type": "string"
          },
          "utility_name": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "UtilityInvitationSetupStep": {
        "properties": {
          "completed_at": {
            "format": "date-time",
            "type": "string"
          },
          "completed_by": {
            "properties": {
              "id": {
                "type": "string"
              },
              "name": {
                "type": "string"
              },
              "type": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "completion_source": {
            "example": "service_area.created",
            "type": "string"
          },
          "responsibility": {
            "enum": [
              "platform",
              "utility"
            ],
            "type": "string"
          },
          "step_id": {
            "example": "service_areas",
            "type": "string"
          }
        },
        "type": "object"
      },
      "UtilityInvitationToken": {
        "additionalProperties": false,
        "properties": {
          "token": {
            "description": "One-time token from the invitation link",
            "type": "string"
          }
        },
        "required": [
          "token"
        ],
        "type": "object"
      },
      "UtilityRow": {
        "properties": {
          "onboarding_status": {
            "description": "not_started when the utility has no application yet",
            "type": "string"
          },
          "organization_id": {
            "type": "string"
          },
          "organization_name": {
            "type": "string"
          },
          "plan_id": {
            "type": "string"
          },
          "plan_name": {
            "type": "string"
          },
          "subscription_status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "tenant_name": {
            "type": "string"
          },
          "tenant_slug": {
            "type": "string"
          },
          "tenant_status": {
            "type": "string"
          },
          "usage": {
            "$ref": "#/components/schemas/TenantUsage"
          }
        },
        "type": "object"
      },
      "UtilityTariff": {
        "properties": {
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "charge_components": {
            "items": {
              "$ref": "#/components/schemas/UtilityTariffChargeComponent"
            },
            "type": "array"
          },
          "code": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "type": "string"
          },
          "effective_from": {
            "format": "date-time",
            "type": "string"
          },
          "effective_to": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "fixed_charges": {
            "items": {
              "$ref": "#/components/schemas/UtilityTariffFixedCharge"
            },
            "type": "array"
          },
          "fixed_fee_cents": {
            "format": "int64",
            "type": "integer"
          },
          "id": {
            "type": "string"
          },
          "min_consumption_m3": {
            "type": "number"
          },
          "minimum_charge_cents": {
            "format": "int64",
            "type": "integer"
          },
          "minor_units": {
            "type": "integer"
          },
          "name": {
            "type": "string"
          },
          "sanitation_surcharge_percent": {
            "type": "number"
          },
          "status": {
            "enum": [
              "draft",
              "active",
              "superseded"
            ],
            "type": "string"
          },
          "tax_percent": {
            "type": "number"
          },
          "tenant_id": {
            "type": "string"
          },
          "tiers": {
            "items": {
              "$ref": "#/components/schemas/UtilityTariffTier"
            },
            "type": "array"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "code",
          "name",
          "category",
          "currency",
          "status"
        ],
        "type": "object"
      },
      "UtilityTariffChargeComponent": {
        "properties": {
          "accounting_role": {
            "type": "string"
          },
          "active": {
            "type": "boolean"
          },
          "amount_minor": {
            "format": "int64",
            "type": "integer"
          },
          "anchor_date": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "basis": {
            "enum": [
              "service_subtotal"
            ],
            "type": "string"
          },
          "cadence": {
            "enum": [
              "every_bill",
              "every_n_periods",
              "one_time"
            ],
            "type": "string"
          },
          "code": {
            "maxLength": 64,
            "type": "string"
          },
          "description": {
            "maxLength": 500,
            "type": "string"
          },
          "diameter_mm": {
            "nullable": true,
            "type": "integer"
          },
          "effective_from": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "effective_to": {
            "format": "date-time",
            "nullable": true,
            "type": "string"
          },
          "interval_periods": {
            "minimum": 1,
            "type": "integer"
          },
          "kind": {
            "enum": [
              "fixed",
              "percentage"
            ],
            "type": "string"
          },
          "labels": {
            "additionalProperties": {
              "type": "string"
            },
            "type": "object"
          },
          "name": {
            "maxLength": 120,
            "type": "string"
          },
          "partial_period_policy": {
            "enum": [
              "full",
              "prorate",
              "skip"
            ],
            "type": "string"
          },
          "payment_terms": {
            "enum": [
              "inherit_invoice"
            ],
            "type": "string"
          },
          "rate_basis_points": {
            "format": "int64",
            "type": "integer"
          },
          "rate_percent": {
            "type": "number"
          },
          "service_area_id": {
            "type": "string"
          },
          "skipped_cycle_policy": {
            "enum": [
              "skip"
            ],
            "type": "string"
          },
          "sort_order": {
            "type": "integer"
          },
          "taxable": {
            "type": "boolean"
          }
        },
        "required": [
          "code",
          "name",
          "kind"
        ],
        "type": "object"
      },
      "UtilityTariffFixedCharge": {
        "properties": {
          "amount_minor": {
            "format": "int64",
            "type": "integer"
          },
          "charge_code": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          }
        },
        "required": [
          "charge_code",
          "amount_minor"
        ],
        "type": "object"
      },
      "UtilityTariffTier": {
        "properties": {
          "max_m3": {
            "description": "Zero means unbounded",
            "type": "number"
          },
          "min_m3": {
            "type": "number"
          },
          "rate_per_m3_cents": {
            "format": "int64",
            "type": "integer"
          },
          "tier_number": {
            "type": "integer"
          },
          "volume_end_l": {
            "format": "int64",
            "nullable": true,
            "type": "integer"
          },
          "volume_start_l": {
            "format": "int64",
            "type": "integer"
          }
        },
        "type": "object"
      },
      "VerificationRequirementDefinition": {
        "properties": {
          "applies_to": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "checked_by": {
            "type": "string"
          },
          "key": {
            "type": "string"
          },
          "label_key": {
            "type": "string"
          },
          "labels": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Localized labels for configured custom requirements.",
            "type": "object"
          }
        },
        "required": [
          "key",
          "label_key",
          "applies_to",
          "checked_by"
        ],
        "type": "object"
      },
      "VerificationResult": {
        "properties": {
          "verified": {
            "type": "boolean"
          }
        },
        "required": [
          "verified"
        ],
        "type": "object"
      },
      "VisitSlots": {
        "properties": {
          "dates": {
            "items": {
              "format": "date",
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "dates"
        ],
        "type": "object"
      },
      "VolumeQuality": {
        "properties": {
          "complete": {
            "type": "boolean"
          },
          "device_id": {
            "type": "string"
          },
          "first_observed_at": {
            "format": "date-time",
            "type": "string"
          },
          "last_observed_at": {
            "format": "date-time",
            "type": "string"
          },
          "sample_count": {
            "type": "integer"
          },
          "source": {
            "enum": [
              "measurements",
              "meter_consumption",
              "none"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "WaterConnection": {
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "activated_at": {
            "format": "date-time",
            "type": "string"
          },
          "address": {
            "type": "string"
          },
          "applied_at": {
            "format": "date-time",
            "type": "string"
          },
          "approved_at": {
            "format": "date-time",
            "type": "string"
          },
          "category": {
            "enum": [
              "residential",
              "commercial",
              "industrial",
              "institutional",
              "government"
            ],
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "currency": {
            "maxLength": 3,
            "minLength": 3,
            "type": "string"
          },
          "customer_id": {
            "type": "string"
          },
          "customer_name": {
            "description": "Display name of the referenced customer. Omitted when unknown.",
            "type": "string"
          },
          "diameter_mm": {
            "type": "integer"
          },
          "estimated_cost_cents": {
            "format": "int64",
            "type": "integer"
          },
          "gps_coordinates": {
            "type": "string"
          },
          "id": {
            "pattern": "^con_",
            "type": "string"
          },
          "installed_at": {
            "format": "date-time",
            "type": "string"
          },
          "meter_holder_name": {
            "description": "Display name of the customer who holds the account the meter is installed on. Omitted when unknown.",
            "type": "string"
          },
          "meter_id": {
            "type": "string"
          },
          "meter_serial": {
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "pipe_diameter_mm": {
            "type": "integer"
          },
          "pipe_material": {
            "type": "string"
          },
          "pressure_zone_id": {
            "type": "string"
          },
          "property_address": {
            "description": "Address line of the referenced property. Omitted when unknown.",
            "type": "string"
          },
          "property_holder_name": {
            "description": "Display name of the customer who holds the referenced property. Omitted when unknown.",
            "type": "string"
          },
          "property_id": {
            "type": "string"
          },
          "rejection_reason": {
            "type": "string"
          },
          "retired_at": {
            "format": "date-time",
            "type": "string"
          },
          "service_status": {
            "enum": [
              "pending_install",
              "active",
              "cut_for_debt",
              "suspended_customer_request",
              "abandoned"
            ],
            "type": "string"
          },
          "status": {
            "enum": [
              "draft",
              "submitted",
              "inspecting",
              "approved",
              "rejected",
              "installing",
              "active",
              "suspended",
              "disconnected",
              "retired"
            ],
            "type": "string"
          },
          "suspended_at": {
            "format": "date-time",
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "customer_id",
          "property_id",
          "category",
          "diameter_mm",
          "status",
          "service_status",
          "estimated_cost_cents",
          "currency",
          "applied_at",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "WaterResult": {
        "properties": {
          "analyzed_at": {
            "format": "date-time",
            "type": "string"
          },
          "compliance": {
            "enum": [
              "compliant",
              "non_compliant",
              "not_evaluated"
            ],
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "max_applied": {
            "type": "number"
          },
          "method": {
            "type": "string"
          },
          "min_applied": {
            "type": "number"
          },
          "parameter": {
            "type": "string"
          },
          "sample_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "value": {
            "type": "number"
          }
        },
        "type": "object"
      },
      "WaterResultList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WaterResult"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "WaterSample": {
        "properties": {
          "asset_id": {
            "type": "string"
          },
          "code": {
            "type": "string"
          },
          "collected_by": {
            "type": "string"
          },
          "dma_id": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "laboratory": {
            "type": "string"
          },
          "location_type": {
            "enum": [
              "reservoir",
              "zone"
            ],
            "type": "string"
          },
          "notes": {
            "type": "string"
          },
          "sampled_at": {
            "format": "date-time",
            "type": "string"
          },
          "status": {
            "enum": [
              "collected",
              "analyzed"
            ],
            "type": "string"
          }
        },
        "type": "object"
      },
      "WaterSampleList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WaterSample"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "WorkOrder": {
        "additionalProperties": true,
        "properties": {
          "account_holder_name": {
            "description": "Display name of the customer who holds the referenced account. Omitted when unknown.",
            "type": "string"
          },
          "account_id": {
            "type": "string"
          },
          "account_number": {
            "description": "Number of the referenced account, e.g. CTA-000044. Omitted when unknown.",
            "type": "string"
          },
          "connection_holder_name": {
            "description": "Display name of the customer who holds the referenced connection. Omitted when unknown.",
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "order_number": {
            "type": "string"
          },
          "order_type": {
            "type": "string"
          },
          "priority": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "WorkOrderLineStockRequest": {
        "properties": {
          "location_id": {
            "type": "string"
          },
          "occurred_at": {
            "format": "date-time",
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "reason": {
            "type": "string"
          },
          "serials": {
            "items": {
              "type": "string"
            },
            "type": "array"
          }
        },
        "required": [
          "quantity"
        ],
        "type": "object"
      },
      "WorkOrderMaterialInput": {
        "properties": {
          "description": {
            "type": "string"
          },
          "item_id": {
            "description": "Catalogue item; omit for a free-text part",
            "type": "string"
          },
          "part_code": {
            "type": "string"
          },
          "quantity": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "required": {
            "description": "Blocks dispatch until reserved; defaults to true for meters on installation and replacement orders",
            "type": "boolean"
          },
          "source_location_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          }
        },
        "required": [
          "quantity"
        ],
        "type": "object"
      },
      "WorkOrderMaterialLine": {
        "properties": {
          "availability": {
            "properties": {
              "available": {
                "$ref": "#/components/schemas/InventoryQuantity"
              },
              "other_locations": {
                "items": {
                  "properties": {
                    "available": {
                      "$ref": "#/components/schemas/InventoryQuantity"
                    },
                    "kind": {
                      "type": "string"
                    },
                    "location_id": {
                      "type": "string"
                    },
                    "location_name": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                },
                "type": "array"
              },
              "short": {
                "$ref": "#/components/schemas/InventoryQuantity"
              },
              "source_location_id": {
                "type": "string"
              },
              "source_location_name": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "cost_minor": {
            "description": "Issues less returns at average cost",
            "format": "int64",
            "type": "integer"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "created_by": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "description": "wml_ identifier (wmt_ for a legacy free-text material)",
            "type": "string"
          },
          "is_meter": {
            "type": "boolean"
          },
          "issued": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "item_code": {
            "type": "string"
          },
          "item_id": {
            "type": "string"
          },
          "kit_id": {
            "type": "string"
          },
          "legacy": {
            "type": "boolean"
          },
          "needs_mapping": {
            "description": "Free text for a stores person to map; touches no stock",
            "type": "boolean"
          },
          "part_code": {
            "type": "string"
          },
          "planned": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "required": {
            "type": "boolean"
          },
          "reservations": {
            "items": {
              "properties": {
                "created_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "expires_at": {
                  "format": "date-time",
                  "type": "string"
                },
                "id": {
                  "type": "string"
                },
                "location_id": {
                  "type": "string"
                },
                "quantity": {
                  "$ref": "#/components/schemas/InventoryQuantity"
                },
                "serial_id": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                }
              },
              "type": "object"
            },
            "type": "array"
          },
          "reserved": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "returned": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "serialised": {
            "type": "boolean"
          },
          "source_location_id": {
            "type": "string"
          },
          "stock_status": {
            "enum": [
              "reserved",
              "partially_reserved",
              "short",
              "issued",
              "settled",
              "released",
              "unmapped",
              "untracked"
            ],
            "type": "string"
          },
          "suggested_transfer": {
            "properties": {
              "from_location_id": {
                "type": "string"
              },
              "quantity": {
                "$ref": "#/components/schemas/InventoryQuantity"
              },
              "to_location_id": {
                "type": "string"
              }
            },
            "type": "object"
          },
          "tenant_id": {
            "type": "string"
          },
          "unit": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          },
          "used": {
            "$ref": "#/components/schemas/InventoryQuantity"
          },
          "work_order_id": {
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "work_order_id",
          "planned",
          "reserved",
          "issued",
          "returned",
          "required",
          "needs_mapping",
          "stock_status",
          "cost_minor",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "WorkOrderMaterialLineList": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WorkOrderMaterialLine"
            },
            "type": "array"
          }
        },
        "required": [
          "data"
        ],
        "type": "object"
      },
      "WorkOrderPage": {
        "properties": {
          "data": {
            "items": {
              "$ref": "#/components/schemas/WorkOrder"
            },
            "type": "array"
          },
          "has_more": {
            "type": "boolean"
          },
          "next_cursor": {
            "type": "string"
          }
        },
        "required": [
          "data",
          "has_more"
        ],
        "type": "object"
      },
      "WorkOrderStatusChange": {
        "properties": {
          "actor_id": {
            "type": "string"
          },
          "changed_at": {
            "format": "date-time",
            "type": "string"
          },
          "from_status": {
            "description": "Absent on the entry that created the order",
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "note": {
            "type": "string"
          },
          "note_code": {
            "description": "Stable code of a note the server wrote (work_order.generated, work_order.dispatched, work_order.cancel.settled_before_cutoff, work_order.cancel.payment_reversed); clients word it and fall back to note. Absent for notes people typed.",
            "type": "string"
          },
          "note_params": {
            "additionalProperties": {
              "type": "string"
            },
            "description": "Values the note code fills in: source for work_order.generated, crew for work_order.dispatched.",
            "type": "object"
          },
          "tenant_id": {
            "type": "string"
          },
          "to_status": {
            "type": "string"
          },
          "work_order_id": {
            "type": "string"
          }
        },
        "type": "object"
      },
      "WorkOrderWithMaterials": {
        "properties": {
          "connection_holder_name": {
            "description": "Display name of the customer who holds the referenced connection. Omitted when unknown.",
            "type": "string"
          },
          "connection_id": {
            "type": "string"
          },
          "created_at": {
            "format": "date-time",
            "type": "string"
          },
          "crew_id": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "id": {
            "type": "string"
          },
          "material_cost_minor": {
            "description": "Cost of the materials used, at average cost; per new connection on its installation order",
            "format": "int64",
            "type": "integer"
          },
          "material_lines": {
            "items": {
              "$ref": "#/components/schemas/WorkOrderMaterialLine"
            },
            "type": "array"
          },
          "order_number": {
            "type": "string"
          },
          "order_type": {
            "type": "string"
          },
          "priority": {
            "type": "string"
          },
          "proposed_kit_id": {
            "description": "Default kit for the order type, offered when created without materials",
            "type": "string"
          },
          "service_area_id": {
            "type": "string"
          },
          "status": {
            "type": "string"
          },
          "tenant_id": {
            "type": "string"
          },
          "updated_at": {
            "format": "date-time",
            "type": "string"
          }
        },
        "required": [
          "id",
          "tenant_id",
          "order_number",
          "order_type",
          "priority",
          "status",
          "description",
          "created_at",
          "updated_at"
        ],
        "type": "object"
      },
      "WorkspaceSettingsTemplate": {
        "properties": {
          "account_types": {
            "items": {
              "enum": [
                "utility",
                "authority",
                "operator",
                "partner"
              ],
              "type": "string"
            },
            "type": "array"
          },
          "country_code": {
            "pattern": "^[A-Z]{2}$",
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "key": {
            "type": "string"
          },
          "name": {
            "type": "string"
          },
          "owner": {
            "type": "string"
          },
          "preview": {
            "properties": {
              "automation_rules": {
                "minimum": 0,
                "type": "integer"
              },
              "billing_schedules": {
                "minimum": 0,
                "type": "integer"
              },
              "integrations": {
                "minimum": 0,
                "type": "integer"
              },
              "skipped_area_rules": {
                "minimum": 0,
                "type": "integer"
              },
              "skipped_area_schedules": {
                "minimum": 0,
                "type": "integer"
              },
              "skipped_webhook_rules": {
                "minimum": 0,
                "type": "integer"
              },
              "tariffs": {
                "minimum": 0,
                "type": "integer"
              }
            },
            "required": [
              "tariffs",
              "billing_schedules",
              "skipped_area_schedules",
              "automation_rules",
              "skipped_webhook_rules",
              "skipped_area_rules",
              "integrations"
            ],
            "type": "object"
          },
          "publisher": {
            "type": "string"
          },
          "review_due_at": {
            "format": "date-time",
            "type": "string"
          },
          "review_interval_days": {
            "minimum": 1,
            "type": "integer"
          },
          "review_overdue": {
            "type": "boolean"
          },
          "reviewed_at": {
            "format": "date-time",
            "type": "string"
          },
          "sources": {
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "version": {
            "type": "string"
          }
        },
        "required": [
          "key",
          "version",
          "name",
          "publisher",
          "owner",
          "reviewed_at",
          "review_interval_days",
          "review_due_at",
          "review_overdue",
          "country_code",
          "preview"
        ],
        "type": "object"
      }
    },
    "securitySchemes": {
      "apiKeyAuth": {
        "description": "An API key (sk_live_... or sk_test_...), on $BUSINESS_API only.",
        "scheme": "bearer",
        "type": "http"
      },
      "bearerAuth": {
        "bearerFormat": "JWT",
        "scheme": "bearer",
        "type": "http"
      },
      "connectorSession": {
        "description": "Opaque connector session token sent as Authorization: Bearer. Payment endpoints also accept Authorization: Token for compatibility.",
        "scheme": "bearer",
        "type": "http"
      },
      "connectorTokenHeader": {
        "description": "Connector session token accepted by payment connector endpoints.",
        "in": "header",
        "name": "X-Connector-Token",
        "type": "apiKey"
      },
      "scimTokenAuth": {
        "description": "SCIM provisioning token (scim_live_...) scoped to one tenant.",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "description": "B2B2C v1 APIs for platform administration, utility business operations, consumer self-service, and private external integrations. The utility is the tenant in v1. Domain services are shared across all four surfaces.",
    "title": "Gota API",
    "version": "1.0.0"
  },
  "openapi": "3.1.0",
  "paths": {
    "/api/openapi.json": {
      "get": {
        "description": "Returns this API contract as JSON, generated from the embedded specification on first request and cached for the life of the process. The servers entry is set to the external origin of the listener that served the request, and every path prefix is rewritten to match the API mounts configured on that listener, so the document always matches the URLs the caller can actually reach. The response is public, needs no authentication and carries Cache-Control: public, max-age=300.",
        "operationId": "getOpenApiDocument",
        "responses": {
          "200": {
            "description": "OpenAPI document"
          }
        },
        "security": [],
        "summary": "This OpenAPI document as JSON"
      }
    },
    "$AUTH_API/2fa": {
      "get": {
        "description": "Reports the signed-in person's authenticator-app (TOTP) enrolment: whether it is enabled, whether an enrolment is pending confirmation, when it was confirmed, and whether a security policy of one of their workspaces requires it. When two-factor authentication is enabled the response also gives the number of unused recovery codes left.",
        "operationId": "getTwoFactorStatus",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TwoFactorStatus"
                }
              }
            },
            "description": "Get the current user two-factor status"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the current user two-factor status"
      }
    },
    "$AUTH_API/2fa/confirm": {
      "post": {
        "description": "Activates the pending authenticator secret created by the enroll call, using the first 6-digit code from the app. On success it returns eight recovery codes in plain text; this is the only time they are shown, so the client must display them for the person to store. Returns 409 when no enrolment was started or two-factor authentication is already enabled, 400 for a wrong or expired code, and 429 when called too often. An audit event is recorded.",
        "operationId": "confirmTwoFactor",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TwoFactorCodeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TwoFactorConfirmation"
                }
              }
            },
            "description": "Confirm enrolment with the first code; returns recovery codes once"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm enrolment with the first code; returns recovery codes once"
      }
    },
    "$AUTH_API/2fa/disable": {
      "post": {
        "description": "Turns off two-factor authentication for the signed-in person and deletes the authenticator secret and recovery codes. The caller must prove identity with either the current password or a valid authenticator or recovery code; sending neither returns 400, a wrong password returns 401, and a wrong code returns 400 and counts towards the lockout (five failures lock the factor for 15 minutes). Returns 409 when two-factor authentication is not set up. Answers 204 and records an audit event.",
        "operationId": "disableTwoFactor",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TwoFactorDisableRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Disable two-factor after proving the password or a current code"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Disable two-factor after proving the password or a current code"
      }
    },
    "$AUTH_API/2fa/enroll": {
      "post": {
        "description": "Starts authenticator-app enrolment by generating a new TOTP secret, storing it encrypted in a pending state, and returning an otpauth:// URI for a QR code plus a masked copy of the secret. Calling it again replaces any earlier pending secret. Nothing is enforced until the enrolment is confirmed with a code; returns 409 when two-factor authentication is already enabled and 429 when called too often. The response is sent with Cache-Control: no-store.",
        "operationId": "enrollTwoFactor",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TwoFactorEnrollment"
                }
              }
            },
            "description": "Start two-factor enrolment and return the QR URI"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "409": {
            "description": "Two-factor is already enabled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start two-factor enrolment and return the QR URI"
      }
    },
    "$AUTH_API/account-moves/pending": {
      "get": {
        "description": "Returns, under data and oldest first, the pending moves whose destination is the active account, together with detachments of the active account itself, which it approves as its own new owner. Moves for other accounts are never revealed. The caller must be an owner of the active workspace or organization; any other context (consumer, platform, a non-owner role) returns 403. The list is not paginated.",
        "operationId": "getPendingAccountMoves",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMoveList"
                }
              }
            },
            "description": "Pending moves awaiting the active account's consent"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The active context is not an account the caller owns"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get account moves awaiting the active account's approval"
      }
    },
    "$AUTH_API/account-moves/{moveID}/approve": {
      "post": {
        "description": "Records the destination's consent to a pending move and, in the same transaction, re-parents the account and its subtree. The caller must be an owner of the active account, and that account must be the move's target parent, or the moved account itself when the move detaches it; otherwise 403, which is also returned for a move that is no longer pending. Returns 404 for an unknown move and 409 when the account's parent has changed since the move was requested. Answers 200 with the completed move. No body is read.",
        "operationId": "approveAccountMove",
        "parameters": [
          {
            "description": "Identifier of the pending move (prefixed \"amv_\"), as returned by requestAccountMove or getPendingAccountMoves.",
            "in": "path",
            "name": "moveID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMove"
                }
              }
            },
            "description": "Move approved and applied"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The active account is not the move's destination, or the move is not pending"
          },
          "404": {
            "description": "Move not found"
          },
          "409": {
            "description": "The account tree changed since the move was requested"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve a pending account move and apply it"
      }
    },
    "$AUTH_API/account-relationships": {
      "get": {
        "description": "Lists the relationships in which the caller's current account is either the source or the destination, with the names of both accounts filled in. Results are ordered by creation time and paginated with limit (default 20, maximum 100) and the after cursor; total_count gives the number of relationships before pagination. Requires a role that can manage the current account, otherwise 403.",
        "operationId": "listAccountRelationships",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountRelationshipPage"
                }
              }
            },
            "description": "Cursor-paginated relationships and requests awaiting consent"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List relationships involving the active account"
      },
      "post": {
        "description": "Records the current account's consent to give another account (to_account_id) a set of grants under a relationship of type operations, reseller or regulator. The relationship is returned as pending and confers no access until an owner of the destination account accepts it. Only an owner of the current account may call this; a missing or identical destination account or an empty grants list returns 403, and an unknown type, a grant missing role, resource_type or action, a regulator grant whose action does not end in \":read\", or an expiry in the past returns 400. An audit event is recorded.",
        "operationId": "requestAccountRelationship",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "agreement_id": {
                    "type": "string"
                  },
                  "expires_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "grants": {
                    "items": {
                      "properties": {
                        "action": {
                          "type": "string"
                        },
                        "expires_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "resource_id": {
                          "type": "string"
                        },
                        "resource_type": {
                          "type": "string"
                        },
                        "role": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "role",
                        "resource_type",
                        "action"
                      ],
                      "type": "object"
                    },
                    "minItems": 1,
                    "type": "array"
                  },
                  "to_account_id": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "operations",
                      "reseller",
                      "regulator"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "to_account_id",
                  "type",
                  "grants"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Request recorded; grants remain unavailable until the other account accepts"
          },
          "400": {
            "description": "Invalid relationship or grant"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Active account owner consent is required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request a consented relationship with another account"
      }
    },
    "$AUTH_API/account-relationships/{relationshipID}": {
      "delete": {
        "description": "Ends a relationship involving the caller's current account, so its grants stop contributing access from then on. Only an owner of the current account may revoke it (403 otherwise), and a relationship that does not involve that account returns 404. Answers 204 and records an audit event.",
        "operationId": "revokeAccountRelationship",
        "parameters": [
          {
            "description": "Identifier of the account relationship to revoke, as returned when it was requested or listed (prefixed \"arl_\").",
            "in": "path",
            "name": "relationshipID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Relationship revoked"
          },
          "403": {
            "description": "Active account does not participate in this relationship"
          },
          "404": {
            "description": "Relationship not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a relationship involving the active account"
      }
    },
    "$AUTH_API/account-relationships/{relationshipID}/accept": {
      "post": {
        "description": "Records the destination account's consent to a pending relationship, after which its grants can appear in sessions and contribute access. The caller must be an owner of the current account and that account must be the relationship's destination; otherwise the call returns 403 or 404. Answers 204 and records an audit event.",
        "operationId": "acceptAccountRelationship",
        "parameters": [
          {
            "description": "Identifier of the pending account relationship to accept (prefixed \"arl_\").",
            "in": "path",
            "name": "relationshipID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Destination consent recorded"
          },
          "403": {
            "description": "Active account does not match the destination"
          },
          "404": {
            "description": "Relationship not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept a relationship requested for the active account"
      }
    },
    "$AUTH_API/accounts": {
      "get": {
        "description": "Returns the same accessible-account tree as getAccountTree: under data, every account backed by one of the signed-in person's active memberships, the ancestor accounts that place them in the ownership tree (which grant nothing), accounts reached through inherited memberships with their allowed scopes, and relationship contexts as separate roots. The list is not paginated. Any signed-in person may call it; it needs no scope and returns 401 without a session.",
        "operationId": "getAccessibleAccounts",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountTreeList"
                }
              }
            },
            "description": "Accessible accounts with their ownership edges"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "404": {
            "description": "The deployment's identity store does not keep an account tree"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the accounts the signed-in person can open"
      },
      "post": {
        "description": "Creates a new utility workspace for the signed-in person without a second identity, makes them its first owner, and returns a new session already switched into it (201). The workspace can start from a published settings template (template_key and template_version together) or from a copy of another workspace the person owns (copy_from_tenant_id), but not both; parent_account_id or organization_id place it under an account where the person is an owner or admin, otherwise 403. Returns 400 for a missing name or unsupported type, 429 when the person reaches the configured account limit or creates accounts too quickly, and 403 with ACCOUNT_CREATION_REVIEW_REQUIRED when the request needs manual review.",
        "operationId": "createAccount",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "copy_from_tenant_id": {
                    "description": "Copy supported settings from an account the person owns. Tariffs become drafts, schedules are paused, automations and integration definitions are disabled, message templates are pending approval, and credentials are excluded.",
                    "type": "string"
                  },
                  "country": {
                    "maxLength": 2,
                    "minLength": 2,
                    "pattern": "^[A-Z]{2}$",
                    "type": "string"
                  },
                  "device_fingerprint": {
                    "description": "Opaque client-generated installation token used only as an account-creation abuse signal.",
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "minLength": 1,
                    "type": "string"
                  },
                  "organization_id": {
                    "deprecated": true,
                    "description": "Legacy alias for parent_account_id. Retained during the organization route compatibility period.",
                    "type": "string"
                  },
                  "parent_account_id": {
                    "description": "Parent account that owns this new account. Use this field to create a child.",
                    "type": "string"
                  },
                  "template_key": {
                    "description": "Published template key. Must be supplied with template_version and cannot be combined with copy_from_tenant_id.",
                    "type": "string"
                  },
                  "template_version": {
                    "description": "Immutable published version to apply. The publisher and exact version are recorded as tenant provenance.",
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "utility",
                      "authority",
                      "operator",
                      "partner"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "country",
                  "type"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Workspace created and the person switched into its owner context"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Creation risk exceeded the configured threshold and needs manual review, or bot challenge required/failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "409": {
            "description": "Workspace slug is already in use"
          },
          "429": {
            "description": "Account creation rate or per-person account limit reached"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a workspace for the signed-in person"
      }
    },
    "$AUTH_API/accounts/settings-copy/preview": {
      "post": {
        "description": "Shows what would be copied from an existing workspace (source_tenant_id) into a new one, without changing anything, so the person can review it before calling createAccount with copy_from_tenant_id. The caller must be an owner of the source workspace. Returns 400 when settings copy is not configured on this deployment.",
        "operationId": "previewWorkspaceSettingsCopy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "source_tenant_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "source_tenant_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "automation_rules": {
                      "description": "Automation rules copied disabled; runs and history are excluded.",
                      "minimum": 0,
                      "type": "integer"
                    },
                    "billing_schedules": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "integrations": {
                      "description": "Integration definitions copied disabled without the source configuration reference or health state.",
                      "minimum": 0,
                      "type": "integer"
                    },
                    "skipped_area_rules": {
                      "description": "Rules with source-area, location, or crew references are skipped until those records are mapped.",
                      "minimum": 0,
                      "type": "integer"
                    },
                    "skipped_area_schedules": {
                      "minimum": 0,
                      "type": "integer"
                    },
                    "skipped_webhook_rules": {
                      "description": "Rules with webhook actions are skipped to avoid copying endpoint or secret configuration.",
                      "minimum": 0,
                      "type": "integer"
                    },
                    "tariffs": {
                      "minimum": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "tariffs",
                    "billing_schedules",
                    "skipped_area_schedules",
                    "automation_rules",
                    "skipped_webhook_rules",
                    "skipped_area_rules",
                    "integrations"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Configuration counts that would be copied"
          },
          "400": {
            "description": "Invalid source account"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The person does not own the source account"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Preview settings available from an account owned by the signed-in person"
      }
    },
    "$AUTH_API/accounts/templates": {
      "get": {
        "description": "Lists the published workspace settings templates that can be applied when creating a workspace, each with its key, immutable version, publisher, review status and a preview of what it sets up. Templates without a country or account type restriction are always included. Returns an empty list when no template catalogue is configured; requires a signed-in person.",
        "operationId": "listWorkspaceSettingsTemplates",
        "parameters": [
          {
            "description": "ISO 3166-1 alpha-2 country code (case-insensitive) used to keep only templates published for that country; when omitted, templates for every country are returned.",
            "in": "query",
            "name": "country",
            "required": false,
            "schema": {
              "pattern": "^[A-Z]{2}$",
              "type": "string"
            }
          },
          {
            "description": "Account type (for example \"utility\") used to keep only templates published for that type; when omitted, templates for every type are returned.",
            "in": "query",
            "name": "type",
            "required": false,
            "schema": {
              "enum": [
                "utility",
                "authority",
                "operator",
                "partner"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/WorkspaceSettingsTemplate"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Payload-free publication metadata and safe configuration previews"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List published workspace templates for the selected country and account type"
      }
    },
    "$AUTH_API/accounts/templates/preview": {
      "post": {
        "description": "Resolves one exact published template by key and version and returns its description and a preview of the settings it would create, without changing anything. Both key and version are required; an unknown pair, or a deployment with no template catalogue, returns 400.",
        "operationId": "previewWorkspaceSettingsTemplate",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "key": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  }
                },
                "required": [
                  "key",
                  "version"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkspaceSettingsTemplate"
                }
              }
            },
            "description": "Publication metadata and safe configuration counts"
          },
          "400": {
            "description": "Unknown or invalid publication"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Preview an exact published workspace template version"
      }
    },
    "$AUTH_API/accounts/tree": {
      "get": {
        "description": "Returns, under data, every account backed by one of the signed-in person's active memberships, plus the ancestor accounts needed to place them in the ownership tree. Entries with direct true come from the person's own membership and carry its roles; ancestor entries only label the tree and grant nothing. Access granted to a descendant through an inherited membership appears with inherited true, the source account and the scopes that the grant allows, and contexts reached through a consented relationship are returned as separate roots with relationship_access true. The list is not paginated. Any signed-in person may call it; it needs no scope and returns 401 without a session.",
        "operationId": "getAccountTree",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountTreeList"
                }
              }
            },
            "description": "Accessible accounts with their ownership edges"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "404": {
            "description": "The deployment's identity store does not keep an account tree"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the accounts the signed-in person can open, arranged by ownership"
      }
    },
    "$AUTH_API/accounts/{accountID}/children": {
      "post": {
        "description": "Creates a new utility workspace as a child of an existing account and returns a new session switched into it (201). The caller must be an active owner or admin of the parent account, otherwise 403. The body accepts the same name, type, country and optional settings source (a template key and version, or a workspace to copy) as createAccount, with the same limits, rate limiting and review checks.",
        "operationId": "createAccountChild",
        "parameters": [
          {
            "description": "Identifier of the parent account (a workspace or organization the caller owns or administers) under which the new workspace is created.",
            "in": "path",
            "name": "accountID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "copy_from_tenant_id": {
                    "type": "string"
                  },
                  "country": {
                    "pattern": "^[A-Z]{2}$",
                    "type": "string"
                  },
                  "device_fingerprint": {
                    "maxLength": 128,
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 255,
                    "minLength": 1,
                    "type": "string"
                  },
                  "template_key": {
                    "type": "string"
                  },
                  "template_version": {
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "utility",
                      "authority",
                      "operator",
                      "partner"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "type",
                  "country"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Child account created and selected"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Active owner consent for the parent account is required"
          },
          "409": {
            "description": "Account limit or name conflict"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an account owned by the active parent account"
      }
    },
    "$AUTH_API/accounts/{accountID}/memberships/{membershipID}/inherit": {
      "delete": {
        "description": "Removes the explicit grant that lets a membership of the active account reach a descendant account; access through it stops from then on. The caller must be an owner or admin of the active account and the membership must be an active membership of that account, otherwise 403. Returns 404 when the membership does not exist or holds no inherited grant for that account, and 204 on success.",
        "operationId": "revokeInheritedAccountMembership",
        "parameters": [
          {
            "description": "Identifier of the descendant account whose inherited grant is removed.",
            "in": "path",
            "name": "accountID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the active account's membership that holds the inherited grant.",
            "in": "path",
            "name": "membershipID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Inherited access removed"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The caller cannot manage the membership's account"
          },
          "404": {
            "description": "Membership or inherited grant not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a membership's inherited access to a descendant account"
      },
      "post": {
        "description": "Gives an existing membership of the active account access to one of its descendant accounts, limited to the listed scopes and to max_depth levels below the membership's account. The caller must be an owner or admin of the active account, and the membership must be an active membership of that same account; otherwise 403. The target account must be a descendant within max_depth (403 otherwise), and every scope must be one the membership already holds (403 otherwise). Calling it again for the same membership and account replaces the scopes and depth. Returns 400 for an empty scopes list, a scope of \"*\" or an empty string, a max_depth outside 1 to 8, or unknown body fields, 404 when the membership does not exist, and 204 on success.",
        "operationId": "grantInheritedAccountMembership",
        "parameters": [
          {
            "description": "Identifier of the descendant account that the membership should reach.",
            "in": "path",
            "name": "accountID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the active account's membership that receives the inherited access.",
            "in": "path",
            "name": "membershipID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "max_depth": {
                    "description": "How many levels below the membership's account the grant reaches; the target account must lie within this depth.",
                    "example": 1,
                    "maximum": 8,
                    "minimum": 1,
                    "type": "integer"
                  },
                  "scopes": {
                    "description": "Scopes the membership may use in the descendant account. Each must already be held by the membership; \"*\" is refused.",
                    "example": [
                      "connections:read",
                      "invoices:read"
                    ],
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array"
                  }
                },
                "required": [
                  "scopes",
                  "max_depth"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Inherited access granted or updated"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The caller cannot manage the membership's account, the target is not a descendant in range, or a scope is not held"
          },
          "404": {
            "description": "Membership not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Let a parent account membership reach a descendant account"
      }
    },
    "$AUTH_API/accounts/{accountID}/move": {
      "post": {
        "description": "Records the current parent's consent to move an account, with its whole subtree, under target_parent_id, or to detach it as a root account when target_parent_id is empty. The caller must be an owner of the active account, and that account must be the account's current parent (or the account itself when it has no parent); otherwise 403. The move is returned as pending (201) and changes nothing until an owner of the destination (or of the account itself, for a detachment) approves it with approveAccountMove. Returns 400 when the target is the account itself or the body has unknown fields, 404 when the account does not exist, and 409 when the account already sits under the target or its parent changed in the meantime. The tree is limited to 8 levels and may not form a cycle.",
        "operationId": "requestAccountMove",
        "parameters": [
          {
            "description": "Identifier of the account to move, as returned by getAccountTree; its descendants move with it.",
            "in": "path",
            "name": "accountID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "target_parent_id": {
                    "description": "Account that should become the new parent. Leave empty or omit it to detach the account and make it a root account.",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountMove"
                }
              }
            },
            "description": "Move recorded and awaiting the destination's approval"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The caller is not an owner of the account's current parent"
          },
          "404": {
            "description": "Account not found"
          },
          "409": {
            "description": "The account already sits under the target, or its parent changed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Propose moving an account under another parent account"
      }
    },
    "$AUTH_API/device/approve": {
      "post": {
        "description": "Lets the signed-in person approve a pending device sign-in by entering the user_code the device shows; case and the hyphen are ignored. The device's next poll then receives a session for the person in context_id or, when omitted, the person's preferred context. The response echoes the user code, the device name and location given when the code was requested, and the chosen context. Returns 400 for an unknown code or with code expired_token for an expired one, 403 when the person is disabled or context_id is not one of their contexts, and 401 without a session. API keys are refused.",
        "operationId": "approveDeviceCode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "context_id": {
                    "description": "Context the device should be signed in to; defaults to the person's preferred context.",
                    "type": "string"
                  },
                  "user_code": {
                    "description": "Code shown by the device, for example ABCD-EFGH.",
                    "example": "ABCD-EFGH",
                    "type": "string"
                  }
                },
                "required": [
                  "user_code"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCodeApproval"
                }
              }
            },
            "description": "Device sign-in approved"
          },
          "400": {
            "description": "Unknown or expired user code"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The person is disabled or the context is not available"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve a device sign-in with the code it shows"
      }
    },
    "$AUTH_API/device/code": {
      "post": {
        "description": "Starts a device authorization for a device that cannot show a sign-in form, such as a terminal. The response gives a secret device_code for the device, a short user_code (for example ABCD-EFGH) that the person enters at verification_uri while signed in, the lifetime in seconds (300) and the minimum polling interval in seconds (5). The device then polls pollDeviceToken. The body is optional and only labels the request with a device name and location, which are shown to the person approving it. It needs no authentication; a malformed body returns 400.",
        "operationId": "startDeviceCode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "device_name": {
                    "description": "Name of the device asking to sign in, shown to the approving person.",
                    "example": "Counter terminal 2",
                    "type": "string"
                  },
                  "location": {
                    "description": "Where the device is, shown to the approving person.",
                    "example": "Head office",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeviceCodeGrant"
                }
              }
            },
            "description": "Device and user codes issued"
          },
          "400": {
            "description": "Validation failure"
          }
        },
        "security": [],
        "summary": "Start a device sign-in and get a code for the person to approve"
      }
    },
    "$AUTH_API/device/token": {
      "post": {
        "description": "Called by the device with its device_code until the person approves the sign-in. While approval is pending it answers 400 with code authorization_pending; after the code expires (5 minutes) it answers 400 with expired_token, and an unknown code returns 400. Once approved it answers 200 with access and refresh tokens for the context the person chose, or 202 with a challenge token when the person has two-factor authentication enabled; the device code can then not be used again. A person who was disabled or lost the chosen context in the meantime gets 403. Devices must wait at least the interval returned by startDeviceCode between polls; a poll sooner than that answers 400 with code slow_down (RFC 8628). It needs no authentication and is not available through the web application's session cookie flow.",
        "operationId": "pollDeviceToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "device_code": {
                    "description": "The device_code returned by startDeviceCode.",
                    "type": "string"
                  }
                },
                "required": [
                  "device_code"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "The approved device's session"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MFAChallenge"
                }
              }
            },
            "description": "A second factor is required; finish with POST $AUTH_API/login/2fa"
          },
          "400": {
            "description": "Approval pending (authorization_pending), code expired (expired_token), or unknown device code"
          },
          "403": {
            "description": "The person is disabled or the chosen context is no longer available"
          }
        },
        "security": [],
        "summary": "Poll for the session of an approved device sign-in"
      }
    },
    "$AUTH_API/invitations/accept": {
      "post": {
        "description": "Redeems a team invitation token and creates the membership it describes. If an identity already exists for the invited e-mail or phone, the password must match it (401 otherwise); if not, a new identity is created with the given password and full name, and the invited contact is marked as verified. Answers 200 with a session in the new membership, or 202 with a second-factor challenge when the identity has two-factor authentication enabled. An invalid, expired, revoked or already used token returns 401.",
        "operationId": "acceptInvitation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcceptInvitationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Accept a team invitation"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [],
        "summary": "Accept a team invitation"
      }
    },
    "$AUTH_API/login": {
      "post": {
        "description": "Authenticates an e-mail address or phone number with a password and opens a session in the requested context_id or, when omitted, the person's preferred context. Answers 200 with access and refresh tokens, or 202 with a challenge token when the person has two-factor authentication enabled, in which case the login is finished with loginTwoFactor. Unknown identifiers and wrong passwords both return 401; 403 is returned for a disabled identity, a person with no usable context, or an account that must sign in through its organization's identity provider (SSO_REQUIRED); repeated attempts return 429 with Retry-After.",
        "operationId": "login",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LoginRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Log in with e-mail or phone and password"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MFAChallenge"
                }
              }
            },
            "description": "A second factor is required; finish with POST $AUTH_API/login/2fa"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "409": {
            "description": "Conflict"
          },
          "429": {
            "description": "Too many attempts"
          }
        },
        "security": [],
        "summary": "Log in with e-mail or phone and password"
      }
    },
    "$AUTH_API/login/2fa": {
      "post": {
        "description": "Finishes a login that answered 202 by exchanging the challenge token and a 6-digit authenticator code or a recovery code for a session. The challenge expires after five minutes and allows five attempts; an invalid, expired or used challenge returns 401 with MFA_CHALLENGE_INVALID, a wrong code returns 400, and too many wrong codes lock the factor for 15 minutes (429 MFA_LOCKED). A recovery code can be used only once, and each outcome is recorded in the audit trail.",
        "operationId": "loginTwoFactor",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TwoFactorChallengeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Finish a challenged login with a TOTP or recovery code"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "429": {
            "description": "Too many attempts or locked (MFA_LOCKED)"
          }
        },
        "security": [],
        "summary": "Finish a challenged login with a TOTP or recovery code"
      }
    },
    "$AUTH_API/login/ldap": {
      "post": {
        "description": "Authenticates a username and password against the LDAP or Active Directory server that the workspace tenant_id has configured, maps the person's directory groups to roles, and creates or updates the person and their membership on first use. Answers 200 with access and refresh tokens, or 202 with a challenge token when the person has two-factor authentication enabled, finished with loginTwoFactor. Returns 400 when tenant_id, username or password is missing, 401 for wrong credentials or an unknown directory user, 403 when the workspace's directory login is disabled, the directory account is disabled or locked, the person must use single sign-on (SSO_REQUIRED), or a bot challenge is required or failed, 404 when the workspace has no directory connection, 429 after repeated attempts (with Retry-After) and 502 when the directory cannot be reached. Failed attempts are recorded in the workspace's audit trail. Through the web application's session cookie flow the tokens are kept in cookies and only user, contexts and active_context are returned.",
        "operationId": "loginLDAP",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LDAPLoginRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Directory login succeeded"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MFAChallenge"
                }
              }
            },
            "description": "A second factor is required; finish with POST $AUTH_API/login/2fa"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Invalid credentials"
          },
          "403": {
            "description": "Directory login disabled, directory account disabled, SSO required, or bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "404": {
            "description": "The workspace has no directory connection"
          },
          "429": {
            "description": "Too many attempts"
          },
          "502": {
            "description": "The directory server could not be reached"
          }
        },
        "security": [],
        "summary": "Log in with a workspace's directory (LDAP or Active Directory) account"
      }
    },
    "$AUTH_API/logout": {
      "post": {
        "description": "Ends the session behind the given refresh token by revoking its whole token family; access tokens of that session stop being accepted. An unknown refresh token is treated as already signed out and still answers 204. A missing refresh_token returns 400.",
        "operationId": "logout",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Revoke a session"
          },
          "400": {
            "description": "Validation failure"
          }
        },
        "security": [],
        "summary": "Revoke a session"
      }
    },
    "$AUTH_API/me": {
      "get": {
        "description": "Returns the signed-in person's profile, every context (workspace, organization or consumer membership) they can switch to, the organizations behind those contexts, and the active context with its roles and scopes. When the request is authenticated with an API key, the response also identifies the key by prefix, last four characters and mode. This call stays available while the active workspace is suspended or closed.",
        "operationId": "getCurrentUser",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CurrentUser"
                }
              }
            },
            "description": "Get the current user, contexts, roles and scopes"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the current user, contexts, roles and scopes"
      },
      "patch": {
        "description": "Changes the signed-in person's full name and preferred locale; fields left out or empty are kept as they are. The locale must be one the platform supports, otherwise 400. Returns the updated profile.",
        "operationId": "updateCurrentUser",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateProfileRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UserProfile"
                }
              }
            },
            "description": "Update the current user's profile"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update the current user's profile"
      }
    },
    "$AUTH_API/membership/current": {
      "delete": {
        "description": "Ends only the authenticated person's active membership. A last owner must provide another active member in the same context as successor; that member is promoted before the departure. When another context remains, the response is a new session for that context; otherwise signed_out is true.",
        "operationId": "leaveCurrentMembership",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "successor_member_id": {
                    "description": "Active membership that will become the new owner if the caller is the last owner",
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/AuthSession"
                    },
                    {
                      "properties": {
                        "signed_out": {
                          "const": true,
                          "type": "boolean"
                        }
                      },
                      "required": [
                        "signed_out"
                      ],
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Membership ended and session switched, or the person was signed out"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Membership is no longer active"
          },
          "409": {
            "description": "A successor must be appointed before the last owner can leave"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Leave the active account or organization"
      }
    },
    "$AUTH_API/oidc/{tenantID}/callback": {
      "get": {
        "description": "Receives the OpenID Connect provider's redirect after the person signs in there; it is called by the browser, not by API clients. Only the code and state query values are read, and the identity comes solely from the verified ID token. On completion the browser is redirected (303) to the sign-in completion page or the native app's redirect URI with a one-time code, or with an error when the login was refused; an unknown or expired state returns 401.",
        "operationId": "oidcCallback",
        "parameters": [
          {
            "description": "Identifier of the utility workspace whose OpenID Connect connection started the login; it must match the workspace stored with the login state.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "303": {
            "description": "Redirect carrying a one-time code"
          },
          "401": {
            "description": "Single sign-on failed"
          }
        },
        "security": [],
        "summary": "OIDC authorization response; identity comes only from the verified ID token"
      }
    },
    "$AUTH_API/organizations": {
      "post": {
        "description": "Creates an organization owned by the signed-in person and returns a new session switched into the organization context (201). The type must be one of utility, authority, operator, partner or group and a name is required, otherwise 400. Returns 429 when the person already belongs to the configured maximum number of organizations or creates accounts too quickly.",
        "operationId": "createOrganizationContext",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "name": {
                    "maxLength": 255,
                    "minLength": 1,
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "utility",
                      "authority",
                      "operator",
                      "partner",
                      "group"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "name",
                  "type"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Organization created and the person switched into its owner context"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "429": {
            "description": "Organization creation rate or per-person limit reached"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an organization for the signed-in person"
      }
    },
    "$AUTH_API/passkeys/register/finish": {
      "post": {
        "description": "Stores a passkey credential for the signed-in person using a challenge issued to that same person by beginPasskeyRegistration within the last 5 minutes; each challenge can be used once. Returns 400 (invalid passkey registration) when the challenge is unknown, expired, issued to someone else or already used, or when credential_id is empty, and 401 without a session. Answers 201. Registered passkeys cannot yet be used to sign in.",
        "operationId": "finishPasskeyRegistration",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "challenge": {
                    "description": "The challenge returned by beginPasskeyRegistration.",
                    "type": "string"
                  },
                  "credential_id": {
                    "description": "Credential identifier produced by the authenticator.",
                    "type": "string"
                  },
                  "label": {
                    "description": "Name the person gives the passkey, for example the device it lives on.",
                    "example": "Work laptop",
                    "type": "string"
                  },
                  "public_key": {
                    "description": "Public key of the credential, as produced by the authenticator.",
                    "type": "string"
                  }
                },
                "required": [
                  "challenge",
                  "credential_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "registered": {
                      "const": true,
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "registered"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Passkey registered"
          },
          "400": {
            "description": "Invalid passkey registration"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a passkey with a challenge from beginPasskeyRegistration"
      }
    },
    "$AUTH_API/passkeys/register/options": {
      "post": {
        "description": "Issues a registration challenge, valid for 5 minutes, together with the relying party and the person's user handle, name and display name, for the client to pass to the platform's passkey (WebAuthn) API. Finish with finishPasskeyRegistration. Passkeys cannot yet be used to sign in. Any signed-in person may call it for themselves; API keys are refused, and no body is read.",
        "operationId": "beginPasskeyRegistration",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PasskeyRegistrationOptions"
                }
              }
            },
            "description": "Registration challenge"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "404": {
            "description": "The signed-in person no longer exists"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a challenge to register a passkey for the signed-in person"
      }
    },
    "$AUTH_API/password": {
      "post": {
        "description": "Verifies the current password, sets the new one, and revokes every refresh token of the person, which signs out all their other sessions. The response is a fresh session in the active context, so the client must replace its stored tokens. A wrong current password returns 401 and a new password that fails the password rules returns 400.",
        "operationId": "changePassword",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePasswordRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Change the current user's password"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change the current user's password"
      }
    },
    "$AUTH_API/password/forgot": {
      "post": {
        "description": "Sends a password reset code by e-mail when the identifier is an e-mail address, or by text message when it is a phone number. It answers 202 whether or not an identity exists for the identifier, so it cannot be used to discover accounts. Repeated requests return 429.",
        "operationId": "forgotPassword",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IdentifierRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodeIssued"
                }
              }
            },
            "description": "Request a password reset code"
          },
          "400": {
            "description": "Validation failure"
          },
          "403": {
            "description": "Bot challenge required or failed for a UI request (CHALLENGE_REQUIRED / CHALLENGE_FAILED); API requests are not challenged (D9)"
          },
          "409": {
            "description": "Conflict"
          },
          "429": {
            "description": "Too many attempts"
          },
          "503": {
            "description": "No provider is configured for the channel of this identifier, outside development. Delivery failures are not reported, so the response does not reveal whether the account exists."
          }
        },
        "security": [],
        "summary": "Request a password reset code"
      }
    },
    "$AUTH_API/password/reset": {
      "post": {
        "description": "Sets a new password using the identifier and the reset code sent by forgotPassword, then revokes every session of the person. A wrong or expired code, or an unknown identifier, returns 400; a password that fails the password rules returns 400; repeated attempts return 429. Answers 204, after which the person must sign in again.",
        "operationId": "resetPassword",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResetPasswordRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Reset a password with a code"
          },
          "400": {
            "description": "Validation failure"
          },
          "409": {
            "description": "Conflict"
          },
          "429": {
            "description": "Too many attempts"
          }
        },
        "security": [],
        "summary": "Reset a password with a code"
      }
    },
    "$AUTH_API/phone-codes": {
      "post": {
        "description": "RFC 0104 §9. Answers the same whether or not the phone has an account. Limited per phone and per IP (RFC 0069). dev_code is returned only in development.",
        "operationId": "requestServiceRequestPhoneCode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "challenge_token": {
                    "description": "Bot-challenge token when security.challenge is enabled (anonymous callers). Only UI requests (browser headers, the dashboard, or X-Client mobile or desktop) are challenged; API requests never are.",
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  }
                },
                "required": [
                  "phone"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodeIssued"
                }
              }
            },
            "description": "Code sent"
          },
          "400": {
            "description": "Missing or invalid phone"
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "429": {
            "description": "Too many codes for this phone or address, or the current code is locked by wrong guesses; Retry-After header and params.retry_after_seconds say how long to wait"
          },
          "503": {
            "description": "No text-message provider is configured",
            "outside development.": null
          }
        },
        "security": [],
        "summary": "Send a code that proves a phone before an account-free service request"
      }
    },
    "$AUTH_API/refresh": {
      "post": {
        "description": "Exchanges a refresh token for a new access token and a new refresh token; the old refresh token is marked as rotated and cannot be used again. Presenting a token that was already rotated or revoked revokes the whole token family, signing out that session. Expired or idle tokens, disabled identities and memberships that no longer exist all return 401.",
        "operationId": "refreshSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RefreshRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Rotate a refresh token"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [],
        "summary": "Rotate a refresh token"
      }
    },
    "$AUTH_API/session": {
      "get": {
        "description": "Returns the person, the contexts they can switch to and the active context for the current session, so a client can restore its state on start-up. Called with a bearer access token it returns the same body as getCurrentUser. The web application may call it through the browser session cookie instead (sending X-Client: web and, optionally, X-Context-ID); that variant rotates the cookie when due and returns only user, contexts and active_context, and answers 403 with context_unavailable when the requested context is no longer available. API keys are refused. Returns 401 without a valid session.",
        "operationId": "getSession",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CurrentSessionView"
                }
              }
            },
            "description": "The session's user and contexts"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The requested context is no longer available, or an API key was used"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Restore the signed-in session's user and contexts"
      }
    },
    "$AUTH_API/session/fork": {
      "post": {
        "description": "Creates a new refresh family for a browser tab without changing the authenticated context.",
        "operationId": "forkSession",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Open an independent session in the current context"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open an independent session in the current context"
      }
    },
    "$AUTH_API/sessions": {
      "get": {
        "description": "Lists the signed-in person's live sessions across all their contexts, with the current session flagged so a client can tell it apart. Revoked, expired and idle sessions are not included.",
        "operationId": "getSessions",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionList"
                }
              }
            },
            "description": "List the current user sessions"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the current user sessions"
      }
    },
    "$AUTH_API/sessions/revoke-others": {
      "post": {
        "description": "Ends every session of the signed-in person except the one making the request, and returns how many sessions were revoked. Their access tokens stop being accepted on the next request. An audit event is recorded.",
        "operationId": "revokeOtherSessions",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RevokedCount"
                }
              }
            },
            "description": "End every other session of the current user"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "End every other session of the current user"
      }
    },
    "$AUTH_API/sessions/{id}": {
      "delete": {
        "description": "Ends one of the signed-in person's own sessions; its tokens stop being accepted on the next request. A session that belongs to someone else returns 404, as does an unknown one. Answers 204 and records an audit event.",
        "operationId": "revokeSession",
        "parameters": [
          {
            "description": "Identifier of the session to end, as listed by getSessions.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "End one of the current user sessions"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "End one of the current user sessions"
      }
    },
    "$AUTH_API/setup": {
      "get": {
        "description": "Tells a client whether the platform still needs its first platform owner, so a fresh installation can show the setup screen instead of the sign-in screen. It needs no authentication. In development mode, while setup is still required, the response also carries the one-time setup code.",
        "operationId": "getPlatformSetupStatus",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "dev_code": {
                      "type": "string"
                    },
                    "required": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "required"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Setup status. dev_code is only present in development."
          }
        },
        "security": [],
        "summary": "Whether the installation still needs its first platform owner"
      },
      "post": {
        "description": "Returns a session, as login does. The setup code is generated at server start while no platform owner exists; each start rotates it. The first boot writes it to the server log once, inside a one-time setup link `{dashboard external URL}/setup#code=<code>` (or, when no dashboard external URL is configured, the address of the listener that serves the dashboard). The code sits in the URL fragment, which browsers never send, so it does not reach request logs; the setup screen reads it from the fragment and sends it here as setup_code. Once a platform owner exists the code is never logged again. Rate limited.",
        "operationId": "completePlatformSetup",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "email": {
                    "type": "string"
                  },
                  "full_name": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string"
                  },
                  "phone": {
                    "type": "string"
                  },
                  "setup_code": {
                    "type": "string"
                  }
                },
                "required": [
                  "setup_code",
                  "full_name",
                  "password"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "First platform owner created"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Wrong or expired setup code"
          },
          "409": {
            "description": "A platform owner already exists, or the e-mail or phone is already registered. When two requests race, the loser receives this."
          },
          "429": {
            "description": "Too many attempts"
          }
        },
        "security": [],
        "summary": "Create the first platform owner with the one-time setup code"
      }
    },
    "$AUTH_API/signup/consumer": {
      "post": {
        "description": "Creates a consumer identity with an e-mail address or phone number, full name and password, and returns a session in the consumer context (201). A verification code is sent to the given contact; if it could not be delivered the identity still exists and verification_delivery_failed is set. Returns 409 when the e-mail or phone is already in use, 400 for invalid input, and 429 when too many signups come from the same address.",
        "operationId": "signupConsumer",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SignupConsumerRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Self-service consumer signup"
          },
          "400": {
            "description": "Validation failure"
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "409": {
            "description": "Conflict"
          },
          "429": {
            "description": "Too many attempts"
          },
          "503": {
            "description": "No e-mail or text-message provider can reach the given contact outside development; nothing is created."
          }
        },
        "security": [],
        "summary": "Self-service consumer signup"
      }
    },
    "$AUTH_API/signup/utility": {
      "post": {
        "description": "Registers a new utility organization, its first workspace and its owner in one step, and returns a session in that workspace (201); a default sandbox workspace is also created. organization_name, full_name, a password and an e-mail or phone are required, and an optional plan_code must name a published plan. Without plan_code the workspace gets the server's default plan (the published free plan, else the published plan with a trial); with no such plan it has no subscription and the sign-up audit event records why (no_published_default_plan). The default sandbox (the test account with sample data, whose last full month is read but not yet billed) is created for every self sign-up. Returns 409 when the contact is already in use, 403 with ACCOUNT_CREATION_REVIEW_REQUIRED when the signup needs manual review, 429 when rate limited, and 400 when utility signup is not configured. A verification code is sent to the owner's contact.",
        "operationId": "signupUtility",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SignupUtilityRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Self-service signup of a utility with its owner",
            "headers": {
              "X-First-Run-Token": {
                "description": "Opaque run token of the test-account tour this sign-up starts; send it back in X-First-Run-Token on tour requests. It carries no identity.",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "description": "Validation failure"
          },
          "403": {
            "description": "Creation risk exceeded the configured threshold and needs manual review, or bot challenge required/failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "409": {
            "description": "E-mail or phone already registered, or the utility name or slug is taken. A taken name or slug names the field in invalid_params (organization_name, tenant_name or tenant_slug)."
          },
          "429": {
            "description": "Too many attempts"
          },
          "503": {
            "description": "No e-mail or text-message provider can reach the given contact outside development; nothing is created."
          }
        },
        "security": [],
        "summary": "Self-service signup of a utility with its owner"
      }
    },
    "$AUTH_API/sso/complete": {
      "get": {
        "description": "Serves the small HTML page that a web single sign-on login lands on; it is opened by the browser, not called by API clients. The one-time code arrives in the URL fragment, which never reaches the server, and the page script posts it to the exchange endpoint before sending the person to the application. The page is sent with no-store caching, a strict Content Security Policy and framing denied.",
        "operationId": "ssoComplete",
        "responses": {
          "200": {
            "description": "HTML page"
          }
        },
        "security": [],
        "summary": "Web page that redeems the one-time code from its URL fragment"
      }
    },
    "$AUTH_API/sso/exchange": {
      "post": {
        "description": "Exchanges the one-time code from a completed single sign-on login for an access token and refresh token. The code_verifier must be the PKCE verifier whose S256 challenge was sent to startSSO; a missing verifier returns 400 and a wrong verifier or an unknown, used or expired code (codes live for one minute) returns 401. A disabled identity or membership returns 403. The response is sent with Cache-Control: no-store and the login is recorded in the audit trail.",
        "operationId": "exchangeSSOCode",
        "responses": {
          "200": {
            "description": "The application session"
          },
          "401": {
            "description": "Invalid, expired or already used code"
          }
        },
        "security": [],
        "summary": "Trade a one-time code for application tokens"
      }
    },
    "$AUTH_API/sso/logout": {
      "post": {
        "description": "Ends the signed-in person's sessions in the active workspace. When that workspace uses a SAML connection with Single Logout and the person signed in through it, the response carries logout_url, where the client should send the browser to finish logout at the identity provider; otherwise logout_url is absent. Outside a workspace context it does nothing and returns an empty result.",
        "operationId": "ssoLogout",
        "responses": {
          "200": {
            "description": "Logout result"
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "security": [],
        "summary": "End the caller's sessions in the active tenant and return the IdP logout URL when there is one"
      }
    },
    "$AUTH_API/sso/lookup": {
      "get": {
        "description": "Tells a sign-in screen whether the domain of an e-mail address routes to a single sign-on connection, using the required domain query value. Only verified domains of enabled connections match; when one does, the response gives the workspace ID, provider type (oidc or saml), connection name and whether password login is blocked for that domain. Otherwise it answers 200 with sso_enabled false; it needs no authentication.",
        "operationId": "lookupSSO",
        "parameters": [
          {
            "description": "E-mail domain to look up, the part after the @ (for example example.test). Without it the call answers 400.",
            "example": "example.test",
            "in": "query",
            "name": "domain",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Whether the domain signs in through SSO"
          },
          "400": {
            "description": "The domain value is missing (RFC 7807)"
          }
        },
        "security": [],
        "summary": "Find the SSO connection of a verified e-mail domain"
      }
    },
    "$AUTH_API/sso/{tenantID}/start": {
      "get": {
        "description": "Begins a single sign-on login for a workspace and redirects the browser (303) to its identity provider. Every client must send code_challenge (a 43-character S256 PKCE challenge) with code_challenge_method=S256, otherwise 400; native apps also send an allow-listed redirect_uri and an optional state, which are returned when the login completes. Returns 404 when the workspace has no enabled connection, 401 when its domain is not verified, and 429 when rate limited. The login state is valid for 10 minutes.",
        "operationId": "startSSO",
        "parameters": [
          {
            "description": "Identifier of the utility workspace whose single sign-on connection to use, as returned by lookupSSO.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "303": {
            "description": "Redirect to the identity provider"
          },
          "404": {
            "description": "SSO is not available"
          }
        },
        "security": [],
        "summary": "Open a browser single sign-on session; native clients pass redirect_uri and an S256 code_challenge"
      }
    },
    "$AUTH_API/switch": {
      "post": {
        "description": "Issues a new session in another context (workspace, organization or consumer membership) that the signed-in person holds, given its context_id. Sending the current refresh_token also signs out the old session. If the target workspace requires a fresh second factor on switch, the call returns 401 step_up_required until step_up_code is supplied, or 403 MFA_ENROLLMENT_REQUIRED when the person has no authenticator set up; an unknown or inactive context returns 403. The switch is recorded in the audit trail.",
        "operationId": "switchContext",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SwitchContextRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuthSession"
                }
              }
            },
            "description": "Open a session in another context of the user"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a session in another context of the user"
      }
    },
    "$AUTH_API/utilities": {
      "get": {
        "description": "Unauthenticated and rate limited per client. Lists only active tenants with approved onboarding, and discloses only the tenant identifier, display name and locality. Locality is the utility's service-area names.",
        "operationId": "listPublicUtilities",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Search utility name",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "properties": {
                          "display_name": {
                            "type": "string"
                          },
                          "locality": {
                            "type": "string"
                          },
                          "tenant_id": {
                            "type": "string"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Utilities"
          },
          "429": {
            "description": "Rate limited"
          }
        },
        "security": [],
        "summary": "Public directory of utilities a consumer can link to"
      }
    },
    "$AUTH_API/utility-invitations/accept": {
      "post": {
        "description": "The sign-in form of POST $PUBLIC_API/utility-invitations/accept, for browsers and other clients that sign in through the auth mount. It consumes the token the same way and answers with the session fields (tokens included) at the top level beside invitation_state, setup_mode, handover and, for a utility the platform set up, handover_summary. On the dashboard listener this is a session route: the refresh token goes into the session cookie and the body carries no tokens (only user, contexts, active_context and the invitation fields). Replays, expired and revoked tokens return 410.",
        "operationId": "acceptUtilityInvitationSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UtilityInvitationAccept"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitationAcceptSession"
                }
              }
            },
            "description": "Accepted and signed in"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing name, weak password, or a password that does not match the existing account"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The contact is already used"
          },
          "410": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Expired, revoked or used"
          }
        },
        "security": [],
        "summary": "Accept a utility invitation and sign the owner in"
      }
    },
    "$AUTH_API/verify/email/confirm": {
      "post": {
        "description": "Marks an e-mail address as verified using the code sent by requestEmailVerification. Both email and code are required; a wrong, expired or used code returns 400 and repeated attempts return 429.",
        "operationId": "confirmEmailVerification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailVerificationConfirm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                }
              }
            },
            "description": "Confirm an e-mail verification code"
          },
          "400": {
            "description": "Validation failure"
          }
        },
        "security": [],
        "summary": "Confirm an e-mail verification code"
      }
    },
    "$AUTH_API/verify/email/request": {
      "post": {
        "description": "Sends a verification code to an e-mail address. It answers 202 whether or not the address belongs to an identity, so it reveals nothing about registration. Returns 400 when email is missing or invalid and 429 when rate limited; in development mode the code is also returned as dev_code.",
        "operationId": "requestEmailVerification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EmailVerificationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodeIssued"
                }
              }
            },
            "description": "Send an e-mail verification code"
          },
          "400": {
            "description": "Validation failure"
          },
          "403": {
            "description": "Bot challenge required or failed for a UI request (CHALLENGE_REQUIRED / CHALLENGE_FAILED); API requests are not challenged (D9)"
          },
          "409": {
            "description": "Conflict"
          },
          "429": {
            "description": "Too many attempts"
          },
          "503": {
            "description": "No e-mail provider is configured, outside development."
          }
        },
        "security": [],
        "summary": "Send an e-mail verification code"
      }
    },
    "$AUTH_API/verify/phone/confirm": {
      "post": {
        "description": "Marks a phone number as verified using the code sent by requestPhoneVerification. Both phone and code are required; a wrong, expired or used code returns 400 and repeated attempts return 429.",
        "operationId": "confirmPhoneVerification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneVerificationConfirm"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VerificationResult"
                }
              }
            },
            "description": "Confirm a phone verification code"
          },
          "400": {
            "description": "Validation failure"
          }
        },
        "security": [],
        "summary": "Confirm a phone verification code"
      }
    },
    "$AUTH_API/verify/phone/request": {
      "post": {
        "description": "Sends a verification code by text message to a phone number. It answers 202 whether or not the number belongs to an identity, so it reveals nothing about registration. Returns 400 when phone is missing or invalid and 429 when rate limited; in development mode the code is also returned as dev_code.",
        "operationId": "requestPhoneVerification",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PhoneVerificationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CodeIssued"
                }
              }
            },
            "description": "Send a phone verification code"
          },
          "400": {
            "description": "Validation failure"
          },
          "403": {
            "description": "Bot challenge required or failed for a UI request (CHALLENGE_REQUIRED / CHALLENGE_FAILED); API requests are not challenged (D9)"
          },
          "409": {
            "description": "Conflict"
          },
          "429": {
            "description": "Too many attempts"
          },
          "503": {
            "description": "No text-message provider is configured, outside development."
          }
        },
        "security": [],
        "summary": "Send a phone verification code"
      }
    },
    "/auth/saml/acs/{tenantID}": {
      "post": {
        "description": "SAML assertion consumer service: receives the identity provider's HTTP-POST form with SAMLResponse and RelayState after the person signs in there; it is called by the browser, not by API clients. RelayState is the one-time login state created by startSSO, and the assertion is verified against the workspace's connection before the person is provisioned or signed in. The browser is then redirected (303) to the completion page or native redirect URI with a one-time code, or with an error. A missing field returns 400 and an unknown or expired RelayState returns 401; the form body is limited to 2 MiB.",
        "operationId": "samlACS",
        "parameters": [
          {
            "description": "Identifier of the utility workspace whose SAML connection is used; it must match the workspace stored with the login state named by RelayState.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "303": {
            "description": "Redirect carrying a one-time code"
          },
          "401": {
            "description": "Single sign-on failed"
          }
        },
        "security": [],
        "summary": "SAML assertion consumer service; RelayState names the pending login. /auth/saml/acs selects the tenant from RelayState alone"
      }
    },
    "/auth/saml/metadata/{tenantID}": {
      "get": {
        "description": "Returns the service provider metadata XML (Content-Type application/samlmetadata+xml) that a workspace administrator gives to their identity provider, including the entity ID and the assertion consumer and logout URLs for that workspace. It needs no authentication. Returns 404 when the workspace has no SAML connection.",
        "operationId": "samlMetadata",
        "parameters": [
          {
            "description": "Identifier of the utility workspace whose SAML connection the metadata describes.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Metadata XML"
          },
          "404": {
            "description": "SSO is not available"
          }
        },
        "security": [],
        "summary": "SAML service provider metadata. /auth/saml/metadata?tenant_id= also works"
      }
    },
    "/auth/saml/slo/{tenantID}": {
      "post": {
        "description": "SAML Single Logout endpoint for the identity provider. A signed LogoutRequest ends the sessions of the federated person in this workspace and, when the connection has an IdP logout URL, redirects (303) back with a LogoutResponse; otherwise it answers 204. A LogoutResponse finishing a logout started here redirects the browser to the completion page. Invalid or unsigned messages return 401 and a workspace without an enabled SAML connection returns 404.",
        "operationId": "samlSingleLogout",
        "parameters": [
          {
            "description": "Identifier of the utility workspace whose SAML connection sent the logout message.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "303": {
            "description": "Logout response to the identity provider"
          },
          "401": {
            "description": "Invalid or unsigned logout message"
          }
        },
        "security": [],
        "summary": "SAML Single Logout, HTTP-POST and HTTP-Redirect (GET) bindings"
      }
    },
    "$BUSINESS_API/account-invitations/bulk": {
      "post": {
        "description": "Issues one invitation code per item, each for the account named by its account_id and sent to exactly one phone or e-mail, with holder permissions unless others are given. Between 1 and 500 items are accepted; each item gets its own result with either the invitation or an error (unknown account, invalid recipient, no delivery channel, or delivery failure), so one bad item does not fail the batch. Invitations that could not be delivered within the request are revoked and reported as errors. Requires the business:accounts:invitations:create permission.",
        "operationId": "createBulkAccountInvitations",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BulkInvitationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Per-account results"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create invitations for many accounts and send them; per-item results (a delivery failure appears as the item's error)",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:invitations:create"
        ]
      }
    },
    "$BUSINESS_API/account-link-requests": {
      "get": {
        "description": "Returns the workspace's queue of requests from people asking to be linked to a customer account. By default only pending requests are listed; status accepts pending, approved, rejected or cancelled. Results are paginated with limit (default 20, maximum 100) and the after cursor. Requires the business:accounts:link-requests:read permission.",
        "operationId": "listAccountLinkRequests",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "pending (default), approved or rejected",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLinkRequestPage"
                }
              }
            },
            "description": "Link requests"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue of consumer link requests",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:link-requests:read"
        ]
      }
    },
    "$BUSINESS_API/account-link-requests/{id}/approve": {
      "post": {
        "description": "Approves a pending link request and, in the same change, gives the requesting person an active holder membership on the account with the standard holder permissions. Returns the updated request. A request already decided returns 409, and one from another workspace returns 404. Requires the business:accounts:link-requests:decide permission.",
        "operationId": "approveAccountLinkRequest",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLinkRequest"
                }
              }
            },
            "description": "Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve a link request, creating the membership",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:link-requests:decide"
        ]
      }
    },
    "$BUSINESS_API/account-link-requests/{id}/reject": {
      "post": {
        "description": "Refuses a resident's pending request to link a service account to their identity, recording the reason, the staff member who decided and the time. No account membership is created, and the request keeps the reason so the resident can see why. A missing reason returns 400; a request of another utility, or one without a matched account, returns 404. Requires business:accounts:link-requests:decide.",
        "operationId": "rejectAccountLinkRequest",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReasonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLinkRequest"
                }
              }
            },
            "description": "Request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a link request",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:link-requests:decide"
        ]
      }
    },
    "$BUSINESS_API/accounts": {
      "get": {
        "description": "Lists the service accounts of the caller's workspace, optionally filtered by customer, property, status and a free-text q search. Results are paginated with limit (default 20, maximum 100) and the after cursor; a negative or non-numeric limit returns 400. Requires the business:accounts:read permission.",
        "operationId": "listBusinessAccounts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "description": "Customer identifier; when set, only accounts belonging to that customer are returned.",
            "in": "query",
            "name": "customer_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Property identifier; when set, only accounts opened for that property are returned.",
            "in": "query",
            "name": "property_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Account status to keep: active, suspended or closed; when omitted, accounts in every status are returned.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "active",
                "suspended",
                "closed"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountPage"
                }
              }
            },
            "description": "Utility accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List service and billing accounts for the utility tenant",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:accounts:read"
        ]
      },
      "post": {
        "description": "Opens a service account for a customer at one of that customer's properties in the caller's workspace. Both customer_id and property_id are required (400 otherwise); either one missing returns 404, and a property that belongs to a different customer returns 409. The account starts active and receives the next number from the workspace's gap-free account number series. Requires the business:accounts:create permission.",
        "operationId": "createBusinessAccount",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAccount"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            },
            "description": "Account opened"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a billing/service account",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:create"
        ]
      }
    },
    "$BUSINESS_API/accounts/{account_id}/invitations": {
      "get": {
        "description": "Lists the invitations issued for one account, each with a status derived at request time (for example pending, accepted, revoked or expired). Results are paginated with limit (default 20, maximum 100) and the after cursor. Returns 404 when the account is not in the caller's workspace; requires the business:accounts:invitations:read permission.",
        "operationId": "listAccountInvitations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountInvitationPage"
                }
              }
            },
            "description": "Invitations"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List invitations with derived status",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:invitations:read"
        ]
      },
      "post": {
        "description": "Issues an 8-character, single-use invitation code that lets a person link themselves to this account, and sends it to exactly one phone (at least 9 digits) or e-mail address. Permissions default to the holder permissions; expires_in_hours defaults to 168 (7 days) and must be between 1 and 720. Returns 503 when the recipient's channel has no delivery provider; if sending fails the invitation is revoked and the error returned. Requires the business:accounts:invitations:create permission.",
        "operationId": "createAccountInvitation",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvitationInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountInvitation"
                }
              }
            },
            "description": "Invitation including its code, shown only once to the staff member who created it. The code is also sent to the recipient by e-mail or text message. Outside development with no provider for the recipient, the request fails with 503."
          },
          "503": {
            "description": "The invitation could not be sent to the recipient: no provider for the target, or the provider failed. No usable invitation remains."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a short, expiring, single-use invitation code",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:invitations:create"
        ]
      }
    },
    "$BUSINESS_API/accounts/{account_id}/invitations/{invitation_id}": {
      "delete": {
        "description": "Withdraws an invitation so its code can no longer be redeemed. Only invitations that are still pending can be revoked; an accepted or already revoked invitation returns 409, and an invitation that belongs to another account returns 404. Answers 204; requires the business:accounts:invitations:revoke permission.",
        "operationId": "revokeAccountInvitation",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "invitation_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a pending invitation",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:invitations:revoke"
        ]
      }
    },
    "$BUSINESS_API/accounts/{account_id}/memberships": {
      "get": {
        "description": "Each membership also carries display_name, masked_phone and masked_email when the identity is known; contact details are masked.",
        "operationId": "listAccountMembershipsOfAccount",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by identity",
            "in": "query",
            "name": "identity_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Set to true to include revoked memberships",
            "in": "query",
            "name": "include_revoked",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Memberships"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List identities linked to an account",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:memberships:read"
        ]
      },
      "post": {
        "description": "Links an identity directly to an account with the given permissions, without an invitation. identity_id and at least one valid permission are required, and expires_at, when set, must be in the future (400 otherwise); the account must exist in the caller's workspace (404). The membership is a holder membership when the permissions include inviting members, and a delegate membership otherwise. Requires the business:accounts:memberships:create permission.",
        "operationId": "createAccountMembership",
        "parameters": [
          {
            "description": "Identifier of the service account in the caller's workspace that the identity is linked to.",
            "in": "path",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAccountMembership"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Account membership created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Grant a consumer explicit account permissions",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:memberships:create"
        ]
      }
    },
    "$BUSINESS_API/accounts/{account_id}/memberships/{identity_id}": {
      "delete": {
        "description": "Ends an identity's membership on an account. Staff of the workspace need the business:accounts:memberships:revoke permission; a person may also remove their own membership, which is recorded as left by the person rather than revoked by the utility. Returns 404 when no active membership matches; answers 204.",
        "operationId": "revokeAccountMembership",
        "parameters": [
          {
            "description": "Identifier of the service account the membership belongs to.",
            "in": "path",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the identity (person) whose membership on the account is ended.",
            "in": "path",
            "name": "identity_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Membership revoked"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a consumer's account membership",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:accounts:memberships:revoke"
        ]
      }
    },
    "$BUSINESS_API/accounts/{id}": {
      "get": {
        "description": "Returns one service account of the caller's workspace, including its number, customer, property, billing entity, status and opening date. An account from another workspace returns 404. Requires the business:accounts:read permission.",
        "operationId": "getBusinessAccount",
        "parameters": [
          {
            "description": "Identifier of the service account to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            },
            "description": "Utility account"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an account in the authenticated utility tenant",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:accounts:read"
        ]
      }
    },
    "$BUSINESS_API/accounts/{id}/credits": {
      "get": {
        "description": "grants lists every grant of the account, pending_approval and rejected ones included, newest first; the totals count only active grants with money left.",
        "operationId": "getAccountCredits",
        "parameters": [
          {
            "description": "Identifier of the service account in the caller's workspace whose credit balance is returned.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "account_id": {
                      "type": "string"
                    },
                    "cash_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "granted_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "grants": {
                      "items": {
                        "$ref": "#/components/schemas/CreditGrant"
                      },
                      "type": "array"
                    },
                    "next_expiry": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "promotional_minor": {
                      "format": "int64",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "account_id",
                    "currency",
                    "cash_minor",
                    "granted_minor",
                    "promotional_minor",
                    "grants"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Account credit balance summary"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get account credit balance and grants",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/accounts/{id}/metadata": {
      "get": {
        "description": "Returns the custom key-value metadata stored on a service account, as a map of string keys to string values. The account must exist in the caller's workspace, otherwise 404. Requires the business:metadata:read permission.",
        "operationId": "getBusinessAccountMetadata",
        "parameters": [
          {
            "description": "Identifier of the service account whose metadata is returned (at most 120 characters).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a account",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the given keys into the account's metadata and returns the full resulting map: keys sent with a value are added or replaced, keys sent with an empty string are deleted, and keys not mentioned are kept. At most 50 keys may be sent at once; keys must be non-blank, at most 40 characters, without square brackets or control characters, and values at most 500 characters, otherwise 400 lists each invalid field. The account must exist in the caller's workspace (404 otherwise); requires the business:metadata:write permission.",
        "operationId": "putBusinessAccountMetadata",
        "parameters": [
          {
            "description": "Identifier of the service account whose metadata is changed (at most 120 characters).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/adjustments": {
      "get": {
        "description": "Returns the credit notes and debit notes recorded against invoices across the tenant, newest first, with cursor pagination (limit defaults to 20, at most 100; pass next_cursor as after). Narrow the list with account_id, invoice_id or type (credit_note or debit_note). Requires invoices:read.",
        "operationId": "listAdjustments",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice adjustments"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List invoice billing adjustments",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/alarm-rules": {
      "get": {
        "description": "Returns the tenant's alarm rules, both active and inactive, newest first, with cursor pagination (limit defaults to 20, at most 100). Each rule carries its source, comparison, threshold, clear threshold, severity and whether it is currently evaluated.",
        "operationId": "listAlarmRules",
        "parameters": [
          {
            "description": "Return only rules that watch this source: telemetry (sensor readings) or quality (water quality sample results); omit to return both.",
            "in": "query",
            "name": "source",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlarmRuleList"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List alarm rules",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      },
      "post": {
        "description": "A telemetry rule needs a sensor_id that exists in the tenant, and a quality rule needs a known water quality parameter. comparison must be above or below; an alarm opens when a value crosses threshold and closes automatically only when a value returns past clear_threshold, which defaults to threshold and must sit on the safe side of it. severity defaults to warning (critical, warning or info) and event_type to alarm.opened; the rule is created active and returns 201, with 400 for any failed check.",
        "operationId": "createAlarmRule",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAlarmRuleRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlarmRule"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a threshold rule with hysteresis",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:alarms:manage"
        ]
      }
    },
    "$BUSINESS_API/alarm-rules/{id}": {
      "get": {
        "description": "Returns one alarm rule of the tenant with its thresholds, severity, notification phones and active flag. Answers 404 when the rule does not exist in the caller's tenant.",
        "operationId": "getAlarmRule",
        "parameters": [
          {
            "description": "Identifier of the alarm rule, as returned when it was created (prefix mrl_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlarmRule"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an alarm rule",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/alarm-rules/{id}/activate": {
      "post": {
        "description": "Marks the rule active so new telemetry readings or quality results are evaluated against it again, and returns the updated rule. The call is idempotent: activating an active rule only refreshes its update time. Existing alarms are not changed.",
        "operationId": "activateAlarmRule",
        "parameters": [
          {
            "description": "Identifier of the alarm rule to activate (prefix mrl_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlarmRule"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate a rule",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:alarms:manage"
        ]
      }
    },
    "$BUSINESS_API/alarm-rules/{id}/deactivate": {
      "post": {
        "description": "Marks the rule inactive so incoming readings and results no longer open, update or auto-clear alarms for it, and returns the updated rule. Alarms it already opened stay as they are and can still be acknowledged or resolved by hand. The call is idempotent.",
        "operationId": "deactivateAlarmRule",
        "parameters": [
          {
            "description": "Identifier of the alarm rule to deactivate (prefix mrl_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlarmRule"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Deactivate a rule",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:alarms:manage"
        ]
      }
    },
    "$BUSINESS_API/alarms": {
      "get": {
        "description": "Returns the tenant's alarms, newest first, with cursor pagination (limit defaults to 20, at most 100; pass next_cursor as after). Filters combine, so you can ask for the open alarms of one rule at one sensor.",
        "operationId": "listAlarms",
        "parameters": [
          {
            "description": "Return only alarms in this state: open, acknowledged or resolved; omit for all states.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only alarms raised by this alarm rule (prefix mrl_).",
            "in": "query",
            "name": "rule_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only alarms raised at this location: the sensor ID for telemetry rules, or the asset or DMA ID of the sample for quality rules.",
            "in": "query",
            "name": "sensor_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AlarmList"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List alarms",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/alarms/{id}": {
      "get": {
        "description": "Returns one alarm with its current, peak and unit values, timestamps for opening, last observation, acknowledgement and resolution, and the resolution notes or code (auto-cleared alarms carry a resolution code). Answers 404 when the alarm is not in the caller's tenant.",
        "operationId": "getAlarm",
        "parameters": [
          {
            "description": "Identifier of the alarm (prefix alm_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Alarm"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an alarm",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/alarms/{id}/acknowledge": {
      "post": {
        "description": "Moves an open alarm to acknowledged and records who acknowledged it and when. Acknowledging an alarm that is already acknowledged returns it unchanged; acknowledging a resolved alarm answers 409. The alarm can still auto-clear or be resolved afterwards.",
        "operationId": "acknowledgeAlarm",
        "parameters": [
          {
            "description": "Identifier of the alarm to acknowledge (prefix alm_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Alarm"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Acknowledge an open alarm",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:alarms:manage"
        ]
      }
    },
    "$BUSINESS_API/alarms/{id}/resolve": {
      "post": {
        "description": "Closes an open or acknowledged alarm by hand, stamping the resolution time and storing the optional notes from the body (the body may be omitted). Resolving an alarm that is already resolved returns it unchanged. A later breach of the same rule at the same location opens a new alarm.",
        "operationId": "resolveAlarm",
        "parameters": [
          {
            "description": "Identifier of the alarm to resolve (prefix alm_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Alarm"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Close an alarm with optional notes",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:alarms:manage"
        ]
      }
    },
    "$BUSINESS_API/assets": {
      "get": {
        "description": "Returns the tenant's water network assets with cursor pagination (limit defaults to 20, at most 100). Filter by asset_type, status or service_area_id, and use q to match a substring of the asset name or code. Requires network:read.",
        "operationId": "listAssets",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkAssetPage"
                }
              }
            },
            "description": "Network assets"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List water network assets",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "post": {
        "description": "Registers a network asset such as a reservoir, pump station, pipe, valve or hydrant. code, name and asset_type are required, and status defaults to operational. The code must be unique within the tenant: a duplicate answers 409. Requires network:write and returns 201 with the stored asset.",
        "operationId": "createAsset",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAssetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkAsset"
                }
              }
            },
            "description": "Network asset registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a water network asset",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/assets/{id}": {
      "get": {
        "description": "Returns one network asset with its type, status, service area, capacity, coordinates, elevation, installation date and free-form properties. Answers 404 when the asset is not in the caller's tenant. Requires network:read.",
        "operationId": "getAsset",
        "parameters": [
          {
            "description": "Identifier of the network asset (prefix ast_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkAsset"
                }
              }
            },
            "description": "Network asset details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get network asset details",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "put": {
        "description": "Changes only the fields you send: name, status, capacity, latitude, longitude, elevation, installation_date and properties. Empty strings and zero numbers are treated as not sent, so this call cannot clear a field or set a coordinate to exactly 0, and properties is replaced as a whole when present. Code, type and service area cannot be changed here. Requires network:write; 404 when the asset is not in the tenant.",
        "operationId": "updateAsset",
        "parameters": [
          {
            "description": "Identifier of the network asset to update (prefix ast_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateAssetRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NetworkAsset"
                }
              }
            },
            "description": "Network asset updated"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a water network asset",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/audit/export": {
      "get": {
        "description": "Streams every audit event of the tenant between from and to, oldest first, as a file download (Content-Disposition attachment). Response headers carry the SHA-256 of the exact bytes returned, a signature over that digest, the event count and the hash of the last event in the chain, so a recipient can check the file with sha256sum and confirm the signature through the export verify endpoint. The range must not exceed 366 days and may hold at most 200,000 events; otherwise the call answers 400 and you should narrow it. Requires audit:read.",
        "operationId": "exportAuditEvents",
        "parameters": [
          {
            "description": "Required start of the export window as an RFC 3339 timestamp (for example 2026-01-01T00:00:00Z); it must be before to.",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Required end of the export window as an RFC 3339 timestamp; the window may span at most 366 days.",
            "in": "query",
            "name": "to",
            "required": true,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Output format: jsonl (one JSON event per line, the default) or csv (header row plus one row per event, with details as a JSON string and the prev_hash and hash columns).",
            "in": "query",
            "name": "format",
            "schema": {
              "enum": [
                "csv",
                "jsonl"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Exported events"
          },
          "400": {
            "description": "Missing or invalid range"
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "security": [],
        "summary": "Time-bounded audit export in CSV or JSONL with a SHA-256 digest header"
      }
    },
    "$BUSINESS_API/audit/export/verify": {
      "post": {
        "description": "Confirms that a digest and signature taken from the headers of an audit export (GET $BUSINESS_API/audit/export) were issued by this server for the caller's tenant, so a recipient can trust a file whose SHA-256 they computed themselves. Send sha256 as the bare hexadecimal digest (without the \"sha256=\" prefix the X-Audit-Digest header carries) and signature as returned, with or without its \"sha256=\" prefix. The answer is 200 with valid true or false; a mismatch is not an error. Both fields are required (400). Requires audit:read.",
        "operationId": "verifyAuditExport",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "sha256": {
                    "description": "Hexadecimal SHA-256 of the exported file, without a prefix.",
                    "example": "9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08",
                    "minLength": 1,
                    "type": "string"
                  },
                  "signature": {
                    "description": "Signature from the export response headers; a leading \"sha256=\" is accepted.",
                    "example": "sha256=4b8e1c0f2a9d6e7b3c5a1f0e9d8c7b6a5f4e3d2c1b0a99887766554433221100",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "sha256",
                  "signature"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditExportVerification"
                }
              }
            },
            "description": "Verification result"
          },
          "400": {
            "description": "sha256 or signature missing, or the body is not JSON (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing audit:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check that an audit export's signature was issued by this installation",
        "x-roles": [
          "admin",
          "analyst",
          "owner"
        ],
        "x-scopes": [
          "audit:read"
        ]
      }
    },
    "$BUSINESS_API/automation-triggers": {
      "get": {
        "description": "Returns every trigger event a rule can use, each with a description, the fields its conditions can test and, where available, a sample payload. Rule editors use it to build trigger and condition pickers, and a rule whose trigger.type is not in this catalogue is rejected on create and update. Requires automations:read.",
        "operationId": "listAutomationTriggers",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "properties": {
                          "description": {
                            "type": "string"
                          },
                          "event": {
                            "type": "string"
                          },
                          "fields": {
                            "items": {
                              "properties": {
                                "description": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "type": {
                                  "type": "string"
                                }
                              },
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "sample": {
                            "additionalProperties": true,
                            "type": "object"
                          }
                        },
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Trigger catalogue"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The trigger catalogue with field schemas and samples, for every rule editor",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations": {
      "get": {
        "description": "Returns the tenant's automation rules with cursor pagination (limit defaults to 20, at most 100; pass next_cursor as after). Each rule includes its trigger, conditions, actions, status and current version. Requires automations:read.",
        "operationId": "listAutomations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only rules in this state: enabled or disabled; omit for both.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "enabled",
                "disabled"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRulePage"
                }
              }
            },
            "description": "Rules"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List automation rules",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "post": {
        "description": "Validates the name (up to 200 characters), trigger, conditions and actions, checks that owner_role, when set, is a utility role holding every scope the actions need, and stores the rule as version 1. Rules are enabled unless enabled is false. An enabled rule ignores records that already match at creation time unless apply_to_existing is true; schedule rules have no such baseline. Returns 201; 400 for an invalid rule and 403 when the caller lacks a scope an action needs.",
        "operationId": "createAutomation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutomationRuleInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRule"
                }
              }
            },
            "description": "Created rule"
          },
          "400": {
            "description": "RFC 7807 validation problem"
          },
          "403": {
            "description": "RFC 7807 problem; the caller lacks automations:write or an action scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an automation rule. Requires automations:write and the scope of every action.",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "automations:write",
          "business:notification-intents:create"
        ]
      }
    },
    "$BUSINESS_API/automations/templates": {
      "get": {
        "description": "Returns the starter templates, each with a key, name, description and a complete rule body in the shape createAutomation accepts. The templates are fixed and editable: post a template's rule as is, or change it first. Requires automations:read.",
        "operationId": "getAutomationTemplates",
        "responses": {
          "200": {
            "description": "Templates, each with a ready-to-submit rule body"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Ready-made rules (dunning sequence, overdue reminder, missing-reading follow-up, anomaly review, ticket escalation)",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}": {
      "delete": {
        "description": "Permanently removes the rule and its list of existing records it was told to skip, answering 204 with no body. Answers 404 when the rule is not in the caller's tenant. Requires automations:write.",
        "operationId": "deleteAutomation",
        "parameters": [
          {
            "description": "Identifier of the automation rule to delete (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a rule",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      },
      "get": {
        "description": "Returns one automation rule with its trigger, conditions or condition group, actions, status, owner role, rate limit and current version number. Answers 404 when the rule is not in the caller's tenant.",
        "operationId": "getAutomation",
        "parameters": [
          {
            "description": "Identifier of the automation rule (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRule"
                }
              }
            },
            "description": "Rule"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a rule",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "patch": {
        "description": "Applies only the fields present in the body, then validates the whole rule again, including the caller's and owner_role's scopes for every action. Each successful update increments the version and stores an immutable snapshot. When an enabled rule's trigger or conditions change, records that already match the new criteria are recorded as existing so they do not all fire on the next sweep. Returns 400 for an invalid rule, 403 for a missing action scope and 404 for an unknown rule.",
        "operationId": "updateAutomation",
        "parameters": [
          {
            "description": "Identifier of the automation rule to update (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AutomationRuleUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRule"
                }
              }
            },
            "description": "Updated rule"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a rule's name, description, trigger, conditions or actions",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/backtests": {
      "get": {
        "description": "Returns every backtest stored for the rule, newest first, with the window, rule version, status, counts of matched records and records that would act, and the per-record results. The list is not paginated. Requires automations:read.",
        "operationId": "listAutomationBacktests",
        "parameters": [
          {
            "description": "Identifier of the automation rule whose backtests to list (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Backtests, newest first"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List a rule's backtests and simulations",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "post": {
        "description": "Replays the rule's trigger and conditions over records from a past window and stores the result, without running any action. from and to are required, to must be after from, and the window is at most 366 days; limit caps the recorded results (default 100, at most 1000). Schedule rules cannot be backtested (400). The call answers 202 with the finished backtest; a scan error is reported in the backtest as status failed rather than as an HTTP error.",
        "operationId": "createAutomationBacktest",
        "parameters": [
          {
            "description": "Identifier of the automation rule to backtest (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "from": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "limit": {
                    "maximum": 1000,
                    "minimum": 1,
                    "type": "integer"
                  },
                  "to": {
                    "format": "date-time",
                    "type": "string"
                  }
                },
                "required": [
                  "from",
                  "to"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Backtest result"
          },
          "400": {
            "description": "RFC 7807 validation problem"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Dry-run a rule over a past window; posts nothing",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/disable": {
      "post": {
        "description": "Sets the rule to disabled, increments its version and stores a snapshot. The caller needs automations:write and the scope of every action in the rule. Disabling an already disabled rule still succeeds and bumps the version.",
        "operationId": "disableAutomation",
        "parameters": [
          {
            "description": "Identifier of the automation rule to disable (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRule"
                }
              }
            },
            "description": "Disabled rule"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Disable a rule. Waiting runs are cancelled on their next attempt.",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/enable": {
      "post": {
        "description": "By default only records that match after the rule is enabled fire it. Send apply_to_existing true to also fire it for records that already match.",
        "operationId": "enableAutomation",
        "parameters": [
          {
            "description": "Identifier of the automation rule to enable (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "apply_to_existing": {
                    "default": false,
                    "type": "boolean"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRule"
                }
              }
            },
            "description": "Enabled rule"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Enable a rule. Requires the scope of every action.",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/existing-count": {
      "get": {
        "description": "Counts the records that match the rule's trigger and conditions right now and have never been claimed by a run of the rule. Use it before enabling with apply_to_existing to see how many records would fire at once. Requires automations:read; the count fails above the per-sweep record limit.",
        "operationId": "countAutomationExistingRecords",
        "parameters": [
          {
            "description": "Identifier of the automation rule to count records for (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "count": {
                      "type": "integer"
                    },
                    "rule_id": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "rule_id",
                    "count"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "How many records applying the rule to existing records would hit"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Count the records that already match a rule and have never fired it",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/runs": {
      "get": {
        "description": "Returns the runs the rule has started, with cursor pagination (limit defaults to 20, at most 100). Each run reports its subject record, status and per-action outcomes. Answers 404 when the rule is not in the caller's tenant.",
        "operationId": "listAutomationRuns",
        "parameters": [
          {
            "description": "Identifier of the automation rule whose runs to list (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only runs in this state: pending, running, waiting, succeeded, failed or cancelled; omit for all.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "running",
                "waiting",
                "succeeded",
                "failed",
                "cancelled"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRunPage"
                }
              }
            },
            "description": "Runs, newest first"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the runs of a rule",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/runs/{runId}": {
      "get": {
        "description": "Returns one run, including the record it fired for and, for each action, its status, scheduled time, summary, created resource and error. Answers 404 when the run does not exist or belongs to a different rule than the one in the path.",
        "operationId": "getAutomationRun",
        "parameters": [
          {
            "description": "Identifier of the automation rule the run belongs to (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the run to read; it must belong to the rule given in id.",
            "in": "path",
            "name": "runId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationRun"
                }
              }
            },
            "description": "Run"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a run with the outcome and error of each action",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/test": {
      "post": {
        "description": "Loads the record named by record_type and record_id (both required, except for schedule rules), evaluates the trigger and every condition, and plans each action without running it. The result says whether the rule would fire, why not if it would not (trigger mismatch, a failed condition, or the rule being disabled), each condition's outcome, and per action the planned summary, delay-adjusted start time or the reason it would be skipped. Requires only automations:read.",
        "operationId": "testAutomation",
        "parameters": [
          {
            "description": "Identifier of the automation rule to test (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "record_id": {
                    "type": "string"
                  },
                  "record_type": {
                    "enum": [
                      "invoice",
                      "payment",
                      "meter",
                      "reading",
                      "consumption",
                      "ticket",
                      "work_order",
                      "disconnection_notice",
                      "schedule"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "record_type",
                  "record_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AutomationTestResult"
                }
              }
            },
            "description": "What would happen"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Dry run a rule against a chosen record, with no side effects",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/automations/{id}/versions": {
      "get": {
        "description": "Returns every stored snapshot of the rule in ascending version order, each with the name, trigger, conditions, actions, owner role, author and time it was saved. A new version is written on create, update, enable and disable. Answers 404 when the rule is not in the tenant.",
        "operationId": "listAutomationRuleVersions",
        "parameters": [
          {
            "description": "Identifier of the automation rule whose versions to list (prefix aut_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/AutomationRule"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Versions, oldest first"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List a rule's immutable versions",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/bank-statements": {
      "get": {
        "description": "Returns the tenant's imported bank statements, newest first, with cursor pagination (limit defaults to 20, at most 100). Each statement carries its bank account reference, statement reference and date, currency and line count. Requires payments:read.",
        "operationId": "listBankStatements",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List bank statements",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      },
      "post": {
        "description": "Stores a statement with its lines, given either as a lines array or as CSV text (columns value_date as YYYY-MM-DD, amount, then optional reference and description; a value_date header row is skipped). bank_account_ref, statement_reference, statement_date and at least one line are required, and amounts are read in the tenant's currency. Each credit line is then matched to a posted payment of the same amount, first by reference or receipt number, then by amount alone when exactly one bank transfer falls within three days; matched payments become reconciled and everything else waits in the unmatched queue. Records a bank_statement.imported event and returns 201 with the statement and its lines.",
        "operationId": "importBankStatement",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "bank_account_ref": {
                    "type": "string"
                  },
                  "csv": {
                    "type": "string"
                  },
                  "statement_date": {
                    "type": "string"
                  },
                  "statement_reference": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Import a bank statement (lines or csv) and match credits to payments",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/lines/{id}/create-payment": {
      "post": {
        "description": "Records a bank transfer payment on the account in the body for the line's amount, dated at the line's value date and referenced with the line's reference (or BANK-<line id> when empty), allocates it to the account's open invoices, reconciles it and matches the line. Only an unmatched credit line qualifies; anything else answers 409. The payment uses an idempotency key derived from the line, so a repeated call does not book a second payment. Returns 201 with the updated line.",
        "operationId": "createPaymentFromBankLine",
        "parameters": [
          {
            "description": "Identifier of the unmatched credit statement line (prefix sln_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "account_id": {
                    "type": "string"
                  },
                  "note": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Book a payment from an unmatched line and match it",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/lines/{id}/ignore": {
      "post": {
        "description": "Marks an unmatched line as ignored, for money that needs no payment such as a bank fee or an internal transfer, and stores the required note. Only an unmatched line can be ignored (409 otherwise), and an empty note answers 400. Returns the updated line.",
        "operationId": "ignoreBankLine",
        "parameters": [
          {
            "description": "Identifier of the statement line to ignore (prefix sln_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "note": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Retire a line that needs no payment",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/lines/{id}/match": {
      "post": {
        "description": "Links an unmatched line to the payment named in the body, moves that payment from posted to reconciled and records who matched it, with an optional note. The line must be unmatched and the payment posted (409 otherwise), and the amounts must be equal (400 otherwise). Returns the updated line.",
        "operationId": "matchBankLine",
        "parameters": [
          {
            "description": "Identifier of the unmatched statement line to match (prefix sln_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "note": {
                    "type": "string"
                  },
                  "payment_id": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Manually match a line to a payment",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/lines/{id}/unmatch": {
      "post": {
        "description": "Returns a matched line to the unmatched queue and moves its payment from reconciled back to posted, clearing who matched it. An optional note query parameter is stored as the review note. A line that is not matched answers 409.",
        "operationId": "unmatchBankLine",
        "parameters": [
          {
            "description": "Identifier of the matched statement line to unmatch (prefix sln_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Return a matched line to review",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/unmatched-lines": {
      "get": {
        "description": "Returns the lines of every statement of the tenant that are still unmatched, across all imports, with cursor pagination (limit defaults to 20, at most 100). This is the review queue for credits that could not be matched automatically and for debits, which are never auto-matched. Requires payments:read.",
        "operationId": "listUnmatchedBankLines",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Unmatched bank lines review queue",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/{id}": {
      "get": {
        "description": "Returns one imported statement with its bank account reference, statement reference and date, currency, line count and status. Lines are listed separately. Answers 404 when the statement is not in the caller's tenant.",
        "operationId": "getBankStatement",
        "parameters": [
          {
            "description": "Identifier of the bank statement (prefix stm_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a bank statement",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/bank-statements/{id}/lines": {
      "get": {
        "description": "Returns the lines of one statement in import order with cursor pagination (limit defaults to 20, at most 100). Pass status (unmatched, matched or ignored) to see only lines in that review state. Each line shows its amount, value date, reference and, when matched, the payment and who matched it.",
        "operationId": "listBankStatementLines",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Identifier of the bank statement whose lines to list (prefix stm_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List a statement's lines, optionally by status",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/billing-policy": {
      "get": {
        "description": "Returns the tenant's billing policy: default due days, grace period, the default volume used for missing readings, and the late penalty settings (kind, amount or rate, frequency, interval, cap, tax and compounding, and exclusions for disputed invoices and payment plans). A tenant that never saved a policy gets the default policy. Requires tariffs:read.",
        "operationId": "getBillingPolicy",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityBillingPolicy"
                }
              }
            },
            "description": "Billing policy"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the utility billing policy",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "tariffs:read"
        ]
      },
      "put": {
        "description": "Applies only the fields present in the body to the current policy, then validates the result: due days, grace period and penalty cap must not be negative, the default missing-reading volume must be a non-negative finite number, and late_penalty_frequency must be one_time or recurring (the default). When late penalties are enabled the chosen kind needs its amount or rate, for example a positive late_penalty_amount_minor for a fixed penalty. Send clear_default_missing_reading true to remove the default volume. Requires tariffs:write; returns the saved policy or 400.",
        "operationId": "updateBillingPolicy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateUtilityBillingPolicyRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityBillingPolicy"
                }
              }
            },
            "description": "Updated billing policy"
          },
          "422": {
            "description": "RFC 7807 validation error"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update the utility billing policy",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "tariffs:write"
        ]
      }
    },
    "$BUSINESS_API/billing-policy/assess-late-penalties": {
      "post": {
        "description": "Runs the tenant's late penalty policy immediately instead of waiting for the scheduled run. Each open invoice with a balance whose due date plus the grace period has passed gets a late fee debit note, fixed or a percentage of the overdue balance and limited by the cap, unless the policy excludes disputed invoices or accounts on an active payment plan. Penalties are idempotent per invoice, policy version and recurrence cycle, so calling again does not charge twice. When late penalties are disabled in the billing policy nothing is applied and applied is 0. No request body is read. Requires invoices:write.",
        "operationId": "assessLatePenalties",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "applied": {
                      "description": "Late fee debit notes created by this call.",
                      "example": 3,
                      "minimum": 0,
                      "type": "integer"
                    }
                  },
                  "required": [
                    "applied"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Number of penalties applied by this run"
          },
          "400": {
            "description": "An invoice changed state while the run was applying a penalty (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing invoices:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Apply late payment penalties to overdue invoices now",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/billing-runs": {
      "get": {
        "description": "Returns the tenant's billing runs with cursor pagination (limit defaults to 20, at most 100), optionally filtered by status. Each run shows its period, service area, status, issued, skipped and estimated invoice counts, total amount and exception count. Requires billing_runs:read.",
        "operationId": "listBillingRuns",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingRunPage"
                }
              }
            },
            "description": "Billing runs"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List billing execution runs",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      },
      "post": {
        "description": "Issues one invoice per account for the period from accepted consumptions; period_start must be before period_end and due_date, when given, must not fall before period_end. A period is billed by one run: calling again for the same period and service area reuses that run and skips accounts already invoiced, so retrying after a partial failure is safe. When the job queue is enabled and the period is large, the run is queued and returned in running status for you to poll. Records billing_run.started and then billing_run.posted or billing_run.failed events, plus exception events for skipped accounts; requires billing_runs:write and the billing capability, and returns 201.",
        "operationId": "executeBillingRun",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillingRunRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingRun"
                }
              }
            },
            "description": "Billing run started"
          },
          "403": {
            "description": "CAPABILITY_INACTIVE: the billing capability is not active because the utility's onboarding is not approved. RFC 7807 Problem Details with code CAPABILITY_INACTIVE and a detail naming the capability."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Trigger a periodic billing run",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "billing_runs:write"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/preview": {
      "post": {
        "description": "Takes the same body as executeBillingRun and returns, per account, the invoice that would be issued (consumption, line items, charges, tax, reconciliation, arrears, due date and payment instructions) plus the exceptions that would be raised and the totals. Nothing is stored or issued and no event is recorded. capability_active reports whether the billing capability is on, so a run would actually be allowed. Requires billing_runs:read.",
        "operationId": "previewBillingRun",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillingRunRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingRunPreview"
                }
              }
            },
            "description": "Invoices that would be issued and accounts that would be skipped, with capability_active"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Report what a billing run would issue, with no side effects",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/{id}": {
      "get": {
        "description": "Returns one billing run with its period, service area, schedule, status, invoice counts, total amount, exception count, error message and completion time. Poll it after a queued run to see when it completes. Answers 404 when the run is not in the caller's tenant.",
        "operationId": "getBillingRun",
        "parameters": [
          {
            "description": "Identifier of the billing run (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingRun"
                }
              }
            },
            "description": "Billing run"
          },
          "404": {
            "description": "Billing run not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a billing execution run",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/{id}/exceptions": {
      "get": {
        "description": "Returns the accounts the run skipped or failed to bill, each with the reason, detail and review status, with cursor pagination (limit defaults to 20, at most 100). Filter by reason or by status (open, resolved or dismissed). Answers 404 when the run is not in the tenant.",
        "operationId": "listBillingRunExceptions",
        "parameters": [
          {
            "description": "Identifier of the billing run whose exceptions to list (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only exceptions with this reason: already_billed, no_consumption, no_reading, no_consumption_history, reading_under_review, no_active_tariff, account_resolution_failed, billing_failed or reconciliation_credit_exceeds_bill.",
            "in": "query",
            "name": "reason",
            "schema": {
              "enum": [
                "already_billed",
                "no_consumption",
                "no_reading",
                "no_consumption_history",
                "reading_under_review",
                "no_active_tariff",
                "account_resolution_failed",
                "billing_failed",
                "reconciliation_credit_exceeds_bill"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RunExceptionPage"
                }
              }
            },
            "description": "Exceptions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accounts a run skipped and why",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/{id}/exceptions/{exceptionId}/resolve": {
      "post": {
        "description": "Sets the exception's review status to resolved (the default) or dismissed, and records who did it, when, and an optional resolution note. Any other status answers 400, and an exception that does not belong to the run in the path answers 404. Dismissals are carried over when the run is retried. Requires billing_runs:write.",
        "operationId": "resolveRunException",
        "parameters": [
          {
            "description": "Identifier of the billing run the exception belongs to (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the exception to resolve or dismiss (prefix rex_).",
            "in": "path",
            "name": "exceptionId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ResolveRunExceptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated exception"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Resolve or dismiss a billing run exception",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "billing_runs:write"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/{id}/invoice-pdfs": {
      "get": {
        "description": "Streams the ZIP archive prepared by enqueueInvoicePdfBatch, as an attachment whose file name depends on the negotiated document language. Answers 404 while no archive exists for the run, so check the status endpoint first.",
        "operationId": "downloadInvoicePdfBatch",
        "parameters": [
          {
            "description": "Identifier of the billing run whose archive to download (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "ZIP archive"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the finished invoice PDF archive",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      },
      "post": {
        "description": "Queues a background job that renders the PDF of every invoice issued by the run into one ZIP archive, and answers 202 with job_id and status. Repeating the call for the same run reuses the queued job. Requires billing_runs:write; answers 404 for an unknown run and 409 when background jobs are not enabled on the installation.",
        "operationId": "enqueueInvoicePdfBatch",
        "parameters": [
          {
            "description": "Identifier of the billing run whose invoices to archive (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "description": "The queued job id"
          },
          "409": {
            "description": "The job queue is not enabled on this installation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue a PDF archive of every invoice of a billing run (job queue enabled)",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "billing_runs:write"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/{id}/invoice-pdfs/status": {
      "get": {
        "description": "Returns enabled, which says whether background jobs can prepare an archive on this installation, and available, which says whether a finished archive for the run can be downloaded now. It answers 200 in both cases so a client can poll after queuing; 404 only when the run itself is unknown.",
        "operationId": "getInvoicePdfBatchStatus",
        "parameters": [
          {
            "description": "Identifier of the billing run whose archive status to read (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "available": {
                      "description": "True when a finished archive can be downloaded",
                      "type": "boolean"
                    },
                    "enabled": {
                      "description": "False when this installation runs without the job queue",
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "enabled",
                    "available"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The archive state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Whether the invoice PDF archive can be prepared and is ready, without a 404 while it is absent",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      }
    },
    "$BUSINESS_API/billing-runs/{id}/retry": {
      "post": {
        "description": "Executes the run's period again: accounts already invoiced are skipped, accounts that failed or were not billable before are attempted again, and the run's counts and exceptions are replaced with the new outcome. Exceptions that were dismissed before are dismissed again with the same note when they recur. Estimates are used again only if the original run issued estimated invoices. Requires billing_runs:write and returns the updated run.",
        "operationId": "retryBillingRun",
        "parameters": [
          {
            "description": "Identifier of the billing run to retry (prefix brn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Updated billing run"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Re-run unresolved accounts for an existing billing run",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "billing_runs:write"
        ]
      }
    },
    "$BUSINESS_API/billing-schedules": {
      "get": {
        "description": "Returns the tenant's billing schedules with cursor pagination (limit defaults to 20, at most 100), optionally filtered by status (active or paused). Each schedule shows its day of month, due days, service area, next run time and next period start. Requires billing_runs:read.",
        "operationId": "listBillingSchedules",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Schedules"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List billing schedules",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      },
      "post": {
        "description": "Creates an active schedule that starts a billing run each month on day_of_month (1 to 28), covering the month before that day; holidays in the tenant calendar are skipped when computing next_run_at. due_days must be 0 to 180 and auto_consumption defaults to true. Only one schedule may cover the whole tenant or a given service area, and a tenant-wide schedule excludes area schedules, so an overlap answers 409. Requires billing_runs:write and returns 201.",
        "operationId": "createBillingSchedule",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BillingScheduleInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSchedule"
                }
              }
            },
            "description": "Schedule"
          },
          "409": {
            "description": "RFC 7807; a schedule already covers this tenant or service area"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a monthly billing schedule for the tenant or one service area",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "billing_runs:write"
        ]
      }
    },
    "$BUSINESS_API/billing-schedules/{id}": {
      "get": {
        "description": "Returns one billing schedule with its name, service area, day of month, due days, estimate and auto-consumption flags, status, next run time and next period start. Answers 404 when the schedule is not in the caller's tenant.",
        "operationId": "getBillingSchedule",
        "parameters": [
          {
            "description": "Identifier of the billing schedule (prefix bsc_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSchedule"
                }
              }
            },
            "description": "Schedule"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a billing schedule",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "billing_runs:read"
        ]
      },
      "patch": {
        "description": "Applies only the fields present in the body; status accepts active or paused, and the same limits as on create apply (day_of_month 1 to 28, due_days 0 to 180). Resuming a paused schedule or changing day_of_month recomputes next_run_at from now, so missed months are not billed retroactively; other edits keep the period already scheduled. Requires billing_runs:write.",
        "operationId": "updateBillingSchedule",
        "parameters": [
          {
            "description": "Identifier of the billing schedule to update (prefix bsc_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "auto_consumption": {
                    "type": "boolean"
                  },
                  "day_of_month": {
                    "maximum": 28,
                    "minimum": 1,
                    "type": "integer"
                  },
                  "due_days": {
                    "type": "integer"
                  },
                  "estimate_missing": {
                    "type": "boolean"
                  },
                  "name": {
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "active",
                      "paused"
                    ],
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingSchedule"
                }
              }
            },
            "description": "Schedule"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update or pause a billing schedule",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "billing_runs:write"
        ]
      }
    },
    "$BUSINESS_API/branding": {
      "get": {
        "description": "Requires business:branding:read (utility owner and admin).",
        "operationId": "getBusinessBranding",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Utility brand with sources"
          },
          "403": {
            "description": "Missing business:branding:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The utility's effective brand and where each value comes from",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:branding:read"
        ]
      },
      "patch": {
        "description": "Requires business:branding:write. The platform PATCH body plus receipt_footer; null resets a field to the next level down (configuration, business profile, platform). Audited as branding.updated.",
        "operationId": "updateBusinessBranding",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantBrandingPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Updated utility brand"
          },
          "400": {
            "description": "A value is invalid or the colours lack contrast"
          },
          "403": {
            "description": "Missing business:branding:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change the utility's brand",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:branding:write"
        ]
      }
    },
    "$BUSINESS_API/branding/assets/{kind}": {
      "delete": {
        "description": "Requires business:branding:write. Audited as branding.asset_removed.",
        "operationId": "deleteBusinessBrandingAsset",
        "parameters": [
          {
            "description": "Which brand file to remove: logo, logo_dark or icon; any other value answers 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Updated utility brand"
          },
          "403": {
            "description": "Missing business:branding:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Return a utility brand file to the next level down",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:branding:write"
        ]
      },
      "put": {
        "description": "Requires business:branding:write. Same types, size cap and SVG sanitising as the platform upload. Audited as branding.asset_uploaded.",
        "operationId": "uploadBusinessBrandingAsset",
        "parameters": [
          {
            "description": "Which brand file to replace: logo, logo_dark or icon; any other value answers 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Updated utility brand"
          },
          "400": {
            "description": "The file is empty",
            "too large or not an allowed type": null
          },
          "403": {
            "description": "Missing business:branding:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload a utility brand file",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:branding:write"
        ]
      }
    },
    "$BUSINESS_API/calendar": {
      "get": {
        "description": "Returns the tenant-wide working calendar: time zone, working weekdays (0 = Sunday to 6 = Saturday) and the holiday template it follows, if any. When the tenant has never saved a calendar, the response is the built-in default (the default time zone and Monday to Friday) rather than a 404. Requires the automations:read permission.",
        "operationId": "getCalendar",
        "responses": {
          "200": {
            "description": "Tenant calendar"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the tenant's time zone, working week and template adoption",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "put": {
        "description": "Saves the calendar that billing due dates, grace periods and scheduled automations are evaluated against. An empty timezone keeps the current one and an omitted working_days keeps the current weekdays, but template_key and template_version are always replaced by the values sent, so omitting them detaches the calendar from its template; sending area_id saves a separate calendar for that service area. Returns 400 for an unknown IANA time zone or for working_days with more than seven entries or values outside 0-6. Requires automations:write.",
        "operationId": "updateCalendar",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated calendar"
          },
          "400": {
            "description": "RFC 7807 validation problem"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Set the tenant's time zone, working days and holiday template",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/days": {
      "get": {
        "description": "Lists the tenant's dated exceptions (holidays, closures and extra working days), sorted by date, in a `data` array without pagination. Each day records where it came from (manual, file, url, connector or template). Recurring rules are not expanded here; use the rules endpoint or the occurrences evaluator for them. Requires automations:read.",
        "operationId": "listCalendarDays",
        "parameters": [
          {
            "description": "Earliest date to include, as YYYY-MM-DD, inclusive; omitted means no lower bound.",
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Latest date to include, as YYYY-MM-DD, inclusive; omitted means no upper bound.",
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Service area id; when set, the list holds that area's days plus the tenant-wide days that have no area, and when omitted it holds every day of the tenant.",
            "in": "query",
            "name": "area_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Calendar days"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List holidays, closures and extra working days",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "post": {
        "description": "Adds one dated exception to the tenant calendar and returns it with 201. The date must be YYYY-MM-DD and kind must be holiday (the default), closure or working; a working day overrides a weekday that is normally off, and a holiday or closure makes the date non-working for schedules. name_pt falls back to name and name_en falls back to name_pt; the day is stored with source `manual`. Requires automations:write.",
        "operationId": "addCalendarDay",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarDayInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created day"
          },
          "400": {
            "description": "RFC 7807 validation problem"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a holiday, closure or extra working day",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/days/{id}": {
      "delete": {
        "description": "Removes one dated exception from the tenant calendar and returns 204 with no body. Schedules evaluated afterwards treat the date by its normal weekday again. Returns 404 when the day does not exist in this tenant. Requires automations:write.",
        "operationId": "deleteCalendarDay",
        "parameters": [
          {
            "description": "Id of the calendar day to delete, as returned when it was added or listed (prefix `cdy`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a calendar day",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/export.csv": {
      "get": {
        "description": "Downloads every dated day and recurring rule of the tenant as a CSV attachment (text/csv) for review or re-import. The header is date,rule,kind,name_pt,name_en,area,observed,source_reference: day rows fill the date column, and rule rows fill the rule column with semicolon-separated kind, month, day, weekday, position, easter and easter_offset values. All areas are included. Requires automations:read.",
        "operationId": "exportCalendarCSV",
        "responses": {
          "200": {
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "CSV document"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Export the effective calendar as CSV",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/calendar/export.ics": {
      "get": {
        "description": "Downloads the tenant's calendar as an iCalendar file (text/calendar attachment) that calendar applications can subscribe to or import. Each dated day becomes an all-day VEVENT, and each recurring rule becomes a VEVENT with a yearly RRULE (BYMONTH with BYMONTHDAY or BYDAY); Easter-relative rules use a non-standard EASTER/OFFSET RRULE that other applications may not understand. Event names use the Portuguese name. Requires automations:read.",
        "operationId": "exportCalendarICS",
        "responses": {
          "200": {
            "content": {
              "text/calendar": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "iCalendar document"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Export the effective calendar as iCalendar",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/calendar/imports": {
      "post": {
        "description": "Parses an ICS or CSV calendar, sent inline in `content` or fetched from `url` (10 second timeout, 4 MB limit), and stores a preview that lists the days and rules it would add, change or remove, the conflicts with existing days, and the schedules the change may move. Nothing is written to the calendar unless `auto_apply` is true and the preview has no conflicts; otherwise apply it later with the apply endpoint. ICS input must use all-day events with optional yearly RRULEs; multi-day events, EXDATE and timed starts are rejected with 400. When `source_id` is given the source must exist and be enabled, and days or rules that the source previously supplied but no longer contains are reported as removals and conflicts. Requires automations:write.",
        "operationId": "createCalendarImport",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarImportInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalendarImport"
                }
              }
            },
            "description": "Import preview with added, changed, removed, conflicts, affected schedules and explicit coverage limitations"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Parse an ICS or CSV calendar into a preview",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/imports/{id}": {
      "get": {
        "description": "Returns a stored import with its status (preview, applied or failed), the parsed items, the added, changed and removed entries, conflicts, affected schedules and the known limits of that affected-schedule analysis. After an apply it also shows who confirmed it, when, and a short outcome. Requires automations:read.",
        "operationId": "getCalendarImport",
        "parameters": [
          {
            "description": "Id of the calendar import returned when it was created (prefix `cim`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalendarImport"
                }
              }
            },
            "description": "Import"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a calendar import preview or outcome",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/calendar/imports/{id}/apply": {
      "post": {
        "description": "Writes a previewed import into the tenant calendar: added and changed rules are created or updated in place, and dated days replace any day with the same source reference. If the preview has conflicts, the import is marked failed and the call returns 409; an import that is no longer in preview status is returned unchanged, so repeating the call is safe. Returns 400 when the linked source has since been disabled. Requires automations:write.",
        "operationId": "applyCalendarImport",
        "parameters": [
          {
            "description": "Id of the calendar import to apply (prefix `cim`); it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CalendarImport"
                }
              }
            },
            "description": "Applied import"
          },
          "409": {
            "description": "RFC 7807 conflict; the preview still has conflicts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Apply a calendar import after its conflicts are resolved",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/occurrences": {
      "post": {
        "description": "Dry-runs a schedule spec against the tenant calendar and returns its next run times, the same way billing and automations evaluate it, so a rule can be checked before it is saved. The calculation uses the area's calendar (or the tenant-wide one), its working weekdays, dated days, recurring rules and template, looking three years each way around `after`. `count` defaults to 5 and is capped at 50, and `after` defaults to now; an invalid spec returns 400. Requires automations:read.",
        "operationId": "evaluateCalendarOccurrences",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "after": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "area_id": {
                    "type": "string"
                  },
                  "count": {
                    "maximum": 50,
                    "minimum": 1,
                    "type": "integer"
                  },
                  "spec": {
                    "additionalProperties": true,
                    "type": "object"
                  }
                },
                "required": [
                  "spec"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Next occurrences"
          },
          "400": {
            "description": "RFC 7807 validation problem"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Evaluate a schedule expression for previews",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/calendar/rules": {
      "get": {
        "description": "Lists the tenant's recurring holiday rules (fixed yearly date, nth or last weekday of a month, or an offset from Western or Orthodox Easter) in a `data` array without pagination. Each rule carries its observed-day policy, validity window and source. Rules that come from a followed template are not listed here. Requires automations:read.",
        "operationId": "listCalendarRules",
        "parameters": [
          {
            "description": "Service area id; when set, the list holds that area's rules plus the tenant-wide rules that have no area, and when omitted it holds every rule of the tenant.",
            "in": "query",
            "name": "area_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Calendar rules"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List recurring calendar rules",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "post": {
        "description": "Creates a recurring rule that marks a date every year and returns it with 201. fixed_yearly needs month 1-12 and day 1-31; nth_weekday and last_weekday need month and weekday 0-6 (position picks the nth week, -1 the last); easter_offset needs easter_kind western or orthodox plus a day offset. `observed` (none, next, previous or nearest) moves the date to a working day when it falls on a day off, at least one of name_pt or name_en is required, and valid_from/valid_to are optional YYYY-MM-DD bounds. Invalid combinations return 400. Requires automations:write.",
        "operationId": "addCalendarRule",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarRuleInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created rule"
          },
          "400": {
            "description": "RFC 7807 validation problem"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a recurring calendar rule",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/rules/{id}": {
      "delete": {
        "description": "Deletes a recurring rule and returns 204 with no body; dates it produced stop counting as days off for schedules evaluated afterwards. Returns 404 when the rule is not in this tenant. Requires automations:write.",
        "operationId": "deleteCalendarRule",
        "parameters": [
          {
            "description": "Id of the calendar rule to delete (prefix `crl`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a recurring calendar rule",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      },
      "patch": {
        "description": "Changes only the fields sent on a recurring rule and returns the updated rule. The merged rule is validated again with the same checks as on creation, so a change that leaves it inconsistent (for example switching to easter_offset without easter_kind) returns 400. The rule's area cannot be changed. Returns 404 when the rule is not in this tenant. Requires automations:write.",
        "operationId": "updateCalendarRule",
        "parameters": [
          {
            "description": "Id of the calendar rule to update (prefix `crl`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarRulePatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated rule"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update fields of a recurring calendar rule",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/sources": {
      "get": {
        "description": "Lists the configured calendar sources of the tenant in a `data` array without pagination. A source records where holiday data comes from (manual, file, url, connector or template_version), its reference, refresh schedule, whether imports from it apply automatically, and whether it is enabled. Requires automations:read.",
        "operationId": "listCalendarSources",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Sources"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List calendar import sources",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "post": {
        "description": "Registers a calendar source and returns it with 201. kind must be manual, file, url, connector or template_version; the source is enabled unless `enabled` is false. Imports created with this source's id track which days and rules came from it, so later imports can report what the source removed. Requires automations:write.",
        "operationId": "addCalendarSource",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarSourceInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created source"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a calendar import source",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/calendar/sources/{id}": {
      "delete": {
        "description": "Deletes a calendar source and returns 204 with no body. Days and rules already imported from it stay in the calendar. Returns 404 when the source is not in this tenant. Requires automations:write.",
        "operationId": "deleteCalendarSource",
        "parameters": [
          {
            "description": "Id of the calendar source to delete (prefix `csr`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a calendar import source",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      },
      "patch": {
        "description": "Changes only the fields sent on a calendar source and returns it. Disabling a source makes new imports and applies that reference it fail with 400. An invalid kind returns 400 and an unknown id returns 404. Requires automations:write.",
        "operationId": "updateCalendarSource",
        "parameters": [
          {
            "description": "Id of the calendar source to update (prefix `csr`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarSourcePatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated source"
          },
          "404": {
            "description": "RFC 7807 not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update fields of a calendar import source",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/campaigns": {
      "get": {
        "description": "Newest first, one cursor page at a time. The response is the standard page (data, has_more, next_cursor); items repeats data for older clients.",
        "operationId": "listPromoCampaigns",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign page"
          },
          "400": {
            "description": "Invalid cursor"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List promotional credit campaigns",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      },
      "post": {
        "description": "Creates a promotional credit campaign in `draft` status; customers cannot redeem its code until the campaign is activated. name and a positive amount_minor are required; currency defaults to MZN and per_account_limit to 1. The code is stored only as a hash, and the response exposes only its first four characters as `code_prefix`. Requires the invoices:write permission.",
        "operationId": "createPromoCampaign",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Campaign created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a promotional credit campaign",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/campaigns/{id}": {
      "get": {
        "description": "Returns one campaign with its status, credit amount, budget and amount spent, redemption count and limits, eligible charge kinds and validity window. The promo code itself is never returned, only its prefix. Returns 404 when the campaign is not in this tenant. Requires invoices:read.",
        "operationId": "getPromoCampaign",
        "parameters": [
          {
            "description": "Id of the promotional campaign (prefix `prc`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a promotional credit campaign",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/campaigns/{id}/activate": {
      "post": {
        "description": "Moves a draft or paused campaign to `active` so its code can be redeemed; redemptions still respect starts_at, ends_at, the budget and the redemption limits. Activating a campaign in any other status returns 400 as an invalid state transition. Requires invoices:write.",
        "operationId": "activatePromoCampaign",
        "parameters": [
          {
            "description": "Id of the promotional campaign to activate (prefix `prc`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign activated"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate a promotional credit campaign",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/campaigns/{id}/pause": {
      "post": {
        "description": "Moves an active campaign to `paused`, after which redemptions of its code are refused until it is activated again. Credits already granted are not affected. Pausing a campaign that is not active returns 400 as an invalid state transition. Requires invoices:write.",
        "operationId": "pausePromoCampaign",
        "parameters": [
          {
            "description": "Id of the promotional campaign to pause (prefix `prc`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign paused"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Pause a promotional credit campaign",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/cases": {
      "get": {
        "description": "Returns a cursor-paginated list of the tenant's debt collection cases. Results can be narrowed by customer_id, account_id, status and aging_bucket, and `search` also matches accounts by holder name; page with `limit` (default 20, max 100) and the `after` cursor from the previous page. Requires collections:read.",
        "operationId": "listCases",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCasePage"
                }
              }
            },
            "description": "Collection cases"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List collection cases",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      },
      "post": {
        "description": "Opens a collection case for an account's overdue debt in `open` status and returns it with 201. customer_id, account_id and a positive total_debt_cents are required; aging_bucket defaults to the 30-day bucket and currency to the tenant currency. Any notes are kept on the case, and the opening is recorded in the case's status history. Requires collections:write.",
        "operationId": "createCase",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCaseRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCase"
                }
              }
            },
            "description": "Collection case opened"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a collection case",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/cases/{id}": {
      "get": {
        "description": "Returns one collection case with its debt, currency, aging bucket, status, dunning status and level, linked cutoff order and notes. Returns 404 when the case is not in this tenant. Requires collections:read.",
        "operationId": "getCase",
        "parameters": [
          {
            "description": "Id of the collection case (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCase"
                }
              }
            },
            "description": "Collection case details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get collection case",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/cases/{id}/enforce": {
      "post": {
        "description": "Moves the case to `enforcement_requested`, the step before disconnection, and stores the optional `reason` as a case note. The change is recorded in the case's status history; a case that is already in this status is returned unchanged. A written-off case cannot move and returns 409. Requires collections:write.",
        "operationId": "requestCollectionEnforcement",
        "parameters": [
          {
            "description": "Id of the collection case (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCase"
                }
              }
            },
            "description": "Enforcement request recorded"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request enforcement for a collection case",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/cases/{id}/notice": {
      "post": {
        "description": "Records a disconnection notice for the case and returns it with 201, moving the case to `notice_sent` and its dunning status to in-notice. The cutoff date is today plus `cutoff_days` (default 14) and delivery defaults to text message; the dunning level rises to final warning when `final_warning` is true or the case already has two or more notices. A resolved or written-off case returns 409. Requires collections:write.",
        "operationId": "issueDisconnectionNotice",
        "parameters": [
          {
            "description": "Id of the collection case the notice is issued for (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueNoticeRequest"
              }
            }
          }
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DisconnectionNotice"
                }
              }
            },
            "description": "Disconnection notice issued"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a disconnection notice for a collection case",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/cases/{id}/notices": {
      "get": {
        "description": "Returns every disconnection notice issued for the case, in a `data` array without pagination, each with its notice and cutoff dates, delivery channel and status. Use the notice PDF endpoint to render one for printing or sending.",
        "operationId": "getCaseNotices",
        "parameters": [
          {
            "description": "Id of the collection case whose notices are listed (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/DisconnectionNotice"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Notices issued for the collection case"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List notices issued for a collection case",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/cases/{id}/notices/{noticeId}/pdf": {
      "get": {
        "description": "Renders a disconnection notice as a PDF, served inline, with the issuer, the customer and account, the debt, the cutoff date, the delivery channel and the account's open invoices. The notice must belong to the given case and the case to the caller's tenant, otherwise 404. Language follows the request locale, and the `layout` parameter picks A4 or a narrow mobile page.",
        "operationId": "getNoticePDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Case id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Notice id",
            "in": "path",
            "name": "noticeId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a collection or disconnection notice as PDF",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/cases/{id}/resolve": {
      "post": {
        "description": "Marks the case `resolved`, for example once the debt is paid or settled, and moves an active dunning status to settled. The optional `reason` is stored as a case note and in the case's status history. A written-off case cannot be resolved and returns 409, and resolving a case that is already resolved changes nothing. Requires collections:write.",
        "operationId": "resolveCollectionCase",
        "parameters": [
          {
            "description": "Id of the collection case to resolve (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCase"
                }
              }
            },
            "description": "Resolved collection case"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Resolve a collection case",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/cashier/shifts": {
      "get": {
        "description": "Returns a paginated list of cashier shifts in the tenant, filterable by cashier_user_id, counter_id and status (open, closed or reconciled). Each shift carries its opening float, cash collected, counted cash and variance once closed, and the supervisor who reconciled it. Requires cashier:read.",
        "operationId": "listCashierShifts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List cashier shifts",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "cashier:read"
        ]
      }
    },
    "$BUSINESS_API/cashier/shifts/close": {
      "post": {
        "description": "Closes a shift by recording the physical cash counted in the drawer; the variance is computed as counted minus (opening float + cash collected). Without `shift_id` the caller's own open shift is closed. A shift that is not open returns 409, and no open shift returns 404. Send an Idempotency-Key header (1 to 255 visible ASCII characters) so a retry returns the stored result instead of failing; a cashier.shift.closed event is emitted. Requires cashier:write.",
        "operationId": "closeCashierShift",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "notes": {
                    "type": "string"
                  },
                  "physical_cash_counted_minor": {
                    "type": "integer"
                  },
                  "shift_id": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Count the drawer and close the shift; variance = counted - (float + cash)",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "cashier:write"
        ]
      }
    },
    "$BUSINESS_API/cashier/shifts/current": {
      "get": {
        "description": "Returns the calling user's open shift, optionally at one counter given by `counter_id`. When the caller has no open shift the response is 200 with a null body, not 404, so a till application can decide whether to prompt for opening a shift. Requires cashier:read.",
        "operationId": "getCurrentCashierShift",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "nullable": true,
                  "properties": {
                    "cash_variance_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "cashier_user_id": {
                      "type": "string"
                    },
                    "closed_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "counter_id": {
                      "type": "string"
                    },
                    "created_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "currency": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "notes": {
                      "type": "string"
                    },
                    "opened_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "opening_float_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "physical_cash_counted_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "reconciled_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "open",
                        "closed",
                        "reconciled"
                      ],
                      "type": "string"
                    },
                    "supervisor_user_id": {
                      "type": "string"
                    },
                    "tenant_id": {
                      "type": "string"
                    },
                    "total_cash_collected_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "total_pos_card_minor": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "updated_at": {
                      "format": "date-time",
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "tenant_id",
                    "cashier_user_id",
                    "counter_id",
                    "currency",
                    "opened_at",
                    "opening_float_minor",
                    "total_cash_collected_minor",
                    "total_pos_card_minor",
                    "status",
                    "created_at",
                    "updated_at"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The caller's open shift, or null when no shift is open"
          },
          "403": {
            "description": "Forbidden"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The caller's open shift",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "cashier:read"
        ]
      }
    },
    "$BUSINESS_API/cashier/shifts/open": {
      "post": {
        "description": "Opens a shift for the calling user at the given counter with an opening cash float, in the tenant currency, and returns it with 201. counter_id is required and opening_float_minor must not be negative; only one open shift per cashier and counter is allowed, so a second one returns 409. Send an Idempotency-Key header (1 to 255 visible ASCII characters) to make retries safe; a reused key with a different request is rejected. A cashier.shift.opened event is emitted. Requires cashier:write.",
        "operationId": "openCashierShift",
        "parameters": [
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "counter_id": {
                    "type": "string"
                  },
                  "opening_float_minor": {
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a shift for the authenticated cashier and counter",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "cashier:write"
        ]
      }
    },
    "$BUSINESS_API/cashier/shifts/{id}": {
      "get": {
        "description": "Returns one cashier shift with its counter, cashier, opening float, cash collected, counted cash, variance, notes and its open, close and reconcile timestamps. Returns 404 when the shift is not in this tenant. Requires cashier:read.",
        "operationId": "getCashierShift",
        "parameters": [
          {
            "description": "Id of the cashier shift (prefix `shf`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a shift",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "cashier:read"
        ]
      }
    },
    "$BUSINESS_API/cashier/shifts/{id}/reconcile": {
      "post": {
        "description": "Supervisor sign-off of a closed shift: sets its status to `reconciled`, records the caller as supervisor with a timestamp, and appends any notes to the shift notes. Only a closed shift can be reconciled; any other status returns 409. Supports an Idempotency-Key header for safe retries. Requires the cashier:supervise permission.",
        "operationId": "reconcileCashierShift",
        "parameters": [
          {
            "description": "Id of the closed cashier shift to reconcile (prefix `shf`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "notes": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Supervisor sign-off of a closed shift",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "cashier:supervise"
        ]
      }
    },
    "$BUSINESS_API/collections/ageing": {
      "get": {
        "description": "Totals the outstanding balance of the tenant's open invoices into ageing buckets (current, 1-30, 31-60, 61-90 and over 90 days past due) with the number of distinct accounts in each, as of now. The figures are computed live from billing, not from collection cases. Returns 400 when billing is not connected to collections. Requires collections:read.",
        "operationId": "getDebtAgeing",
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Debt ageing buckets (current, 30, 60, 90, 120+)",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/collections/cases/{id}/write-off": {
      "post": {
        "description": "Declares the account's debt uncollectible: writes off every open invoice of the case's account in billing, moves the case to `written_off` (a final status), and settles any active dunning status. A non-empty `reason` is required and is passed to each invoice write-off. A case that cannot move to written off returns 409. Requires collections:write.",
        "operationId": "writeOffCollectionCase",
        "parameters": [
          {
            "description": "Id of the collection case to write off (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Write off a case's open debt and close it",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/collections/eligible-cutoffs": {
      "get": {
        "description": "Lists, most overdue first, the accounts that the tenant's collection policy allows to be disconnected now: overdue past cutoff_past_due_days, owing at least cutoff_min_debt_cents, not on an active payment plan, with no disputed invoice, with an active connection, and not already pending cutoff or disconnected. The list is computed live from billing; page with `limit` (default 20, max 100) and the `after` cursor, which stays stable when an account pays between pages. Requires collections:read.",
        "operationId": "listEligibleCutoffs",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accounts past the tenant threshold, excluding active plans and disputes",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/collections/orders/generate": {
      "post": {
        "description": "Raises a disconnection field order for each currently eligible account, or only for the ids in `account_ids`. For each one it opens a case if none exists, moves the case to `enforcement_requested` with dunning set to cutoff pending, creates the order with the optional priority and scheduled_for, and emits a cutoff-order-generated event. It first defaults payment plans that are overdue past the grace period. An existing order on a case is reused, so repeating the call does not create duplicates; requested accounts that are not eligible come back in `skipped`. Returns 400 when field orders are not connected. Requires collections:write.",
        "operationId": "generateCutoffOrders",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "account_ids": {
                    "type": "array"
                  },
                  "priority": {
                    "type": "string"
                  },
                  "scheduled_for": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create disconnect field orders for eligible accounts",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/collections/payment-plans": {
      "get": {
        "description": "Returns a cursor-paginated list of the tenant's payment plans with their instalments, filterable by account_id, case_id and status. Page with `limit` (default 20, max 100) and the `after` cursor. Requires collections:read.",
        "operationId": "listCollectionPaymentPlans",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List payment plans",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      },
      "post": {
        "description": "Puts a collection case on an instalment plan and moves the case to `payment_plan_active`, which takes the account out of cutoff eligibility. installment_count defaults to 3, interval_months to 1 and first_due_date to one month from now; simple interest from interest_basis_points is added to the debt, with the rounding remainder on the last instalment. Interest is charged to the account in billing, and a payment-plan-created event is emitted. Returns 404 for an unknown case and 400 for negative interest. Requires collections:write.",
        "operationId": "createCollectionPaymentPlan",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "case_id": {
                    "type": "string"
                  },
                  "first_due_date": {
                    "type": "string"
                  },
                  "installment_count": {
                    "type": "integer"
                  },
                  "interest_basis_points": {
                    "type": "integer"
                  },
                  "interval_months": {
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a payment plan with installments and interest",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/collections/payment-plans/{id}": {
      "get": {
        "description": "Returns one payment plan with its totals, interest, remaining amount, next due date, status and the full instalment schedule. Returns 404 when the plan is not in this tenant. Requires collections:read.",
        "operationId": "getCollectionPaymentPlan",
        "parameters": [
          {
            "description": "Id of the payment plan (prefix `pln`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a plan with installments",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/collections/payment-plans/{id}/default": {
      "post": {
        "description": "Marks an active payment plan as defaulted, which makes the account eligible for cutoff again under the collection policy. Only an active plan can default; any other status returns 409. Plans are also defaulted automatically when an instalment is unpaid past the policy's grace period. Requires collections:write.",
        "operationId": "defaultCollectionPaymentPlan",
        "parameters": [
          {
            "description": "Id of the payment plan to default (prefix `pln`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Declare a plan defaulted",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/collections/policy": {
      "get": {
        "description": "Returns the tenant's disconnection policy: how many days past due an account must be (cutoff_past_due_days), the minimum overdue debt (cutoff_min_debt_cents), and how many days an unpaid instalment may be late before its plan defaults (plan_default_grace_days). When the tenant has not saved a policy, the defaults are returned: 30 days, 1 minor unit and 30 days. Requires collections:read.",
        "operationId": "getCollectionPolicy",
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the tenant cutoff policy",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      },
      "put": {
        "description": "Changes only the policy fields sent and returns the full policy; omitted fields keep their current or default values. Values must not be negative, otherwise 400. The new values apply on the next eligibility check, cutoff generation and plan-default sweep. Requires collections:write.",
        "operationId": "updateCollectionPolicy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "cutoff_min_debt_cents": {
                    "type": "integer"
                  },
                  "cutoff_past_due_days": {
                    "type": "integer"
                  },
                  "plan_default_grace_days": {
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update the tenant cutoff policy",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/collectors": {
      "get": {
        "description": "Returns a paginated list of the on-premises meter data collectors registered to the tenant, with their name, status, assignment revision and last-seen time. Collectors are created and credentialed on the platform API; this view is read-only. Requires the business:collectors:read permission.",
        "operationId": "listBusinessCollectors",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the utility collectors",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:collectors:read"
        ]
      }
    },
    "$BUSINESS_API/collectors/{id}": {
      "get": {
        "description": "Returns one collector registered to the tenant, with its status, assignment revision and last-seen time. Returns 404 when the collector does not belong to this tenant. Requires business:collectors:read.",
        "operationId": "getBusinessCollector",
        "parameters": [
          {
            "description": "Id of the collector registered to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a utility collector",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:collectors:read"
        ]
      }
    },
    "$BUSINESS_API/collectors/{id}/health": {
      "get": {
        "description": "Reports the collector's operational state computed from instance heartbeats at request time: an instance is online if seen within 90 seconds, degraded within 5 minutes, and offline after that. The response counts online, degraded and offline instances, lists them, gives the overall state (online if any instance is online), and counts active sessions and meter assignments. Returns 404 for a collector outside the tenant. Requires business:collectors:read.",
        "operationId": "getBusinessCollectorHealth",
        "parameters": [
          {
            "description": "Id of the collector whose health is computed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Operational health of a utility collector",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:collectors:read"
        ]
      }
    },
    "$BUSINESS_API/compliance/retention": {
      "get": {
        "description": "Returns the tenant's data retention period for each record class (audit_logs, readings, invoices, sessions), with `is_default` showing whether the built-in period applies (365, 1825, 3650 and 90 days respectively). When the background sweep has run, each class also shows the cutoff before which records are past retention, how many there are, and when they were marked. Requires compliance:read.",
        "operationId": "getRetentionSchedule",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetentionList"
                }
              }
            },
            "description": "Get the retention schedule"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the retention schedule",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "compliance:read"
        ]
      },
      "put": {
        "description": "Sets the retention period of the classes sent in `classes`; classes left out keep their current value, and the response is the full schedule. Each class must be one of audit_logs, readings, invoices or sessions, and retention_days must be between 1 and 36500; any invalid entry rejects the whole request with 400 before anything is saved. The change is written to the audit log, and the background sweep only marks expired records, it does not delete audit events. Requires compliance:retention.",
        "operationId": "putRetentionSchedule",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RetentionUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RetentionList"
                }
              }
            },
            "description": "Update retention days per class"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update retention days per class",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "compliance:retention"
        ]
      }
    },
    "$BUSINESS_API/connections": {
      "get": {
        "description": "Returns the tenant's service connections one cursor page at a time (limit defaults to 20, maximum 100). Besides paging, the handler accepts the filters customer_id, property_id, account_id, meter_id, category, status, service_status and q (free-text search that also matches account holders). Requires the connections:read permission in the authenticated utility tenant; a missing permission returns 403.",
        "operationId": "listConnections",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectionPage"
                }
              }
            },
            "description": "Service connections in the authenticated utility tenant"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List water service connections",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      },
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant. customer_id and property_id are required; omitted category defaults to residential and omitted or non-positive diameter_mm defaults to 15.",
        "operationId": "createConnection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConnectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Connection created"
          },
          "400": {
            "description": "Invalid request or connection data"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a new water service connection",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}": {
      "get": {
        "description": "Returns one connection of the authenticated tenant with its application status, service status, and linked customer, property, account and meter. Requires connections:read. Returns 404 when no connection with that ID exists in the tenant.",
        "operationId": "getConnection",
        "parameters": [
          {
            "description": "Identifier of the connection in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Service connection details"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get water service connection details",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      },
      "patch": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "updateConnection",
        "parameters": [
          {
            "description": "Identifier of the connection to update in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateConnectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Updated connection"
          },
          "400": {
            "description": "Invalid connection update"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update water service connection details",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/activate": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "activateConnection",
        "parameters": [
          {
            "description": "Identifier of the connection to activate; it must be in the approved or installing status, otherwise the request fails with 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "account_id": {
                    "type": "string"
                  },
                  "meter_id": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Activated connection"
          },
          "400": {
            "description": "Connection cannot be activated in its current state"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Complete installation and activate a connection",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/disconnect": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "disconnectConnectionForDebt",
        "parameters": [
          {
            "description": "Identifier of the connection to cut; it must be active or suspended, otherwise the request fails with 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Disconnected connection"
          },
          "400": {
            "description": "Connection is not active or suspended"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Cut a connection for non-payment (service_status cut_for_debt)",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata the tenant has stored on a connection, as a resource_type, resource_id and metadata object. A connection without metadata returns an empty map. Requires business:metadata:read; returns 404 when the connection does not exist in the tenant.",
        "operationId": "getBusinessConnectionMetadata",
        "parameters": [
          {
            "description": "Identifier of the connection whose metadata is read (at most 120 characters).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a connection",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the supplied keys into the connection's existing metadata and returns the full result; keys not in the request stay unchanged. A request may set at most 50 keys, each key at most 40 characters with no square brackets or control characters, and each value at most 500 characters; a resource may hold at most 50 keys in total. Requires business:metadata:write; invalid keys or values return 400 listing each offending field, and an unknown connection returns 404.",
        "operationId": "putBusinessConnectionMetadata",
        "parameters": [
          {
            "description": "Identifier of the connection whose metadata is merged (at most 120 characters).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/reconnect": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "reconnectConnection",
        "parameters": [
          {
            "description": "Identifier of the connection to restore; it must be suspended or disconnected, otherwise the request fails with 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Reconnected service"
          },
          "400": {
            "description": "Connection cannot be reconnected in its current state"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Restore a suspended or disconnected connection",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/retire": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "retireConnection",
        "parameters": [
          {
            "description": "Identifier of the connection to retire; a connection that is already retired returns 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Retired connection"
          },
          "400": {
            "description": "Connection cannot be retired in its current state"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Retire a water service connection",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/review": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "reviewConnection",
        "parameters": [
          {
            "description": "Identifier of the connection application to review; it must be in the submitted or inspecting status, otherwise the request fails with 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReviewConnectionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Reviewed connection application"
          },
          "400": {
            "description": "Connection cannot be reviewed in its current state"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve or reject a water service connection application",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/schedule-install": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "scheduleConnectionInstall",
        "parameters": [
          {
            "description": "Identifier of the connection to schedule; it must be in the approved status, otherwise the request fails with 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Installation scheduled"
          },
          "400": {
            "description": "Connection is not approved"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule installation of an approved connection",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/connections/{id}/suspend": {
      "post": {
        "description": "Requires connections:write in the authenticated utility tenant.",
        "operationId": "suspendConnection",
        "parameters": [
          {
            "description": "Identifier of the connection to suspend; it must be active, otherwise the request fails with 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterConnection"
                }
              }
            },
            "description": "Suspended connection"
          },
          "400": {
            "description": "Connection is not active"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Connection not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Suspend an active connection",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/consumptions": {
      "get": {
        "description": "Returns the tenant's stored consumption records, one cursor page at a time. Each record covers one meter and billing cycle, references the accepted readings it was computed from, and states whether it is actual or estimated. Requires business:consumptions:read; an unknown method value or an invalid cursor returns 400.",
        "operationId": "listAcceptedConsumptions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only consumptions computed for this meter ID.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only consumptions belonging to this account ID (the account the meter was assigned to when the consumption was recorded).",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only consumptions recorded for this billing cycle identifier.",
            "in": "query",
            "name": "cycle_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only consumptions of this kind: actual when both readings were actual, estimated when either reading was estimated; empty returns both.",
            "in": "query",
            "name": "method",
            "schema": {
              "enum": [
                "actual",
                "estimated"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Consumption records with selected reading IDs preserved"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List immutable consumption records selected from accepted readings",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:consumptions:read"
        ]
      },
      "post": {
        "description": "Computes consumption for one meter between period_start and period_end and stores it as an immutable record for the given cycle_id. The baseline is the latest accepted reading at or before the period start (or the meter's installation time if it was installed inside the period) and the end is the latest accepted reading at or before period_end; meter resets and rollovers in between are accounted for. The result is marked estimated when either reading was estimated. Requires business:consumptions:create; missing fields or period_end not after period_start return 400, an unknown meter returns 404, and 409 is returned when no usable pair of accepted readings exists or a consumption already exists for that meter and cycle.",
        "operationId": "createAcceptedConsumption",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Consumption"
                }
              }
            },
            "description": "Consumption selected and recorded for billing"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Select accepted readings and persist immutable meter consumption",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:consumptions:create"
        ]
      }
    },
    "$BUSINESS_API/credit-grants": {
      "get": {
        "description": "Requires invoices:read. Newest first, one cursor page at a time.",
        "operationId": "listCreditGrants",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only grants in this status: pending_approval, active, exhausted, expired or rejected; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending_approval",
                "active",
                "exhausted",
                "expired",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "description": "Return only grants made to this account ID.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/CreditGrant"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data",
                    "has_more"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Grant page"
          },
          "400": {
            "description": "Unknown status or invalid cursor"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the utility's credit grants, such as those waiting for approval",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      },
      "post": {
        "description": "Creates a credit for one account; account_id and a positive amount_minor are required. Unless requires_approval is true the grant is active immediately: a grant transaction is recorded and the credit is applied to the account's open invoices, and the response shows the remaining amount after that. With requires_approval true the grant is stored as pending_approval and a different user must approve it. Optional fields default to funding granted, source promotion, applies_to water_invoice and charge_kinds water and sanitation; requires invoices:write.",
        "operationId": "createCreditGrant",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Credit grant created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Grant promotional or manual account credit",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/credit-grants/bulk": {
      "post": {
        "description": "Creates one active granted credit per account in account_ids, each for the same amount_minor, and applies each to that account's open invoices. The response reports how many grants were created and lists them. Grants are created one at a time without a transaction, so if one account fails the request returns the error and the grants already created remain. Requires invoices:write; an empty account_ids or a non-positive amount returns 400.",
        "operationId": "bulkCreateCreditGrants",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Bulk credit grants created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Bulk grant promotional credits to multiple accounts",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/credit-grants/liability": {
      "get": {
        "description": "Summarizes the tenant's outstanding granted credit: the unapplied remaining amount of active, unexpired granted-funding grants, how many such grants exist, and how much of that amount expires within the next 30 days. The response also lists the tenant's credit campaigns. Requires invoices:read.",
        "operationId": "getCreditLiabilityReport",
        "responses": {
          "200": {
            "description": "Credit liability report"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get unapplied granted-credit liability and campaign summary",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/credit-grants/{id}/approve": {
      "post": {
        "description": "Activates a grant that is pending approval, records the grant transaction and applies the credit to the account's open invoices, then returns the updated grant. The user who proposed the grant cannot approve it. Requires invoices:write; a grant that is not pending approval, or approval by its proposer, returns 400, and an unknown grant returns 404.",
        "operationId": "approveCreditGrant",
        "parameters": [
          {
            "description": "Identifier of the credit grant to approve; it must be in the pending_approval status.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Credit grant approved"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve a pending credit grant (maker-checker)",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/credit-grants/{id}/reject": {
      "post": {
        "description": "Marks a pending grant as rejected, stores the rejection reason and sets its remaining amount to zero, so no credit is ever applied. A non-empty reason is required. Requires invoices:write; a missing reason or a grant that is not pending approval returns 400, and an unknown grant returns 404.",
        "operationId": "rejectCreditGrant",
        "parameters": [
          {
            "description": "Identifier of the credit grant to reject; it must be in the pending_approval status.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Credit grant rejected"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a pending credit grant",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/crews": {
      "get": {
        "description": "Returns the tenant's maintenance crews one cursor page at a time. The handler also accepts status (available, dispatched or off_duty) and q (free-text search) filters. Requires the crews:read scope.",
        "operationId": "listCrews",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Maintenance crews"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List maintenance crews",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "crews:read"
        ]
      },
      "post": {
        "description": "Creates a crew in the tenant with the available status. name and lead_technician are required; contact_phone and skills are optional. Requires operations:write; missing required fields or an invalid body return 400.",
        "operationId": "createCrew",
        "responses": {
          "201": {
            "description": "Maintenance crew registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a maintenance crew",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/crews/{id}": {
      "get": {
        "description": "Returns one crew of the authenticated tenant with its lead technician, contact phone, skills and current status (available, dispatched or off_duty). Requires crews:read; an unknown crew returns 404.",
        "operationId": "getCrew",
        "parameters": [
          {
            "description": "Identifier of the maintenance crew in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Maintenance crew details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get maintenance crew details",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "crews:read"
        ]
      }
    },
    "$BUSINESS_API/customers": {
      "get": {
        "description": "Returns the tenant's customers one cursor page at a time; the filters combine. Requires business:customers:read; an invalid limit or cursor returns 400.",
        "operationId": "listCustomers",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "description": "Return only customers of this type: individual or business.",
            "in": "query",
            "name": "customer_type",
            "schema": {
              "enum": [
                "individual",
                "business"
              ],
              "type": "string"
            }
          },
          {
            "description": "Return only customers in this tariff category: residential, commercial, industrial, institutional or government.",
            "in": "query",
            "name": "category",
            "schema": {
              "enum": [
                "residential",
                "commercial",
                "industrial",
                "institutional",
                "government"
              ],
              "type": "string"
            }
          },
          {
            "description": "Return only customers in this status: active, suspended or closed.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "active",
                "suspended",
                "closed"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerPage"
                }
              }
            },
            "description": "Utility customers in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility customers using resource filters and cursor pagination",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:customers:read"
        ]
      },
      "post": {
        "description": "Creates a customer in the authenticated tenant with the active status. display_name, a valid customer_type (individual or business) and a valid category are required; tax_number, email and phone are optional and trimmed. Requires business:customers:create; invalid input returns 400. Creating a customer does not create an account or property, which are separate resources.",
        "operationId": "createCustomer",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateCustomer"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            },
            "description": "Customer registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a utility customer",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:customers:create"
        ]
      }
    },
    "$BUSINESS_API/customers/import": {
      "post": {
        "description": "Creates each valid row of the dry run through the customer service, once per idempotency key (body idempotency_key or the Idempotency-Key header): the same key returns the first answer and creates nothing more; another key returns 409. A dry run with no valid rows returns 400; a stale one (over 24 hours) returns 409. A confirm that creates at least one customer completes the utility_real customer_import step. Requires business:customers:create.",
        "operationId": "confirmCustomerImport",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerImportConfirmRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerImportResult"
                }
              }
            },
            "description": "The confirmation, with the created customer per row"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing key, or no valid rows"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing business:customers:create"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Dry run not found for this utility"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Already confirmed with another key, or stale"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm a customer import dry run"
      }
    },
    "$BUSINESS_API/customers/import/dry-run": {
      "post": {
        "description": "Parses and validates the CSV (at most 2000 rows and 2 MiB) and returns every row with its normalized data and errors by field; rows that repeat a phone or e-mail of an earlier row are errors. Nothing is written except the dry run itself, which can be confirmed for 24 hours. Requires business:customers:create.",
        "operationId": "dryRunCustomerImport",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerImportDryRunRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerImportResult"
                }
              }
            },
            "description": "The dry run"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unreadable CSV, unknown column, no rows or too many rows"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing business:customers:create"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Validate a customer CSV without writing anything"
      }
    },
    "$BUSINESS_API/customers/import/template": {
      "get": {
        "description": "Requires business:customers:create. The CSV header the import reads: display_name (required), customer_type (individual or business, default individual), category (residential, commercial, industrial, institutional or government, default residential), phone, email, tax_number.",
        "operationId": "getCustomerImportTemplate",
        "responses": {
          "200": {
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "The CSV template"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing business:customers:create"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the customer import CSV template"
      }
    },
    "$BUSINESS_API/customers/{id}": {
      "get": {
        "description": "Returns one customer with its type, category, contact details and status. Requires business:customers:read; an unknown customer returns 404.",
        "operationId": "getCustomer",
        "parameters": [
          {
            "description": "Identifier of the customer in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Customer"
                }
              }
            },
            "description": "Customer resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a customer in the authenticated utility tenant",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:customers:read"
        ]
      }
    },
    "$BUSINESS_API/customers/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata the tenant has stored on a customer, as a resource_type, resource_id and metadata object. A customer without metadata returns an empty map. Requires business:metadata:read; returns 404 when the customer does not exist in the tenant.",
        "operationId": "getBusinessCustomerMetadata",
        "parameters": [
          {
            "description": "Identifier of the customer whose metadata is read (at most 120 characters).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a customer",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the supplied keys into the customer's existing metadata and returns the full result; keys not in the request stay unchanged. A request may set at most 50 keys, each key at most 40 characters with no square brackets or control characters, and each value at most 500 characters; a resource may hold at most 50 keys in total. Requires business:metadata:write; invalid keys or values return 400 listing each offending field, and an unknown customer returns 404.",
        "operationId": "putBusinessCustomerMetadata",
        "parameters": [
          {
            "description": "Identifier of the customer whose metadata is merged (at most 120 characters).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/customers/{id}/statement.pdf": {
      "get": {
        "description": "Renders the customer's statement of account for a date range and returns it as an inline application/pdf file. Movements before from are summed into the opening balance, and movements inside the range are listed in date order with debits and credits. Without from and to the range is the last year up to today; dates use YYYY-MM-DD, and a malformed date or from after to returns 400. Returns 403 when the caller may not read the customer's statement and 404 when the customer does not exist.",
        "operationId": "getCustomerStatementPDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Customer id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Start of the statement (YYYY-MM-DD); defaults to one year before to",
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date",
              "type": "string"
            }
          },
          {
            "description": "End of the statement (YYYY-MM-DD); defaults to today",
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a customer statement of account as PDF",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:customers:read"
        ]
      }
    },
    "$BUSINESS_API/decision-policies/{type}": {
      "get": {
        "description": "Returns the tenant's decision policy for one approval type, with its mode and current version. When the tenant has never configured that type, a default policy in human mode is returned without being saved. Requires automations:read; an unknown approval type returns 400.",
        "operationId": "getDecisionPolicy",
        "parameters": [
          {
            "description": "Approval type: billing_posting, price_version_publication, manual_journal_entry, supplier_payout, refund, write_off or cut_approval.",
            "in": "path",
            "name": "type",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Policy with its current mode, limits and version"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the decision policy of an approval type",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      },
      "put": {
        "description": "Saves a new immutable version of the approval type's policy (mode, condition group, limits, sampling percent and explanation) and increments the policy version; the first update creates the policy. Every approval type currently has a platform minimum of human review, so any mode other than human is refused with 400. An invalid condition group or a sampling_percent outside 0 to 100 also returns 400. Requires automations:write.",
        "operationId": "updateDecisionPolicy",
        "parameters": [
          {
            "description": "Approval type: billing_posting, price_version_publication, manual_journal_entry, supplier_payout, refund, write_off or cut_approval.",
            "in": "path",
            "name": "type",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "condition_group": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "explanation": {
                    "type": "string"
                  },
                  "limits": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "mode": {
                    "enum": [
                      "automatic",
                      "human",
                      "sampled"
                    ],
                    "type": "string"
                  },
                  "sampling_percent": {
                    "maximum": 100,
                    "minimum": 0,
                    "type": "integer"
                  }
                },
                "required": [
                  "mode"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated policy"
          },
          "400": {
            "description": "RFC 7807 validation problem, including a platform minimum"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Configure an approval type's mode, conditions and limits",
        "x-roles": [
          "admin",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:write"
        ]
      }
    },
    "$BUSINESS_API/decision-policies/{type}/simulate": {
      "post": {
        "description": "Evaluates the current policy version against the supplied case (amount_cents and inputs) and returns the outcome: automatic, pending_human, approved or rejected. The decision is always saved to the decision log, so this call is not a dry run. When approved is set, the decision records a human approval or rejection by the caller, which also requires the write scope for that approval type (for example refund needs payments:write). Requires automations:read; an unknown approval type returns 400.",
        "operationId": "simulateDecisionPolicy",
        "parameters": [
          {
            "description": "Approval type to evaluate: billing_posting, price_version_publication, manual_journal_entry, supplier_payout, refund, write_off or cut_approval.",
            "in": "path",
            "name": "type",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount_cents": {
                    "type": "integer"
                  },
                  "approved": {
                    "type": "boolean"
                  },
                  "decided_by": {
                    "type": "string"
                  },
                  "inputs": {
                    "additionalProperties": true,
                    "type": "object"
                  },
                  "subject_id": {
                    "type": "string"
                  },
                  "subject_type": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Decision with policy version, outcome and explanation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Evaluate a policy against one case and record the decision",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/decisions": {
      "get": {
        "description": "Returns the tenant's decision log one cursor page at a time. Each entry records the policy and version applied, the subject, the inputs, the mode, the outcome and its explanation, and who decided. Requires automations:read.",
        "operationId": "listDecisions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only decisions of this approval type (for example refund or write_off); empty returns every type.",
            "in": "query",
            "name": "approval_type",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Decisions, newest first"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List automatic and human decisions",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "automations:read"
        ]
      }
    },
    "$BUSINESS_API/definitions": {
      "get": {
        "description": "Returns the report definitions the tenant can run, one cursor page at a time: its own definitions plus the platform-wide ones. The handler also accepts a category filter. Requires reports:read.",
        "operationId": "listBusinessReportDefinitions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Report definitions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility report definitions",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      },
      "post": {
        "description": "Creates a report definition scoped to the authenticated tenant. key, name and dataset_key are required; description and category are optional. The key must be unique within the tenant, and a duplicate returns 409. Requires reports:write.",
        "operationId": "createBusinessReportDefinition",
        "responses": {
          "201": {
            "description": "Definition created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create utility report definition",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:write"
        ]
      }
    },
    "$BUSINESS_API/definitions/{id}": {
      "get": {
        "description": "Returns one report definition that the tenant can see, either its own or a platform-wide one. Requires reports:read; a definition belonging to another tenant, or an unknown ID, returns 404.",
        "operationId": "getBusinessReportDefinition",
        "parameters": [
          {
            "description": "Identifier of the report definition.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Report definition"
          },
          "403": {
            "description": "Missing reports:read scope"
          },
          "404": {
            "description": "Definition not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a utility report definition",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      }
    },
    "$BUSINESS_API/developer/api-keys": {
      "get": {
        "description": "Returns the API keys that belong to the caller's context (the tenant, or the organization when no tenant is selected), one cursor page at a time. Keys are identified by prefix and last four characters; the secret is never returned again. Each key reports its computed status (for example active, expired or revoked). Requires developer:read.",
        "operationId": "listDeveloperApiKeys",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKeyPage"
                }
              }
            },
            "description": "API keys"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List API keys by prefix and last four",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      },
      "post": {
        "description": "Issues a key in the caller's context and returns its full secret only in this response. A secret key (no scopes given) receives every grantable scope the caller holds; a restricted key needs at least one scope, and every scope must be in the catalog and held by the caller. Mode defaults to live: test keys are issued only in a sandbox tenant, a sandbox issues only test keys, and test keys cannot hold money-moving write scopes outside a sandbox. The request must come from a person, not an API key, and needs developer:write; a missing or over-long name (128 characters), an unknown scope, a past expires_at or a mode mismatch returns 400, and a scope the caller lacks returns 403.",
        "operationId": "createDeveloperApiKey",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeveloperApiKey"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKey"
                }
              }
            },
            "description": "Key created; secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a secret or restricted API key; the full key appears once in the response",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/api-keys/{id}": {
      "delete": {
        "description": "Ends the key at once, so requests made with it fail from now on, and writes an audit record. The request must come from a person, not an API key, and needs developer:write. An unknown key returns 404.",
        "operationId": "revokeDeveloperApiKey",
        "parameters": [
          {
            "description": "Identifier of the API key to revoke, in the caller's context.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a key immediately",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/api-keys/{id}/roll": {
      "post": {
        "description": "Issues a replacement key with the same name, kind, mode, scopes, allowed IPs and expiry, returns its secret once, and keeps the old key valid for overlap_seconds (default 24 hours, maximum 7 days, never past the old key's own expiry). Only an active key that has not already been rolled can be rolled; otherwise the response is 409. The request must come from a person, needs developer:write, and the caller must hold every scope the key carries, or the response is 403.",
        "operationId": "rollDeveloperApiKey",
        "parameters": [
          {
            "description": "Identifier of the active API key to replace, in the caller's context.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeveloperRoll"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKey"
                }
              }
            },
            "description": "Replacement key; secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace a key, keeping the old one valid for the overlap",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/cli-sessions": {
      "get": {
        "description": "Returns the tenant's live CLI sessions, newest first, with cursor pagination, so the dashboard can show who is listening and to which events. Secrets are never returned here. Requires developer:read.",
        "operationId": "listDeveloperCliSessions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/DeveloperCliSession"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Live sessions"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the CLI sessions listening now",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      },
      "post": {
        "description": "Opens a session for the CLI's webhooks listen command: a temporary endpoint that receives the tenant's new events, signed with its own whsec_ secret, returned once in this response. events limits the session to some event types; empty means every type. The session lives while the CLI polls it and expires about 90 seconds after the last poll. Requires developer:write.",
        "operationId": "createDeveloperCliSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeveloperCliSessionRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperCliSession"
                }
              }
            },
            "description": "Session, with its secret shown once"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a temporary webhook endpoint for the CLI",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/cli-sessions/{id}": {
      "delete": {
        "description": "Ends a CLI session at once; the CLI calls this when it exits. Only the user who opened the session can end it. Requires developer:write.",
        "operationId": "deleteDeveloperCliSession",
        "parameters": [
          {
            "description": "Identifier of the CLI session to end.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Session ended"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Unknown or expired session"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "End a CLI session",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/cli-sessions/{id}/events": {
      "get": {
        "description": "Long-polls a CLI session: returns the events published since the previous poll, oldest first and at most 50, each with its genuine payload and the Standard Webhooks headers signed with the session secret. When none is ready the request is held for up to wait seconds. Each poll extends the session. Only the user who opened the session can poll it; an expired or unknown session returns 404. Requires developer:read.",
        "operationId": "pollDeveloperCliSession",
        "parameters": [
          {
            "description": "Identifier of the CLI session, as returned when it was opened.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Seconds to hold the request while no event is ready, from 0 (answer at once) to 25.",
            "in": "query",
            "name": "wait",
            "required": false,
            "schema": {
              "maximum": 25,
              "minimum": 0,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperCliSessionPoll"
                }
              }
            },
            "description": "Events since the previous poll"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Unknown or expired session"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Wait for the next events of a CLI session",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/deliveries/{id}": {
      "get": {
        "description": "Returns one webhook delivery with its status, the event payload it carries and the history of every attempt (response status, error, response body and duration), oldest first. Requires developer:read; an unknown delivery returns 404. The same operation is also served at /developer/webhooks/deliveries/{id}.",
        "operationId": "getDeveloperDelivery",
        "parameters": [
          {
            "description": "Identifier of the webhook delivery in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperDelivery"
                }
              }
            },
            "description": "Delivery"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a delivery with its payload and attempts",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/deliveries/{id}/retry": {
      "post": {
        "description": "Resets a delivery to pending, makes it due now with a fresh attempt budget and wakes the delivery worker; the response is 202 with the updated delivery. Ordering per resource still applies, so it can wait behind an earlier undelivered event about the same resource. Requires developer:write; 409 is returned when the delivery is being attempted right now or its webhook no longer exists, and 404 when the delivery is unknown.",
        "operationId": "retryDeveloperDelivery",
        "parameters": [
          {
            "description": "Identifier of the webhook delivery to retry.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperDelivery"
                }
              }
            },
            "description": "Delivery"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Make a delivery due now",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/event-types": {
      "get": {
        "description": "Returns the catalog of event types a webhook endpoint can subscribe to, each with its type name, category and description. Use these names (or * for every event) in a webhook's events list. Requires developer:read.",
        "operationId": "getDeveloperEventTypes",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperEventTypes"
                }
              }
            },
            "description": "Event types"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Webhook event type catalog",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/events": {
      "get": {
        "description": "Returns the domain events published for the tenant, one cursor page at a time, without their payloads; fetch one event to see its payload. Filters: type, resource_type and resource_id match exactly, and from and to are RFC 3339 timestamps bounding the creation time. Each event states when it stops being available for replay. Requires developer:read; a malformed timestamp returns 400.",
        "operationId": "listDeveloperEvents",
        "parameters": [
          {
            "description": "Event type",
            "in": "query",
            "name": "type",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource type",
            "in": "query",
            "name": "resource_type",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource id",
            "in": "query",
            "name": "resource_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 start",
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 end",
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperEventPage"
                }
              }
            },
            "description": "Events"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List published domain events",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/events/{id}": {
      "get": {
        "description": "Returns one published event with its full payload and every webhook delivery created for it, plus when it stops being available for replay. Requires developer:read; an unknown event returns 404.",
        "operationId": "getDeveloperEvent",
        "parameters": [
          {
            "description": "Identifier of the published event in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperEvent"
                }
              }
            },
            "description": "Event"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an event with its payload and deliveries",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/logs": {
      "get": {
        "description": "Returns logged business API requests for the tenant, one cursor page at a time, without request or response bodies. By default only requests made with API keys are listed; pass principal_type, or include_sessions=true, to see other traffic. Filters: status is a class such as 4xx, method matches case-insensitively, path is a prefix, key matches an API key ID or prefix, request_id matches exactly, and from and to are RFC 3339 timestamps. Requires developer:read; an invalid status class or timestamp returns 400.",
        "operationId": "listDeveloperRequestLogs",
        "parameters": [
          {
            "description": "Status class: 2xx, 4xx, 5xx ...",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "HTTP method",
            "in": "query",
            "name": "method",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Path prefix",
            "in": "query",
            "name": "path",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "API key id or prefix",
            "in": "query",
            "name": "key",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact request id, as returned in X-Request-Id and in error responses",
            "in": "query",
            "name": "request_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 start",
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 end",
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperRequestLogPage"
                }
              }
            },
            "description": "Request logs"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List business API requests",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/logs/{id}": {
      "get": {
        "description": "Returns one logged request with its method, path, status, duration, caller and API key, and request and response bodies with sensitive fields redacted. Requires developer:read; an unknown log returns 404.",
        "operationId": "getDeveloperRequestLog",
        "parameters": [
          {
            "description": "Identifier of the request log entry in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperRequestLog"
                }
              }
            },
            "description": "Request log"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a request log with redacted bodies",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/overview": {
      "get": {
        "description": "Summarizes the tenant's API traffic and webhook deliveries over a window given by from and to (RFC 3339), which defaults to the last 24 hours and may span at most 90 days. Request statistics are bucketed hourly, or daily when the window exceeds 48 hours; the response also counts active API keys, enabled webhooks and request logs dropped under load. Requires developer:read; a malformed timestamp or an invalid window returns 400.",
        "operationId": "getDeveloperOverview",
        "parameters": [
          {
            "description": "RFC 3339 start; defaults to 24 hours before to",
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 end; defaults to now",
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperOverview"
                }
              }
            },
            "description": "Overview"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Requests, error rate, latency and webhook success over a window",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/scopes": {
      "get": {
        "description": "Returns the scopes the caller can put on a restricted API key in the current context: the catalog of grantable scopes narrowed to those the caller holds. A secret key created now would carry this same list. Requires developer:read.",
        "operationId": "getDeveloperScopes",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperScopes"
                }
              }
            },
            "description": "Grantable scopes"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Scopes the caller can put on an API key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks": {
      "get": {
        "description": "Returns the tenant's webhook endpoints, one cursor page at a time, with their URL, subscribed events, enabled flag and health. Signing secrets are not included. Requires developer:read.",
        "operationId": "listDeveloperWebhooks",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhookPage"
                }
              }
            },
            "description": "Endpoints"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List webhook endpoints",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      },
      "post": {
        "description": "Registers an endpoint and returns its signing secret only in this response. The URL must be absolute https, without credentials or a fragment, at most 2048 characters, and must resolve to a public address; internal host names and private, loopback or link-local addresses are refused with 400. At least one known event type (or *) is required, description is limited to 512 characters, and enabled defaults to true. Requires developer:write.",
        "operationId": "createDeveloperWebhook",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeveloperWebhook"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhook"
                }
              }
            },
            "description": "Endpoint created; secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a webhook endpoint; the signing secret appears once in the response",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}": {
      "delete": {
        "description": "Requires the developer:write scope. The endpoint is removed permanently, and in the same transaction every delivery still pending or paused for it is marked cancelled with the reason \"endpoint deleted\"; deliveries already completed keep their history. Answers 204 with no body, or 404 when no endpoint with this id exists in the caller's tenant. The deletion is recorded in the audit trail.",
        "operationId": "deleteDeveloperWebhook",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint to delete, matched within the caller's tenant only.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a webhook endpoint and cancel its pending deliveries",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      },
      "get": {
        "description": "Returns one webhook endpoint with its URL, description, subscribed events, enabled flag and delivery health; the signing secret is not included. Requires developer:read; an unknown endpoint returns 404.",
        "operationId": "getDeveloperWebhook",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint in the authenticated tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhook"
                }
              }
            },
            "description": "Endpoint"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a webhook endpoint",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      },
      "patch": {
        "description": "Changes only the fields supplied: url (checked against the same public https rules as on creation), description (512 characters at most), events and enabled. Setting enabled to false pauses the endpoint and holds its deliveries rather than cancelling them; setting it back to true resumes them in order. Requires developer:write; invalid fields return 400 and an unknown endpoint returns 404. The same operation is also served with PUT.",
        "operationId": "updateDeveloperWebhook",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint to change.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDeveloperWebhook"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhook"
                }
              }
            },
            "description": "Endpoint"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a webhook endpoint",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      },
      "put": {
        "description": "Served by the same handler as the PATCH operation on this path and behaves the same way: only the fields present in the body change, so omitted fields keep their current values rather than being cleared. url is checked against the same public https rules as on creation, description may hold at most 512 characters, and events must name known event types. Setting enabled to false pauses the endpoint and holds its deliveries; setting it back to true resumes them in order. Requires developer:write. Invalid fields or a refused url return 400, a missing scope returns 403 and an unknown endpoint returns 404.",
        "operationId": "replaceDeveloperWebhook",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint to change, matched within the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDeveloperWebhook"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhook"
                }
              }
            },
            "description": "Endpoint after the change"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No webhook endpoint with this id in the caller's tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a webhook endpoint with PUT",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}/deliveries": {
      "get": {
        "description": "Requires the developer:read scope. Returns one page of this endpoint's deliveries ordered by creation time, using the limit and after cursor parameters, and the status query parameter narrows the list to deliveries in exactly that state. Answers 404 when the endpoint does not exist in the caller's tenant; to see a delivery's payload and attempt history, read it by its own id.",
        "operationId": "listDeveloperWebhookDeliveries",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint whose deliveries are listed; it must exist in the caller's tenant or the request answers 404.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "pending, delivering, succeeded, failed or cancelled",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperDeliveryPage"
                }
              }
            },
            "description": "Deliveries"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List an endpoint's deliveries",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}/redeliveries": {
      "post": {
        "description": "Deliveries are re-queued in order per resource. With dry_run the count is returned and nothing changes.",
        "operationId": "createDeveloperWebhookRedelivery",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint whose deliveries are re-queued; it must exist in the caller's tenant or the request answers 404.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeveloperRedelivery"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperRedelivery"
                }
              }
            },
            "description": "Dry run count"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperRedelivery"
                }
              }
            },
            "description": "Deliveries re-queued"
          },
          "400": {
            "description": "Invalid window, status or event type (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Endpoint not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Re-queue an endpoint's failed or paused deliveries in a window of at most 7 days",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}/redeliveries/{redeliveryId}": {
      "get": {
        "description": "Requires the developer:read scope. Returns a bulk redelivery created earlier for this endpoint: its time window, the event types and delivery statuses it selected, how many deliveries it re-queued, who created it and when. Dry runs are not stored, so they cannot be read back here. Answers 404 when the redelivery does not exist or belongs to a different endpoint.",
        "operationId": "getDeveloperWebhookRedelivery",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint the redelivery was created for, matched within the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the redelivery, as returned when it was created; it is only found under the endpoint it was created for.",
            "in": "path",
            "name": "redeliveryId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperRedelivery"
                }
              }
            },
            "description": "The redelivery"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a bulk redelivery",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:read"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}/resume": {
      "post": {
        "description": "Requires the developer:write scope. The endpoint URL is checked again as a delivery target first, and a refused target answers 400 naming the url field. On success the endpoint is enabled and marked healthy, its pause reason and failure count are cleared, and every delivery held as paused is set back to pending for immediate sending; the updated endpoint is returned. Answers 404 when the endpoint does not exist in the caller's tenant.",
        "operationId": "resumeDeveloperWebhook",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint to resume, matched within the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhook"
                }
              }
            },
            "description": "The resumed endpoint"
          },
          "400": {
            "description": "The endpoint's address is no longer allowed (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Endpoint not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Resume a paused endpoint; its held deliveries are sent in order",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}/roll": {
      "post": {
        "description": "Requires the developer:write scope. A new signing secret is generated and returned once in the secret field of the 201 response, so store it right away. The optional overlap_seconds body field sets how long the previous secret keeps signing alongside the new one, from 0 to 604800 seconds (7 days) with a default of 24 hours, and 0 retires the old secret immediately; a value out of range answers 400. Answers 404 when the endpoint does not exist in the caller's tenant.",
        "operationId": "rollDeveloperWebhookSecret",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint whose signing secret is replaced, matched within the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeveloperRoll"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperWebhook"
                }
              }
            },
            "description": "New secret; shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Roll a signing secret; both secrets sign during the overlap",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/developer/webhooks/{id}/test": {
      "post": {
        "description": "Requires the developer:write scope. A test event is published to this endpoint only and goes through the normal delivery queue, signing and retries; the response is 202 with the queued delivery, which you can follow through the deliveries endpoints. Answers 409 when the endpoint is disabled or paused, so enable or resume it first, and 404 when it does not exist in the caller's tenant.",
        "operationId": "testDeveloperWebhook",
        "parameters": [
          {
            "description": "Identifier of the webhook endpoint that receives the test event, matched within the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperDelivery"
                }
              }
            },
            "description": "Queued delivery"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue a sample event for one endpoint",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "developer:write"
        ]
      }
    },
    "$BUSINESS_API/disconnection-notices": {
      "get": {
        "description": "Returns every disconnection notice issued in the tenant across all collection cases, newest first, with notice and cut-off dates, delivery method and status (issued, delivered or resolved). Results are cursor-paginated (default 20, maximum 100 per page); the handler also accepts account_id and case_id query filters. Requires the collections:read permission.",
        "operationId": "listDisconnectionNotices",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Disconnection notices"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List issued disconnection notices",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/dmas": {
      "get": {
        "description": "Returns the tenant's district metered areas (DMAs), newest first, with their code, name, service area, inflow and outflow meters and target pressure. Results are cursor-paginated (default 20, maximum 100); the handler also accepts service_area_id and a q search that matches name or code. Requires the network:read permission.",
        "operationId": "listDMAs",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistrictMeteredAreaPage"
                }
              }
            },
            "description": "DMAs"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List District Metered Areas",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "post": {
        "description": "Creates a district metered area in the tenant and returns it with 201. code, name and service_area_id are required (400 when missing); inflow_meter_id, outflow_meter_id and target_pressure_bar are optional, and the inflow meter is what night-flow analysis reads. A duplicate DMA code returns 409. Requires the network:write permission.",
        "operationId": "createDMA",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDMARequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistrictMeteredArea"
                }
              }
            },
            "description": "DMA registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a DMA",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/dmas/{id}": {
      "get": {
        "description": "Returns one district metered area of the tenant, including its code, service area, inflow and outflow meter references and target pressure. Returns 404 when the DMA does not exist in the tenant. Requires the network:read permission.",
        "operationId": "getDMA",
        "parameters": [
          {
            "description": "Identifier of the district metered area (a dma_ prefixed ID) within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistrictMeteredArea"
                }
              }
            },
            "description": "District Metered Area details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get District Metered Area details",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "put": {
        "description": "Changes only the fields present in the body (name, service_area_id, inflow_meter_id, outflow_meter_id, target_pressure_bar) and returns the updated DMA; the code cannot be changed. name and service_area_id may not be set to an empty string (400), while the meter references can be cleared with an empty string. Returns 404 for an unknown DMA. Requires the network:write permission.",
        "operationId": "updateDMA",
        "parameters": [
          {
            "description": "Identifier of the district metered area to update within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateDMARequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DistrictMeteredArea"
                }
              }
            },
            "description": "Updated DMA"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a DMA's name, service area, inflow and outflow meters or target pressure",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/dmas/{id}/night-flow": {
      "get": {
        "description": "Reads the DMA's inflow device measurements and reports, for each local night in the window, the mean flow in litres per second between 02:00 and 04:00, compared with the median of up to seven preceding nights (at least three are needed for a baseline). A night whose excess over the baseline is above threshold_percent is flagged burst_suspected; nights with fewer than two samples are insufficient_data. When the DMA has no inflow meter the report is returned with a warning and no values. The window must be at most 366 days with to after from (400 otherwise); 404 for an unknown DMA.",
        "operationId": "getDmaNightFlow",
        "parameters": [
          {
            "description": "Identifier of the district metered area whose inflow device is analysed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required start of the window as an RFC 3339 timestamp; the first reported night is the local calendar day containing it.",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required end of the window as an RFC 3339 timestamp; it must be after from and no more than 366 days later.",
            "in": "query",
            "name": "to",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "IANA time zone name (for example Africa/Maputo) used to place the 02:00-04:00 window and night dates; defaults to UTC, and an unknown zone returns 400.",
            "in": "query",
            "name": "timezone",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Positive percentage above the baseline at which a night is flagged as burst suspected; defaults to 30, and zero, negative or non-numeric values return 400.",
            "in": "query",
            "name": "threshold_percent",
            "required": false,
            "schema": {
              "type": "number"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NightFlowReport"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          },
          "404": {
            "description": "DMA not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Minimum night flow 02:00-04:00 per local night with burst suspicion",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/dmas/{id}/water-balance": {
      "get": {
        "description": "Computes an IWA-style water balance for one DMA over the window: system input volume, billed and unbilled authorised consumption, water losses and non-revenue water in litres, with non-revenue water as basis points of system input. Losses are split into apparent and real only when apparent_loss_bp is given, otherwise the split is reported as insufficient data; a status and warnings say when data is partial or missing. The window must be at most 366 days with to after from (400 otherwise); 404 for an unknown DMA. Requires the network:read permission.",
        "operationId": "getDmaWaterBalance",
        "parameters": [
          {
            "description": "Identifier of the district metered area to balance.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required start of the balance period as an RFC 3339 timestamp.",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required end of the balance period as an RFC 3339 timestamp; it must be after from and no more than 366 days later.",
            "in": "query",
            "name": "to",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional assumed apparent loss (meter under-registration and unauthorised use) as basis points of authorised consumption, an integer from 0 to 10000; when it exceeds total losses it is capped with a warning.",
            "in": "query",
            "name": "apparent_loss_bp",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IWAWaterBalance"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          },
          "404": {
            "description": "DMA not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "IWA water balance of one DMA",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/events": {
      "get": {
        "description": "Returns the tenant's hash-chained audit events, each with a localized human-readable summary, a summary code and parameters. Filters combine (actor, exact action, resource type and ID, RFC 3339 from/to; unparseable dates are ignored) and results are cursor-paginated (default 20, maximum 100). Requires the audit:read permission.",
        "operationId": "listAuditEvents",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Filter by resource type, e.g. customer, account, property, meter, connection, invoice, payment, ticket, work_order, incident, tariff, onboarding",
            "in": "query",
            "name": "resource_type",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by resource identifier, for a record page's history",
            "in": "query",
            "name": "resource_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by exact action code",
            "in": "query",
            "name": "action",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by actor",
            "in": "query",
            "name": "actor_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC3339 start",
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC3339 end",
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEventPage"
                }
              }
            },
            "description": "Audit events, newest first"
          },
          "403": {
            "description": "Missing audit:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List append-only cryptographic audit events, optionally for one record",
        "x-roles": [
          "admin",
          "analyst",
          "owner"
        ],
        "x-scopes": [
          "audit:read"
        ]
      }
    },
    "$BUSINESS_API/events/verify": {
      "get": {
        "description": "Walks the tenant's entire audit chain in sequence order, checking each event's link to the previous hash and recomputing its payload hash. Always answers 200: verified is true with the event count and last hash when the chain is intact, or false with tampered_event_id and failure_reason (broken prev_hash linkage or payload hash mismatch) at the first bad event. An empty chain verifies with zero events. Requires the audit:verify permission.",
        "operationId": "verifyAuditLedger",
        "responses": {
          "200": {
            "description": "Ledger verification result"
          },
          "403": {
            "description": "Missing audit:verify scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Verify audit log cryptographic hash-chain integrity",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "audit:verify"
        ]
      }
    },
    "$BUSINESS_API/evidence-photos": {
      "post": {
        "description": "Stores a photo taken with a reading or a field order and returns the reference to send as photo_evidence, evidence_photo or in evidence_ids. The content is verified by its bytes; the storage location is generated by the server. Retrying with the same client_key and the same photo returns the original record and stores nothing new. Requires the business:evidence-photos:create scope.",
        "operationId": "uploadEvidencePhoto",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "client_key": {
                    "description": "Identifier chosen by the client, stable across retries (letters, digits and the characters . _ : - up to 200).",
                    "maxLength": 200,
                    "type": "string"
                  },
                  "file": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "file",
                  "client_key"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "client_key": {
                      "type": "string"
                    },
                    "content_type": {
                      "enum": [
                        "image/jpeg",
                        "image/png"
                      ],
                      "type": "string"
                    },
                    "created_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "reference": {
                      "description": "Value to store on the reading or field order, of the form evidence://{id}.",
                      "type": "string"
                    },
                    "size_bytes": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "tenant_id": {
                      "type": "string"
                    },
                    "uploaded_by": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "The photo already stored under this client key"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "client_key": {
                      "type": "string"
                    },
                    "content_type": {
                      "enum": [
                        "image/jpeg",
                        "image/png"
                      ],
                      "type": "string"
                    },
                    "created_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "reference": {
                      "description": "Value to store on the reading or field order, of the form evidence://{id}.",
                      "type": "string"
                    },
                    "size_bytes": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "tenant_id": {
                      "type": "string"
                    },
                    "uploaded_by": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Stored photo"
          },
          "400": {
            "description": "Missing file or invalid client_key"
          },
          "401": {
            "description": "Not authenticated"
          },
          "403": {
            "description": "Missing business:evidence-photos:create scope"
          },
          "409": {
            "description": "The client_key was already used for a different photo"
          },
          "413": {
            "description": "The photo exceeds 8 MiB"
          },
          "415": {
            "description": "The content is not a JPEG or PNG image"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload an evidence photo (JPEG or PNG, up to 8 MiB)",
        "x-roles": [
          "admin",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:evidence-photos:create"
        ]
      }
    },
    "$BUSINESS_API/evidence-photos/{id}/file": {
      "get": {
        "description": "Returns the photo to staff of the owning tenant. Requires the business:evidence-photos:read scope. A photo owned by another tenant answers 404.",
        "operationId": "getEvidencePhotoFile",
        "parameters": [
          {
            "description": "Identifier from the photo's reference",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/jpeg": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "The photo bytes"
          },
          "401": {
            "description": "Not authenticated"
          },
          "403": {
            "description": "Missing business:evidence-photos:read scope"
          },
          "404": {
            "description": "Unknown photo or a photo owned by another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read an evidence photo",
        "x-roles": [
          "admin",
          "customer_service",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:evidence-photos:read"
        ]
      }
    },
    "$BUSINESS_API/executions": {
      "get": {
        "description": "Returns the tenant's report runs with their definition, status (pending, running, completed or failed), row count, timings, error message and, when completed, the CSV download path. Results are cursor-paginated (default 20, maximum 100); the handler also accepts definition_id and status filters. Requires the reports:read permission.",
        "operationId": "listBusinessReportExecutions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportExecutionPage"
                }
              }
            },
            "description": "Report executions"
          },
          "403": {
            "description": "Missing reports:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List durable report execution runs",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      },
      "post": {
        "description": "Requires reports:execute. Execution records are private to their utility tenant.",
        "operationId": "executeBusinessReport",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "definition_id": {
                    "type": "string"
                  },
                  "parameters": {
                    "additionalProperties": true,
                    "type": "object"
                  }
                },
                "required": [
                  "definition_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportExecution"
                }
              }
            },
            "description": "Report execution started"
          },
          "403": {
            "description": "Missing reports:execute scope"
          },
          "404": {
            "description": "Definition not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Trigger report execution",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:execute"
        ]
      }
    },
    "$BUSINESS_API/executions/{id}": {
      "get": {
        "description": "Returns one report run, which can be polled until its status is completed or failed. A completed run carries row_count and a download_url for the CSV export; the PDF rendering is available at /exports/{id}.pdf. Returns 404 when the run is not in the tenant. Requires the reports:read permission.",
        "operationId": "getBusinessReportExecution",
        "parameters": [
          {
            "description": "Identifier of the report execution within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReportExecution"
                }
              }
            },
            "description": "Report execution details"
          },
          "403": {
            "description": "Missing reports:read scope"
          },
          "404": {
            "description": "Execution not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get report execution details",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      }
    },
    "$BUSINESS_API/export/compliance": {
      "post": {
        "description": "Queues a ZIP package of all tenant data (tenant metadata, each dataset as CSV and JSON, the audit chain and its verification result, and a manifest with row counts) and returns the export record with status queued and 202. Only one export may be queued or running per tenant; another request returns 409. The request is recorded in the audit chain and remains allowed after the workspace is closed. Requires the compliance:export permission.",
        "operationId": "requestComplianceExport",
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComplianceExport"
                }
              }
            },
            "description": "Queue an asynchronous compliance export"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing compliance:export scope"
          },
          "409": {
            "description": "An export is already in progress"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue an asynchronous compliance export",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "compliance:export"
        ]
      }
    },
    "$BUSINESS_API/export/compliance/status": {
      "get": {
        "description": "Returns one compliance export, or the tenant's most recent one when no id is given, with status (queued, running, completed or failed), file name, size, SHA-256 digest, whether the audit chain verified and any error. download_url is set only once the export is completed. Returns 404 when no matching export exists; available after the workspace is closed. Requires the compliance:read permission.",
        "operationId": "getComplianceExportStatus",
        "parameters": [
          {
            "description": "Optional compliance export identifier; omit it to get the latest export of the tenant.",
            "in": "query",
            "name": "id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ComplianceExport"
                }
              }
            },
            "description": "Get an export status (latest, or by id)"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing compliance:read scope"
          },
          "404": {
            "description": "Export not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an export status (latest, or by id)",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "compliance:read"
        ]
      }
    },
    "$BUSINESS_API/export/compliance/{id}/download": {
      "get": {
        "description": "Streams the completed package as application/zip with an attachment file name, or answers 302 with a short-lived presigned link when the file store supports it. Exports that are not completed return 404. Each download is recorded in the audit chain, and the endpoint stays available after the workspace is closed. Requires the compliance:read permission.",
        "operationId": "downloadComplianceExport",
        "parameters": [
          {
            "description": "Identifier of a completed compliance export in the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Download a completed compliance package (ZIP)"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing compliance:read scope"
          },
          "404": {
            "description": "Export not found or not completed in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a completed compliance package (ZIP)",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "compliance:read"
        ]
      }
    },
    "$BUSINESS_API/exports/{id}.csv": {
      "get": {
        "description": "When the execution has a `locale`, the header row and known enum values (status, method, category, ageing band…) are labelled in that language; unknown values pass through. `raw=true` returns the stored file with snake_case column keys and raw values, for machine use.",
        "operationId": "downloadReportExport",
        "parameters": [
          {
            "description": "Execution id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "`true` returns column keys and raw values regardless of the execution's locale.",
            "in": "query",
            "name": "raw",
            "required": false,
            "schema": {
              "default": false,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "text/csv"
          },
          "403": {
            "description": "Caller lacks reports:read scope"
          },
          "404": {
            "description": "Unknown execution or other tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a completed report execution as CSV",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      }
    },
    "$BUSINESS_API/exports/{id}.pdf": {
      "get": {
        "description": "Renders the stored CSV of a completed report run as a PDF with the tenant's issuer details, the report definition's name and description, and column labels and values in the caller's language; it is served inline. Runs that are not completed, or whose export file is missing or empty, return 404. Requires the reports:read permission.",
        "operationId": "downloadReportExportPDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Execution id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a completed report execution as PDF",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      }
    },
    "$BUSINESS_API/field-visits": {
      "get": {
        "description": "Returns field visit records of the tenant with outcome, reader, location, evidence and revisit details. Filters combine, the handler also accepts route_id and cycle_id, and results are cursor-paginated (default 20, maximum 100). An unknown outcome value returns 400. Requires the business:field-visits:read permission.",
        "operationId": "listFieldVisits",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only visits to this meter.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only visits to meters of this service account.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only visits recorded by this staff member (the identity that submitted the visit).",
            "in": "query",
            "name": "reader_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only visits with this outcome: read, inaccessible, damaged or not_found; any other value returns 400.",
            "in": "query",
            "name": "outcome",
            "schema": {
              "enum": [
                "read",
                "inaccessible",
                "damaged",
                "not_found"
              ],
              "type": "string"
            }
          },
          {
            "description": "When true or 1, return only visits that need a revisit; any other value returns only visits that do not; omit to include both.",
            "in": "query",
            "name": "revisit_required",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldVisitPage"
                }
              }
            },
            "description": "Field visits list"
          },
          "403": {
            "description": "Missing business:field-visits:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List field visit records and inspection outcomes",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:field-visits:read"
        ]
      },
      "post": {
        "description": "Records a visit by the calling staff member to an active meter and returns it with 201; the account is taken from the meter. With assignment_id, the assignment must belong to the caller, be in progress, include the meter and sit in an in-progress reading round, and the visit then carries its route and cycle. visited_at defaults to now and must lie between the meter's installation and five minutes in the future, and revisit_scheduled_at may not be in the past (400). An inactive meter or a round that is not in progress returns 409; an unknown meter or assignment returns 404.",
        "operationId": "recordFieldVisit",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "assignment_id": {
                    "type": "string"
                  },
                  "evidence_ids": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "latitude": {
                    "type": "number"
                  },
                  "longitude": {
                    "type": "number"
                  },
                  "meter_id": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "outcome": {
                    "enum": [
                      "read",
                      "inaccessible",
                      "damaged",
                      "not_found"
                    ],
                    "type": "string"
                  },
                  "reading_id": {
                    "type": "string"
                  },
                  "revisit_reason": {
                    "type": "string"
                  },
                  "revisit_required": {
                    "type": "boolean"
                  },
                  "revisit_scheduled_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "visited_at": {
                    "format": "date-time",
                    "type": "string"
                  }
                },
                "required": [
                  "meter_id",
                  "outcome"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldVisit"
                }
              }
            },
            "description": "Field visit recorded"
          },
          "400": {
            "description": "Invalid visit outcome, timestamp or revisit schedule"
          },
          "403": {
            "description": "Missing business:field-visits:create scope"
          },
          "404": {
            "description": "Meter not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record field visit evidence, outcome, or revisit requirement",
        "x-roles": [
          "admin",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:field-visits:create"
        ]
      }
    },
    "$BUSINESS_API/field-visits/{id}": {
      "get": {
        "description": "Returns one field visit with its outcome, reader, linked reading, coordinates, evidence IDs, notes and revisit details. Returns 404 when the visit is not in the tenant. Requires the business:field-visits:read permission.",
        "operationId": "getFieldVisit",
        "parameters": [
          {
            "description": "Identifier of the field visit (an fvs_ prefixed ID) within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FieldVisit"
                }
              }
            },
            "description": "Field visit details"
          },
          "403": {
            "description": "Missing business:field-visits:read scope"
          },
          "404": {
            "description": "Field visit not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get details of a recorded field visit",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:field-visits:read"
        ]
      }
    },
    "$BUSINESS_API/first-run/abandon": {
      "post": {
        "description": "Records that the user explicitly exited or cancelled the journey at the given step. It is sent only after an explicit exit; closing a tab, losing the network or inactivity are never recorded. The body carries only the opaque run token and the stable step ID: no reason text or identity. Repeats are idempotent. Utility journeys require business:onboarding:write. Staff journeys require only a valid run token issued to the same principal for their role journey plus the entitlement of their own role action; this records the exit and grants no other onboarding access.",
        "operationId": "abandonBusinessFirstRun",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunAbandonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Exit recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid or expired run token, or unknown step"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the token was issued to someone else"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The step is already done"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an explicit exit from a first-use journey"
      }
    },
    "$BUSINESS_API/first-run/payment-check": {
      "post": {
        "description": "A payment connection check: asks the utility's payment connectors, through the payment service, which payment methods are operational right now, and succeeds when at least one connector method is. Nothing is charged. Success in the real account (not the test account) completes the utility_real connect_payments step. Codes: payments_inactive, no_payment_connector, connector_unavailable. Requires business:onboarding:write and a role that may read the utility's payment methods.",
        "operationId": "checkUtilityPaymentConnection",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "checked_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "code": {
                      "enum": [
                        "payments_inactive",
                        "no_payment_connector",
                        "connector_unavailable"
                      ],
                      "type": "string"
                    },
                    "connectors": {
                      "description": "Names of the connectors with an operational method",
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "outcome": {
                      "enum": [
                        "succeeded",
                        "failed"
                      ],
                      "type": "string"
                    },
                    "retryable": {
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "outcome",
                    "checked_at",
                    "retryable"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The check outcome"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or role"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check the utility's payment connection"
      }
    },
    "$BUSINESS_API/first-run/progress": {
      "get": {
        "description": "Returns the durable progress of the signed-in utility user and their tenant for one journey (utility_test, utility_real, staff_field_reader, staff_cashier, staff_finance): every step by stable ID in server order, its state (todo, done, skipped or blocked with a reason), whether and why it can be skipped, who changed it and when, and the qualifying action that completed it. A journey with no record returns its steps as todo. The response also carries an opaque run token the client sends back in the X-First-Run-Token header so funnel events join without storing who ran them. Requires business:onboarding:read for the utility journeys. A staff member reads only their own role journey with the entitlement of their own first-run action: business:reading-assignments:read for staff_field_reader, and business:onboarding:read or cashier:write (staff_cashier) or billing_runs:read (staff_finance); no subject or tenant selector is accepted. From a test (sandbox) account, utility_test is the owning real account's tour (the record the tour's actions credit, also for skips and resumes) and utility_real answers 404.",
        "operationId": "getBusinessFirstRunProgress",
        "parameters": [
          {
            "description": "Journey ID",
            "in": "query",
            "name": "journey",
            "required": true,
            "schema": {
              "enum": [
                "utility_test",
                "utility_real",
                "staff_field_reader",
                "staff_cashier",
                "staff_finance"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirstRunProgress"
                }
              }
            },
            "description": "Journey progress"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or entitlement"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Journey not available to this audience"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read first-use progress for one journey"
      }
    },
    "$BUSINESS_API/first-run/progress/{journey}/{step}": {
      "patch": {
        "description": "Records an explicit skip (state skipped with a reason_code from the step's allowed_skip_reasons) or resumes a skipped step (state todo). A client can never write done or blocked: domain actions complete steps and prerequisites block them. A done step cannot be reopened (409). Security, identity and legal steps and the moment-of-value steps have no skip reasons. Requires business:onboarding:write. Staff journeys are completed only by their actions and cannot be patched (403).",
        "operationId": "updateBusinessFirstRunStep",
        "parameters": [
          {
            "description": "Journey ID",
            "in": "path",
            "name": "journey",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Step ID",
            "in": "path",
            "name": "step",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunStepUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirstRunProgress"
                }
              }
            },
            "description": "Updated journey progress"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not skippable, unknown reason or a state the client cannot write"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unknown journey or step"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The step is done"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Skip or resume one first-use step"
      }
    },
    "$BUSINESS_API/inbox": {
      "get": {
        "description": "Results are scoped to both the active utility tenant and the authenticated identity.",
        "operationId": "listStaffNotificationInbox",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "When true, return only messages that have not been marked read; accepts Go boolean strings (true, false, 1, 0, t, f) and returns 400 for anything else.",
            "in": "query",
            "name": "unread_only",
            "schema": {
              "default": false,
              "type": "boolean"
            }
          },
          {
            "description": "When true, also return archived messages, which are hidden by default; accepts Go boolean strings and returns 400 for anything else.",
            "in": "query",
            "name": "include_archived",
            "schema": {
              "default": false,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/NotificationInboxItem"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data",
                    "has_more"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Utility-scoped staff inbox messages"
          },
          "403": {
            "description": "Missing business:notification-intents:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List notification messages addressed to the authenticated utility staff member",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:notification-intents:read"
        ]
      }
    },
    "$BUSINESS_API/inbox/{id}/archive": {
      "post": {
        "description": "Sets the archive time on a message in the caller's own staff inbox and returns the updated message; archived messages are hidden from the inbox list unless include_archived is set. Archiving does not mark the message read, and repeating the call keeps the original archive time. Returns 404 when the message does not belong to the caller in this tenant.",
        "operationId": "archiveStaffNotification",
        "parameters": [
          {
            "description": "Identifier of a message in the authenticated staff member's inbox.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationInboxItem"
                }
              }
            },
            "description": "Updated inbox item"
          },
          "403": {
            "description": "Missing business:notification-intents:read"
          },
          "404": {
            "description": "Inbox item is not visible to this identity in the active utility"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Archive a staff inbox message",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:notification-intents:read"
        ]
      }
    },
    "$BUSINESS_API/inbox/{id}/read": {
      "post": {
        "description": "Sets the read time on a message in the caller's own staff inbox and returns the updated message. The call is idempotent: a message already read keeps its original read time. Returns 404 when the message does not belong to the caller in this tenant.",
        "operationId": "markStaffNotificationRead",
        "parameters": [
          {
            "description": "Identifier of a message in the authenticated staff member's inbox.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationInboxItem"
                }
              }
            },
            "description": "Updated inbox item"
          },
          "403": {
            "description": "Missing business:notification-intents:read"
          },
          "404": {
            "description": "Inbox item is not visible to this identity in the active utility"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark a staff inbox message as read",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:notification-intents:read"
        ]
      }
    },
    "$BUSINESS_API/incidents": {
      "get": {
        "description": "Returns the tenant's network incidents (leaks, bursts, pressure drops, contamination, illegal connections) with severity, status, location and timestamps. Results are cursor-paginated (default 20, maximum 100); the handler also accepts incident_type, severity, status and service_area_id filters. Requires the operations:read permission.",
        "operationId": "listIncidents",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Incidents"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List water network incidents",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      },
      "post": {
        "description": "Records a new incident with status reported and a generated INC-<year>-<suffix> number, and returns it with 201. incident_type and description are required (400 otherwise); severity defaults to medium, and asset, service area and coordinates are optional. Requires the operations:write permission.",
        "operationId": "reportIncident",
        "responses": {
          "201": {
            "description": "Incident reported"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Report a water leak or incident",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/incidents/{id}": {
      "get": {
        "description": "Returns one incident with its number, type, severity, status, linked asset and service area, coordinates and reported and resolved times. Returns 404 when it is not in the tenant. Requires the operations:read permission.",
        "operationId": "getIncident",
        "parameters": [
          {
            "description": "Identifier of the incident (an inc_ prefixed ID) within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incident details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get incident details",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      }
    },
    "$BUSINESS_API/incidents/{id}/metadata": {
      "get": {
        "description": "Returns the custom key-value metadata attached to the incident, as an object of string values. The incident must exist in the tenant, otherwise 404. Requires the business:metadata:read permission.",
        "operationId": "getBusinessIncidentMetadata",
        "parameters": [
          {
            "description": "Identifier of the incident whose metadata is read, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a incident",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the given keys into the incident's metadata and returns the full resulting set: keys in the body are added or overwritten, an empty string value deletes that key, and keys not in the body are kept. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and the incident may carry at most 50 keys (400 otherwise). Requires the business:metadata:write permission; 404 when the incident does not exist.",
        "operationId": "putBusinessIncidentMetadata",
        "parameters": [
          {
            "description": "Identifier of the incident whose metadata is merged, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/incidents/{id}/resolve": {
      "post": {
        "description": "Sets the incident's status to resolved, stamps resolved_at with the current time and returns the updated incident. The status is not checked first, so resolving an already resolved incident moves resolved_at forward. Returns 404 for an unknown incident. Requires the operations:write permission.",
        "operationId": "resolveIncident",
        "parameters": [
          {
            "description": "Identifier of the incident to resolve within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Incident resolved"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark incident resolved",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/integrations": {
      "get": {
        "description": "Returns the integrations registered for the tenant, newest first, with category, provider key, secret configuration reference (never the secret itself), status and last reported health. Results are cursor-paginated (default 20, maximum 100) and the q parameter matches the name case-insensitively; a negative limit returns 400. Requires the business:integrations:read permission.",
        "operationId": "listUtilityIntegrations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "$ref": "#/components/parameters/IntegrationCategory"
          },
          {
            "$ref": "#/components/parameters/IntegrationStatus"
          },
          {
            "$ref": "#/components/parameters/IntegrationHealth"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IntegrationPage"
                }
              }
            },
            "description": "Tenant-scoped integration registrations"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List external integrations configured for this utility tenant",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:integrations:read"
        ]
      },
      "post": {
        "description": "Secret values are kept by the configured secret provider, not stored in this resource.",
        "operationId": "registerUtilityIntegration",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateIntegration"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Integration"
                }
              }
            },
            "description": "Integration registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register utility-scoped integration metadata and a config reference",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:integrations:create"
        ]
      }
    },
    "$BUSINESS_API/integrations/{id}": {
      "get": {
        "description": "Returns one integration registration with its category, provider key, secret configuration reference, status, health and last health check time. Returns 404 when it is not registered in the tenant. Requires the business:integrations:read permission.",
        "operationId": "getUtilityIntegration",
        "parameters": [
          {
            "description": "Identifier of the integration within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Integration"
                }
              }
            },
            "description": "Integration metadata without provider secrets"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get integration registration metadata",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:integrations:read"
        ]
      },
      "patch": {
        "description": "Sets the integration's status to active, suspended or disabled. Activating requires a configuration reference to be set, otherwise 400, and any other status value also returns 400; 404 for an unknown integration. The handler answers 204 with no body on success. Requires the business:integrations:manage permission.",
        "operationId": "updateUtilityIntegrationStatus",
        "parameters": [
          {
            "description": "Identifier of the integration whose status changes.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "suspended",
                      "disabled"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Integration status updated"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate, suspend, or disable a utility integration",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:integrations:manage"
        ]
      }
    },
    "$BUSINESS_API/integrations/{id}/configuration": {
      "put": {
        "description": "The secret value is never accepted or returned; only a reference to the configured secret provider is stored.",
        "operationId": "updateUtilityIntegrationConfiguration",
        "parameters": [
          {
            "description": "Identifier of the integration whose secret configuration reference is replaced; after the change it stays disabled until its status is set back to active.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "configuration_reference": {
                    "maxLength": 255,
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "configuration_reference"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Configuration updated; integration is disabled until explicitly enabled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace an integration's secret reference and disable it until re-enabled",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:integrations:manage"
        ]
      }
    },
    "$BUSINESS_API/interruptions": {
      "get": {
        "description": "Returns the tenant's planned and unplanned supply interruptions with type, status, service area, DMA, start and end times and estimated affected customers. Results are cursor-paginated (default 20, maximum 100); the handler also accepts service_area_id and status filters. Customers in an affected service area see open interruptions through the consumer API. Requires the interruptions:read permission.",
        "operationId": "listInterruptions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupplyInterruptionPage"
                }
              }
            },
            "description": "Supply interruptions"
          },
          "403": {
            "description": "Missing interruptions:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List water supply interruptions",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "interruptions:read"
        ]
      },
      "post": {
        "description": "Creates a supply interruption with status planned and returns it with 201. title and service_area_id are required (400 otherwise); interruption_type defaults to maintenance (other values: emergency, rationing), and DMA, description, start and end times and an affected-customer estimate are optional. Open interruptions in an area become visible to that area's customers. Requires the operations:write permission.",
        "operationId": "createInterruption",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInterruptionRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupplyInterruption"
                }
              }
            },
            "description": "Supply interruption scheduled"
          },
          "400": {
            "description": "Missing required title or service_area_id"
          },
          "403": {
            "description": "Missing operations:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule a supply interruption",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/interruptions/{id}": {
      "get": {
        "description": "Returns one supply interruption with its type, status, service area, DMA, schedule and estimated affected customers. Returns 404 when it is not in the tenant. Requires the interruptions:read permission.",
        "operationId": "getInterruption",
        "parameters": [
          {
            "description": "Identifier of the interruption (an out_ prefixed ID) within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupplyInterruption"
                }
              }
            },
            "description": "Interruption details"
          },
          "403": {
            "description": "Missing interruptions:read scope"
          },
          "404": {
            "description": "Interruption not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get supply interruption details",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "interruptions:read"
        ]
      }
    },
    "$BUSINESS_API/interruptions/{id}/complete": {
      "post": {
        "description": "Sets the interruption's status to completed and returns it, so it is no longer shown to customers as open. The current status is not checked, so a cancelled or already completed interruption is also set to completed. Returns 404 for an unknown interruption. Requires the operations:write permission.",
        "operationId": "completeInterruption",
        "parameters": [
          {
            "description": "Identifier of the interruption to complete within the current tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupplyInterruption"
                }
              }
            },
            "description": "Interruption completed"
          },
          "403": {
            "description": "Missing operations:write scope"
          },
          "404": {
            "description": "Interruption not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark supply restored",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/adjustments": {
      "post": {
        "description": "Corrects the on-hand stock at one active location: a positive line quantity records stock found, a negative one removes stock missing, and each line becomes an append-only adjustment movement. Needs the inventory:supervise scope and a reason. For serialised items, the serials you list are created in stock (found) or marked lost (missing). Meters found must come in through a receipt and return 409, as do removals that would take the location below its reserved stock (insufficient_stock) unless it allows negative stock. Movements that carry value raise an inventory.movement.recorded event for the ledger. Send an Idempotency-Key header to make retries safe: a replay returns the stored response with Idempotent-Replayed: true.",
        "operationId": "adjustInventoryStock",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryAdjustmentRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Adjustment recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Adjust stock found (positive) or missing (negative)",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/alerts": {
      "get": {
        "description": "Returns the open and resolved stock alerts for the tenant, newest work first, paged with limit (default 20, max 100) and the after cursor. An alert has kind negative_balance (raised when a movement takes a location that allows negative stock below zero), below_reorder (raised by the daily reorder scan) or short_for_planned (planned work orders need more than is available). Filter with kind and status (open or resolved). Needs the inventory:read scope.",
        "operationId": "listInventoryAlerts",
        "parameters": [
          {
            "description": "negative_balance, below_reorder or short_for_planned",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "enum": [
                "negative_balance",
                "below_reorder",
                "short_for_planned"
              ],
              "type": "string"
            }
          },
          {
            "description": "open or resolved",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "open",
                "resolved"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryAlertPage"
                }
              }
            },
            "description": "Alerts"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The stores work queue: negative balances and items below their reorder level",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/availability": {
      "get": {
        "description": "Adds up the balances of one item across locations and returns the totals together with the per-location balances. item_id is required (400 when missing, 404 when the item does not exist in this tenant). Pass location_id to limit the answer to one location; without it, only locations with a non-zero on-hand, reserved or in-transit quantity are listed. Needs the inventory:read scope.",
        "operationId": "getInventoryAvailability",
        "parameters": [
          {
            "description": "The item",
            "in": "query",
            "name": "item_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "One location; without it every location holding the item",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryAvailability"
                }
              }
            },
            "description": "Availability"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "On hand, reserved and available for one item, by location",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/balances": {
      "get": {
        "description": "Pages the stock balance rows (one per location and item), ordered by location then item, with limit (default 20, max 100) and the after cursor. Narrow with location_id and item_id. Set non_zero=true to skip empty rows, below_reorder=true for rows at or under the reorder level once holds and planned shortfalls are taken off, and short_for_planned=true for rows where planned work orders need more than is available. Needs the inventory:read scope.",
        "operationId": "listInventoryBalances",
        "parameters": [
          {
            "description": "One location",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "One item",
            "in": "query",
            "name": "item_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only balances at or under their reorder level",
            "in": "query",
            "name": "below_reorder",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Leave out empty balances",
            "in": "query",
            "name": "non_zero",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Only balances whose available stock does not cover the unreserved need of planned work orders",
            "in": "query",
            "name": "short_for_planned",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryBalancePage"
                }
              }
            },
            "description": "Balances ordered by location and item"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "What is where: on hand, reserved, available and in transit",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/issues": {
      "post": {
        "description": "Refused with insufficient_stock when available stock would go below zero, unless the location allows negative stock; a negative balance then raises an alert. Meter serials are issued by installing the meter.",
        "operationId": "issueInventoryStock",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryIssueRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Issue recorded at the average cost"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue stock to a work order or connection",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/items": {
      "get": {
        "description": "Pages the tenant's catalogue with limit (default 20, max 100) and the after cursor. Filter by kind (bulk or serialised), is_meter and active (true or 1 for true, any other value for false), and search with q. Needs the inventory:read scope.",
        "operationId": "listInventoryItems",
        "parameters": [
          {
            "description": "bulk or serialised",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "enum": [
                "bulk",
                "serialised"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only meter items",
            "in": "query",
            "name": "is_meter",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Only active or inactive items",
            "in": "query",
            "name": "active",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryItemPage"
                }
              }
            },
            "description": "Catalogue items"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List catalogue items",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "post": {
        "description": "Adds a stock item to the catalogue and returns it with status 201. code (stored upper case, unique per tenant) and name are required; unit defaults to un and must be one of un, m, kg, l, cx or rolo, and kind defaults to bulk. Serialised items, including every item with is_meter set, are counted in un. Reorder levels need distinct, existing locations and values of zero or more. Needs the inventory:supervise scope; a duplicate code returns 409. Send an Idempotency-Key header to make retries safe.",
        "operationId": "createInventoryItem",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInventoryItemRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryItem"
                }
              }
            },
            "description": "Item created"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a catalogue item",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/items/export": {
      "get": {
        "description": "Downloads the whole catalogue as a text/csv attachment, built in full before it is sent so a failure comes back as a problem response instead of a cut-off file. The columns are code, name, unit, kind, description, reorder_level, standard_cost_minor, average_cost_minor, is_meter, meter_manufacturer, meter_model, meter_diameter_mm and active, the same header the item import reads. Needs the inventory:read scope.",
        "operationId": "exportInventoryItems",
        "responses": {
          "200": {
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "text/csv with the catalogue import's columns and average_cost_minor"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The catalogue as plain CSV, for an ERP",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/items/import": {
      "post": {
        "description": "Columns code, name, unit, kind, description, reorder_level, standard_cost_minor, is_meter, meter_manufacturer, meter_model, meter_diameter_mm and active, as the catalogue export writes them. A unit or kind never changes on an existing item.",
        "operationId": "importInventoryItems",
        "parameters": [
          {
            "description": "Check every row and report errors without writing anything",
            "in": "query",
            "name": "dry_run",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryCsvImportRequest"
              }
            },
            "text/csv": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryImportReport"
                }
              }
            },
            "description": "Dry run report"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryImportReport"
                }
              }
            },
            "description": "Imported"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "A CSV import is limited to 5 MB"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryImportReport"
                }
              }
            },
            "description": "Rows in error; nothing was written"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create and update catalogue items from CSV, matched by code, with a dry run",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/items/{id}": {
      "get": {
        "description": "Returns one catalogue item of the caller's tenant, including its per-location reorder levels, standard and average cost, and meter details. Returns 404 when the item does not exist in this tenant. Needs the inventory:read scope.",
        "operationId": "getInventoryItem",
        "parameters": [
          {
            "description": "Item ID (itm_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryItem"
                }
              }
            },
            "description": "Item"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a catalogue item with its reorder levels",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "patch": {
        "description": "Changes only the fields you send: name, description, reorder_level, reorder_levels (replaces the whole list), standard_cost_minor, the meter manufacturer, model and diameter, and active. Code, unit and kind cannot be changed. Negative levels or costs and a blank name return 400, and an unknown item returns 404. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.",
        "operationId": "updateInventoryItem",
        "parameters": [
          {
            "description": "Item ID (itm_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateInventoryItemRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryItem"
                }
              }
            },
            "description": "Item updated"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change an item, its standard cost and reorder levels",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/kits": {
      "get": {
        "description": "Pages the tenant's kits with limit (default 20, max 100) and the after cursor. Filter by work_order_type to find the default kit for a type of work order, and by active. Needs the inventory:read scope.",
        "operationId": "listInventoryKits",
        "parameters": [
          {
            "description": "Kits proposed for one work-order type",
            "in": "query",
            "name": "work_order_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only active or inactive kits",
            "in": "query",
            "name": "active",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryKitPage"
                }
              }
            },
            "description": "Kits"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List kits and default kits per work-order type",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "post": {
        "description": "Creates a named list of items and quantities that work orders draw on, returned with status 201. code (stored upper case, unique per tenant) and name are required, and lines must hold 1 to 100 distinct existing items with positive quantities, in whole units for serialised items. Setting work_order_type makes the kit the default for that type; 409 when another active kit already holds that type or the code exists. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.",
        "operationId": "createInventoryKit",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInventoryKitRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryKit"
                }
              }
            },
            "description": "Kit created"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a kit",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/kits/{id}": {
      "get": {
        "description": "Returns one kit of the caller's tenant with its lines and the work-order type it is the default for. Returns 404 when the kit does not exist in this tenant. Needs the inventory:read scope.",
        "operationId": "getInventoryKit",
        "parameters": [
          {
            "description": "Kit ID (kit_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryKit"
                }
              }
            },
            "description": "Kit"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a kit",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "patch": {
        "description": "Changes only the fields you send: name, description, work_order_type, active, and lines (replaces all lines, with the same rules as on create). An active kit keeps the one-default-per-type rule, so naming a work-order type that another active kit already holds returns 409. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.",
        "operationId": "updateInventoryKit",
        "parameters": [
          {
            "description": "Kit ID (kit_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateInventoryKitRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryKit"
                }
              }
            },
            "description": "Kit updated"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a kit or its lines",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/locations": {
      "get": {
        "description": "Pages the tenant's stock locations with limit (default 20, max 100) and the after cursor. Filter by kind (warehouse, area or van), crew_id and active, and search with q. Needs the inventory:read scope.",
        "operationId": "listInventoryLocations",
        "parameters": [
          {
            "description": "warehouse, area or van",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "enum": [
                "warehouse",
                "area",
                "van"
              ],
              "type": "string"
            }
          },
          {
            "description": "Vans of one crew",
            "in": "query",
            "name": "crew_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only active or inactive locations",
            "in": "query",
            "name": "active",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryLocationPage"
                }
              }
            },
            "description": "Locations"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List warehouses, shelf areas and vans",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "post": {
        "description": "Creates a stock location, returned with status 201. code (stored upper case, unique per tenant) and name are required; kind defaults to warehouse, and an area needs parent_id naming a warehouse. A crew_id must name an existing crew. member_user_ids list the users who may move stock in a van with only the inventory:van:write scope, and allow_negative lets the balance go below zero (raising an alert) instead of refusing the movement. Needs the inventory:supervise scope; a duplicate code returns 409. Send an Idempotency-Key header to make retries safe.",
        "operationId": "createInventoryLocation",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInventoryLocationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryLocation"
                }
              }
            },
            "description": "Location created"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a warehouse, shelf area or van",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/locations/{id}": {
      "get": {
        "description": "Returns one location of the caller's tenant: its kind, parent warehouse, crew, service area, van members and whether it allows negative stock. Returns 404 when the location does not exist in this tenant. Needs the inventory:read scope.",
        "operationId": "getInventoryLocation",
        "parameters": [
          {
            "description": "Location ID (loc_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryLocation"
                }
              }
            },
            "description": "Location"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a location",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "patch": {
        "description": "Changes only the fields you send: name, crew_id (must name an existing crew), service_area_id, member_user_ids (replaces the list), allow_negative and active. The default warehouse cannot be deactivated (409). Code, kind and parent cannot be changed. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.",
        "operationId": "updateInventoryLocation",
        "parameters": [
          {
            "description": "Location ID (loc_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateInventoryLocationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryLocation"
                }
              }
            },
            "description": "Location updated"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a location, its crew and van members",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/movements": {
      "get": {
        "description": "Pages the movements, each one a positive quantity moving into or out of a location (receipt, issue, return, transfer_out, transfer_in, adjustment or scrap). Use limit (default 20, max 100) and the after cursor. Filter by item_id, location_id (matches either side), kind, source_type, source_id, work_order_id, actor_id, and from/to (RFC 3339 or YYYY-MM-DD; from is inclusive, to is exclusive). Needs the inventory:read scope.",
        "operationId": "listInventoryMovements",
        "parameters": [
          {
            "description": "One item",
            "in": "query",
            "name": "item_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Movements from or to one location",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Movement kind",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "enum": [
                "receipt",
                "issue",
                "return",
                "transfer_out",
                "transfer_in",
                "adjustment",
                "scrap"
              ],
              "type": "string"
            }
          },
          {
            "description": "work_order, connection, meter, stocktake, transfer, receipt or other",
            "in": "query",
            "name": "source_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "The source record",
            "in": "query",
            "name": "source_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Movements serving a work order's material lines",
            "in": "query",
            "name": "work_order_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Who recorded it",
            "in": "query",
            "name": "actor_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Occurred at or after (RFC 3339 or YYYY-MM-DD)",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Occurred before (RFC 3339 or YYYY-MM-DD)",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementPage"
                }
              }
            },
            "description": "Movements, newest first"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The append-only movement ledger",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/movements/export": {
      "get": {
        "description": "Oldest first within the filters; at most 100000 movements per export, so narrow the dates for more. The last two columns tie each row to the ledger: stock_value_change_minor is what the movement posted to the stock on hand account, and ledger_source_reference is the source reference of its journal entry (empty for a transfer, which posts nothing).",
        "operationId": "exportInventoryMovements",
        "parameters": [
          {
            "description": "Only movements of this catalogue item ID.",
            "in": "query",
            "name": "item_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only movements into or out of this location ID; it matches either the source or the destination location.",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only movements of this kind: receipt, issue, return, transfer_out, transfer_in, adjustment or scrap.",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only movements pointing at this kind of source, such as work_order, connection, meter, stocktake, transfer, receipt or other.",
            "in": "query",
            "name": "source_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only movements pointing at this source record ID, usually combined with source_type.",
            "in": "query",
            "name": "source_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only movements tied to this work order ID.",
            "in": "query",
            "name": "work_order_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only movements recorded by this user ID.",
            "in": "query",
            "name": "actor_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Inclusive lower bound on the time the movement occurred, as an RFC 3339 timestamp or a YYYY-MM-DD date (midnight UTC); any other format returns 400.",
            "in": "query",
            "name": "from",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Exclusive upper bound on the time the movement occurred, as an RFC 3339 timestamp or a YYYY-MM-DD date (midnight UTC, so that day is left out); any other format returns 400.",
            "in": "query",
            "name": "to",
            "required": false,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "text/csv: occurred_at, movement_id, kind, item_code, item_name, unit, quantity, from_location_code, to_location_code, serial_number, unit_cost_minor, total_cost_minor, reason, source_type, source_id, work_order_id, material_line_id, reference, actor_id"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The movement ledger as plain CSV, for an ERP",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/receipts": {
      "post": {
        "description": "Receiving units of a meter item registers each meter in the meter module (device status in_warehouse) and its serial at the location in one action. Each unit cost feeds the moving weighted average cost.",
        "operationId": "receiveInventoryStock",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryReceiptRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Receipt recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (meter lines also need business:meters:create)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Receive stock, with serials for serialised items",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/receipts/import": {
      "post": {
        "description": "Columns item_code (or item_id), quantity, unit_cost_minor, serials (serialised items, separated by | or spaces), location_code (or the location_id parameter) and reference; commas or semicolons, with a header row. Every row is checked first: a dry run, or a file with any row in error, writes nothing and answers with each row's errors. A commit receives one receipt per location; the same file imported again records once (the key is the Idempotency-Key, or the file's digest). Meter rows also register each meter.",
        "operationId": "importInventoryReceipts",
        "parameters": [
          {
            "description": "Check every row and report errors without writing anything",
            "in": "query",
            "name": "dry_run",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Receiving location for rows that name none",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Delivery note reference for rows that name none",
            "in": "query",
            "name": "reference",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryCsvImportRequest"
              }
            },
            "text/csv": {
              "schema": {
                "type": "string"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryImportReport"
                }
              }
            },
            "description": "Dry run report"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryImportReport"
                }
              }
            },
            "description": "Imported"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (meter rows also need business:meters:create)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          },
          "413": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "A CSV import is limited to 5 MB"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryImportReport"
                }
              }
            },
            "description": "Rows in error; nothing was written"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Import an opening stock or a delivery note from CSV, with a dry run",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/reservations": {
      "get": {
        "description": "Pages the stock reservations, mostly ones work orders hold for their materials, with limit (default 20, max 100) and the after cursor. Filter by status (held, issued or released), location_id, item_id and work_order_id. Needs the inventory:read scope.",
        "operationId": "listInventoryReservations",
        "parameters": [
          {
            "description": "held, issued or released",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "held",
                "issued",
                "released"
              ],
              "type": "string"
            }
          },
          {
            "description": "One location",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "One item",
            "in": "query",
            "name": "item_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "One work order",
            "in": "query",
            "name": "work_order_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryReservationPage"
                }
              }
            },
            "description": "Reservations"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open holds and their ageing",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/reservations/{id}/release": {
      "post": {
        "description": "Frees a held reservation so its quantity counts as available again, and records the reason (required) and the release time. Only a reservation in status held can be released: an issued or already released one returns 409. Callers with only the inventory:van:write scope can release holds only in a van whose members include them. Send an Idempotency-Key header to make retries safe.",
        "operationId": "releaseInventoryReservation",
        "parameters": [
          {
            "description": "Reservation ID (rsv_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReleaseInventoryReservationRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryReservation"
                }
              }
            },
            "description": "Reservation released"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Release a stale hold",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/returns": {
      "post": {
        "description": "Puts issued stock back into an active location as return movements and responds with status 201. A reason is required; source_type and source_id can point at the work order or record the stock came back from, and occurred_at can backdate the movement. Serialised lines must list serials that are currently issued (409 serial_mismatch otherwise), and they move back in stock at the location. Callers with only the inventory:van:write scope can return only into a van whose members include them. Send an Idempotency-Key header to make retries safe.",
        "operationId": "returnInventoryStock",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryReturnRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Return recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Return issued stock to a location",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/scraps": {
      "post": {
        "description": "Meter serials are scrapped through POST $BUSINESS_API/meters/{id}/device-status.",
        "operationId": "scrapInventoryStock",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryScrapRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Scrap recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Write off damaged stock",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/serials/{serial}": {
      "get": {
        "description": "Looks up a serial number (trimmed and matched in upper case) and returns its current status and location, its catalogue item, and every movement it took part in. Status is one of in_stock, in_transit, issued, installed, in_testing, scrapped or lost. Returns 404 when the serial is not registered in this tenant. Needs the inventory:read scope.",
        "operationId": "getInventorySerial",
        "parameters": [
          {
            "description": "Serial number",
            "in": "path",
            "name": "serial",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventorySerialHistory"
                }
              }
            },
            "description": "Serial and its movements"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Where a meter or device is, and its history",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/settings": {
      "get": {
        "description": "Returns the tenant's inventory settings, currently redispatch_hold_days: how long reservations stay held after a work order fails because access was denied, waiting for it to be dispatched again. It also shows who last changed the settings and when. Needs the inventory:read scope.",
        "operationId": "getInventorySettings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventorySettings"
                }
              }
            },
            "description": "Settings"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The utility's inventory settings, such as the re-dispatch hold period",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "patch": {
        "description": "Sets redispatch_hold_days, which must be between 1 and 365 (400 otherwise), and records the caller as the last editor. Leaving the field out keeps the current value. Needs the inventory:supervise scope; send an Idempotency-Key header to make retries safe.",
        "operationId": "updateInventorySettings",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "redispatch_hold_days": {
                    "maximum": 365,
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventorySettings"
                }
              }
            },
            "description": "Settings"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change how long a failed visit keeps its reservations (14 days by default)",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/stocktakes": {
      "get": {
        "description": "Pages the stocktakes with limit (default 20, max 100) and the after cursor. Filter by location_id and by status (counting or approved). Needs the inventory:read scope.",
        "operationId": "listInventoryStocktakes",
        "parameters": [
          {
            "description": "One location",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "counting or approved",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "counting",
                "approved"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryStocktakePage"
                }
              }
            },
            "description": "Stocktakes"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List stocktakes",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "post": {
        "description": "Opens a stocktake in status counting at an active location, returned with status 201. It records a line for every item with a non-zero balance there, holding the expected quantity, the expected serials for serialised items, and the item's average cost. A reason is optional. Callers with only the inventory:van:write scope can open one only in a van whose members include them. Send an Idempotency-Key header to make retries safe.",
        "operationId": "createInventoryStocktake",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateInventoryStocktakeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryStocktake"
                }
              }
            },
            "description": "Stocktake opened"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a count, freezing the expected quantities of a location",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/stocktakes/{id}": {
      "get": {
        "description": "Returns one stocktake with its status, its lines with the expected and counted quantities and serials, who counted each line, and the approval details once approved. Returns 404 when the stocktake does not exist in this tenant. Needs the inventory:read scope.",
        "operationId": "getInventoryStocktake",
        "parameters": [
          {
            "description": "Stocktake ID (stk_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryStocktake"
                }
              }
            },
            "description": "Stocktake"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a stocktake with expected, counted and differences",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/stocktakes/{id}/approve": {
      "post": {
        "description": "Turns each counted line's difference from the expected quantity into adjustment movements and marks the stocktake approved. Needs the inventory:supervise scope and a reason. The approver must be someone other than whoever opened the stocktake or counted any line (403). Returns 409 when the stocktake is already approved, when nothing was counted, when expected meters are missing (scrap or locate them first), or when a found serial is registered elsewhere. Send an Idempotency-Key header to make retries safe.",
        "operationId": "approveInventoryStocktake",
        "parameters": [
          {
            "description": "Stocktake ID (stk_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ApproveInventoryStocktakeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Stocktake approved"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:supervise scope; the approver must not have opened or counted the stocktake"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve the differences as adjustment movements",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "inventory:supervise"
        ]
      }
    },
    "$BUSINESS_API/inventory/stocktakes/{id}/lines": {
      "post": {
        "description": "Records 1 to 500 counted lines on a stocktake still in status counting (409 once approved) and returns the updated stocktake. Count bulk items with a quantity of zero or more. Count serialised items by scanning their serials, where the quantity is the number of distinct serials. An item may appear only once per request, and counting it again later replaces the earlier count. The caller is recorded as the counter of each line. Send an Idempotency-Key header to make retries safe.",
        "operationId": "recordInventoryStocktakeCounts",
        "parameters": [
          {
            "description": "Stocktake ID (stk_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryCountRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryStocktake"
                }
              }
            },
            "description": "Stocktake with the counts"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record counted lines",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/transfers": {
      "get": {
        "description": "Pages the transfers with limit (default 20, max 100) and the after cursor. Filter by status (in_transit or received) and location_id. Needs the inventory:read scope.",
        "operationId": "listInventoryTransfers",
        "parameters": [
          {
            "description": "in_transit or received",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "in_transit",
                "received"
              ],
              "type": "string"
            }
          },
          {
            "description": "Transfers from or to one location",
            "in": "query",
            "name": "location_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryTransferPage"
                }
              }
            },
            "description": "Transfers"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List transfers",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      },
      "post": {
        "description": "Takes stock out of one active location with transfer_out movements and creates a transfer in status in_transit to another location, responding with status 201. The two locations must differ, and serialised lines must list serials in stock at the source. The reason defaults to a standard stock-transfer text. Returns 409 when the source lacks available stock. Callers with only the inventory:van:write scope can send only from a van whose members include them. Send an Idempotency-Key header to make retries safe.",
        "operationId": "createInventoryTransfer",
        "parameters": [
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InventoryTransferRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Transfer in transit"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send stock to another location; it stays in transit until received",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/inventory/transfers/{id}": {
      "get": {
        "description": "Returns one transfer with its source and destination, its lines and serials, its status, and who created and received it. Returns 404 when the transfer does not exist in this tenant. Needs the inventory:read scope.",
        "operationId": "getInventoryTransfer",
        "parameters": [
          {
            "description": "Transfer ID (xfr_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryTransfer"
                }
              }
            },
            "description": "Transfer"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a transfer",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "inventory:read"
        ]
      }
    },
    "$BUSINESS_API/inventory/transfers/{id}/receive": {
      "post": {
        "description": "Books the transfer's lines into the destination location as transfer_in movements, puts its serials back in stock there, and marks the transfer received by the caller. The request takes no body. A transfer that was already received returns 409. Callers with only the inventory:van:write scope can receive only into a van whose members include them. Send an Idempotency-Key header to make retries safe.",
        "operationId": "receiveInventoryTransfer",
        "parameters": [
          {
            "description": "Transfer ID (xfr_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/InventoryMovementResult"
                }
              }
            },
            "description": "Transfer received"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing inventory:write scope (or inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm a transfer at the receiving location",
        "x-roles": [
          "admin",
          "field_reader",
          "owner"
        ],
        "x-scopes": [
          "inventory:van:write"
        ]
      }
    },
    "$BUSINESS_API/invoices": {
      "get": {
        "description": "Pages the invoices of the caller's tenant with limit (default 20, max 100) and the after cursor. Filter by customer_id, account_id, meter_id, reading_id, billing_run_id and status. q searches the invoice number and the accounts whose holder matches the text. Needs the invoices:read permission.",
        "operationId": "listInvoices",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "description": "Only invoices that opened or closed on this reading",
            "in": "query",
            "name": "reading_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices in the authenticated utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility invoices",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      },
      "post": {
        "description": "Issues one invoice for an account outside a billing run by pricing consumption_m3 for the period against a tariff version: tariff_version_id when given, otherwise the residential tariff active at period_end. Fixed charges, tiers, sanitation, extra charge components and tax are computed by the server, the invoice is numbered in the tenant's invoice series and opened with the tariff's currency, and the tenant's enabled payment instructions are copied onto it. Without due_date the invoice is due after the billing policy's default due days (30 when unset). Any account credit available is applied straight away, so the returned balance can be lower than the total. For an invoice made of free-text lines use POST $BUSINESS_API/invoices/manual instead. Requires invoices:write and the billing capability. customer_id and account_id are required and period_end must not be before period_start (400); unknown fields are rejected (400); no matching tariff returns 404.",
        "operationId": "createInvoice",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateBusinessInvoiceRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "The issued invoice"
          },
          "400": {
            "description": "Invalid input, unknown field, or period_end before period_start (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing invoices:write scope, or the billing capability is inactive"
          },
          "404": {
            "description": "Tariff version not found, or no tariff active at period_end"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Price consumption against a tariff and issue an invoice",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/manual": {
      "post": {
        "description": "Issues one invoice outside a billing run, numbered in the same gap-free\ninvoice series and posted to the ledger like any other. Prices are in the\ncurrency of the account's active tariff; taxable lines carry VAT at that\ntariff's rate. Needs the invoices:write scope and the billing capability.\n",
        "operationId": "issueManualInvoice",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "account_id": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "customer_id": {
                    "description": "When given",
                    "must own the account": null,
                    "type": "string"
                  },
                  "due_date": {
                    "description": "Defaults to the billing policy's payment terms",
                    "format": "date-time",
                    "type": "string"
                  },
                  "lines": {
                    "items": {
                      "additionalProperties": false,
                      "properties": {
                        "description": {
                          "minLength": 1,
                          "type": "string"
                        },
                        "quantity": {
                          "exclusiveMinimum": 0,
                          "type": "number"
                        },
                        "taxable": {
                          "default": false,
                          "type": "boolean"
                        },
                        "unit_price_cents": {
                          "format": "int64",
                          "minimum": 1,
                          "type": "integer"
                        }
                      },
                      "required": [
                        "description",
                        "quantity",
                        "unit_price_cents"
                      ],
                      "type": "object"
                    },
                    "minItems": 1,
                    "type": "array"
                  }
                },
                "required": [
                  "account_id",
                  "lines"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "The issued invoice"
          },
          "400": {
            "a line without a description": null,
            "description": "Missing account or lines",
            "or a quantity or price not above zero": null
          },
          "403": {
            "description": "Missing invoices:write scope",
            "or the billing capability is inactive": null
          },
          "404": {
            "description": "Account or active tariff not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a manual invoice with free lines for one account",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}": {
      "get": {
        "description": "Returns one invoice of the caller's tenant with its amounts in minor units (subtotal, sanitation, tax, total, balance and amount due), status, period, due date, the payment instructions captured when it was issued, any void, dispute or write-off details, and its line items. Account, customer and meter references carry the holder's display name. Requires invoices:read; an id that does not exist in the caller's tenant returns 404.",
        "operationId": "getInvoice",
        "parameters": [
          {
            "description": "Identifier of the invoice (inv_...), matched within the caller's tenant only.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "Invoice"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing invoices:read scope"
          },
          "404": {
            "description": "Invoice not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one invoice with its lines",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/adjust": {
      "post": {
        "description": "Issues a credit_note or debit_note for a positive amount_cents with a required reason, and returns the updated invoice. A credit lowers the balance (any amount beyond it is kept as credit excess) and marks the invoice paid when the balance reaches zero. A debit raises both the balance and the total and may carry the category late_fee or interest (default general). Void and written-off invoices refuse notes, and paid invoices accept only credits; these state errors return 400. A note that moves money raises an invoice.adjusted event.",
        "operationId": "createAdjustment",
        "parameters": [
          {
            "description": "ID of the invoice the credit or debit note applies to; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount_cents": {
                    "format": "int64",
                    "minimum": 1,
                    "type": "integer"
                  },
                  "category": {
                    "enum": [
                      "general",
                      "late_fee",
                      "interest"
                    ],
                    "type": "string"
                  },
                  "reason": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "type": {
                    "enum": [
                      "credit_note",
                      "debit_note"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "type",
                  "amount_cents",
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "Invoice with the applied adjustment"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Post a credit or debit adjustment to an invoice",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/dispute": {
      "post": {
        "description": "Records a required reason, and optionally the line item or charge code being contested, and returns the invoice with its dispute details. While the dispute is open, the account is left out of cutoff and late-penalty runs. Disputing again replaces the earlier dispute details. A void invoice cannot be disputed (400), and a line_item_id that is not on the invoice returns 400.",
        "operationId": "disputeInvoice",
        "parameters": [
          {
            "description": "ID of the invoice to mark as disputed; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "charge_code": {
                    "type": "string"
                  },
                  "line_item_id": {
                    "type": "string"
                  },
                  "reason": {
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "Invoice marked as disputed"
          },
          "400": {
            "description": "Dispute reason is required or invoice cannot be disputed in its current state"
          },
          "403": {
            "description": "Missing invoices:write scope"
          },
          "404": {
            "description": "Invoice not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark an invoice as disputed, excluding the account from cutoff",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/dispute/resolve": {
      "post": {
        "description": "Clears the open dispute on an invoice, stores the optional resolution text with the resolution time, and returns the invoice. The account becomes eligible for cutoff and late penalties again. The body may be empty. An invoice that is not under dispute returns 400. Needs the invoices:write permission.",
        "operationId": "resolveInvoiceDispute",
        "parameters": [
          {
            "description": "ID of the disputed invoice; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "Invoice dispute resolved"
          },
          "400": {
            "description": "Invoice is not currently disputed"
          },
          "403": {
            "description": "Missing invoices:write scope"
          },
          "404": {
            "description": "Invoice not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Lift a dispute",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata stored on an invoice of the caller's tenant, as a map of string keys to string values. Needs the business:metadata:read scope. Returns 404 when the invoice does not exist in this tenant.",
        "operationId": "getBusinessInvoiceMetadata",
        "parameters": [
          {
            "description": "ID of the invoice whose metadata is read, up to 120 characters; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a invoice",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the keys in the metadata object into what the invoice already carries, leaving other keys untouched, and returns the full resulting map. Keys are up to 40 characters with no square brackets or control characters, and values are up to 500 characters. A request may set at most 50 keys, and a merge that would leave more than 50 keys on the invoice is refused. Needs the business:metadata:write scope; 404 when the invoice is not in this tenant.",
        "operationId": "putBusinessInvoiceMetadata",
        "parameters": [
          {
            "description": "ID of the invoice whose metadata is merged, up to 120 characters; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/pdf": {
      "get": {
        "description": "Renders the invoice as an inline application/pdf document. It includes the issuer, the customer, the period, consumption, totals, previous balance, amount due and the payment instructions captured when the invoice was issued (or the tenant's current payment channels when none were captured). The query parameter locale (pt-MZ or en-US) picks the language, falling back to the caller's own locale and then pt-MZ. layout=mobile renders a phone-sized page instead of A4. Returns 404 when the invoice is not in the caller's tenant.",
        "operationId": "getInvoicePDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Invoice id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download an invoice as a Portuguese PDF factura",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/reconcile-consumption": {
      "post": {
        "description": "Re-prices an invoice with the consumption that replaced a superseded reading, using the invoice's own tariff version and period. It stores the new consumption ID, the volume and, when given, the readings. Any difference from the old total is posted as a debit note (higher) or a credit note (lower), and the response reports delta_cents with the updated invoice. new_consumption_id and reason are required and new_consumption_m3 must not be negative; a void invoice returns 400. Needs the invoices:write permission.",
        "operationId": "reconcileInvoiceConsumption",
        "parameters": [
          {
            "description": "ID of the finalized invoice to reconcile; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "from_reading_id": {
                    "type": "string"
                  },
                  "new_consumption_id": {
                    "type": "string"
                  },
                  "new_consumption_m3": {
                    "minimum": 0,
                    "type": "number"
                  },
                  "reason": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "to_reading_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "new_consumption_id",
                  "new_consumption_m3",
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReconcileConsumptionResult"
                }
              }
            },
            "description": "Invoice reconciled with credit or debit adjustment"
          },
          "400": {
            "description": "Invalid consumption or void invoice"
          },
          "403": {
            "description": "Missing invoices:write scope"
          },
          "404": {
            "description": "Invoice or tariff not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reconcile finalized invoice when a reading was superseded",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/void": {
      "post": {
        "description": "Cancels an invoice that has no payments applied. The invoice keeps its number, so the series stays without gaps; its status becomes void, its balance drops to zero, voided_at and void_reason are set, an invoice.voided event and a status transition are recorded, and any account credit that had been applied to it is released back to the account. A non-empty reason is required. An invoice that is already void, or that is paid or partially paid, is refused with 400: correct those with a credit note or a payment reversal instead. Requires invoices:write; an unknown invoice returns 404.",
        "operationId": "voidInvoice",
        "parameters": [
          {
            "description": "Identifier of the invoice to void, matched within the caller's tenant only.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "description": "Why the invoice is voided; stored on the invoice and in its history.",
                    "example": "Issued to the wrong account",
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "The voided invoice"
          },
          "400": {
            "description": "Missing reason, invoice already void, or invoice has payments (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing invoices:write scope"
          },
          "404": {
            "description": "Invoice not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Void an unpaid invoice",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/invoices/{id}/write-off": {
      "post": {
        "description": "Moves the whole outstanding balance into written_off_cents, sets the balance to zero, marks the invoice uncollectible and stores the required reason. An invoice.written_off event posts the amount to bad debt expense in the ledger. An invoice with no balance left returns 400. Once written off, the invoice accepts no further credit or debit notes. Needs the invoices:write permission.",
        "operationId": "writeOffInvoice",
        "parameters": [
          {
            "description": "ID of the invoice whose unpaid balance is written off; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Write off an unpaid balance as bad debt",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "invoices:write"
        ]
      }
    },
    "$BUSINESS_API/jobs": {
      "get": {
        "description": "Pages the background jobs that belong to the caller's tenant, with limit (default 20, max 100) and the after cursor. Each job shows its kind, status, attempts, last error and timestamps; payloads are never returned. When background jobs are not enabled on the installation, the list is empty. Needs the business:jobs:read scope.",
        "operationId": "listBusinessJobs",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only jobs in this status: queued, running or succeeded (jobs that ran out of attempts are listed under the dead-letters endpoint instead).",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "queued",
                "running",
                "succeeded"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only jobs of this job kind, matched exactly.",
            "in": "query",
            "name": "kind",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobPage"
                }
              }
            },
            "description": "Jobs"
          },
          "403": {
            "description": "Missing business:jobs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List durable background jobs",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:jobs:read"
        ]
      }
    },
    "$BUSINESS_API/jobs/dead-letters": {
      "get": {
        "description": "Pages the tenant's dead letters, jobs that failed on every attempt, with limit (default 20, max 100) and the after cursor. Each entry shows the attempts, the last error, when it died and, once retried, the ID of the job that replaced it. The list is empty when background jobs are not enabled. Needs the business:jobs:read scope.",
        "operationId": "listBusinessJobDeadLetters",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only dead letters of this job kind, matched exactly.",
            "in": "query",
            "name": "kind",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeadJobPage"
                }
              }
            },
            "description": "Dead letters"
          },
          "403": {
            "description": "Missing business:jobs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List jobs that exhausted their attempts",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:jobs:read"
        ]
      }
    },
    "$BUSINESS_API/jobs/dead-letters/{id}/retry": {
      "post": {
        "description": "Creates a fresh queued job with the dead letter's kind and payload, marks the dead letter as retried, and answers 202 with the new job. Each dead letter can be retried only once; a second attempt returns 409, as does a call when background jobs are not enabled. Needs the business:jobs:retry scope; a dead letter of another tenant returns 404.",
        "operationId": "retryBusinessJobDeadLetter",
        "parameters": [
          {
            "description": "ID of the dead letter to requeue, as returned by the dead-letters list; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            },
            "description": "The new queued job"
          },
          "403": {
            "description": "Missing business:jobs:retry scope"
          },
          "404": {
            "description": "Dead letter not found in the authenticated tenant"
          },
          "409": {
            "description": "The dead letter was already retried, or the job queue is not enabled on this installation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Requeue a dead letter as a new job; a dead letter can be retried once",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:jobs:retry"
        ]
      }
    },
    "$BUSINESS_API/jobs/summary": {
      "get": {
        "description": "Returns enabled together with a counts map holding the number of the tenant's jobs that are queued, running and succeeded, and the number of dead letters not yet retried. When background jobs are not enabled on the installation, enabled is false and counts is empty. Needs the business:jobs:read scope.",
        "operationId": "getBusinessJobSummary",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobSummary"
                }
              }
            },
            "description": "Status counts. enabled is false, with empty counts, when this installation runs without the job queue."
          },
          "403": {
            "description": "Missing business:jobs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Counts of jobs by status, including dead letters",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:jobs:read"
        ]
      }
    },
    "$BUSINESS_API/jobs/{id}": {
      "get": {
        "description": "Returns one background job of the caller's tenant: kind, status, attempts and max attempts, the worker holding it, the last error, the originating request ID and its timestamps. The payload is not returned. A job of another tenant, or any job when background jobs are not enabled, returns 404. Needs the business:jobs:read scope.",
        "operationId": "getBusinessJob",
        "parameters": [
          {
            "description": "ID of the background job to read; it must belong to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            },
            "description": "The job"
          },
          "403": {
            "description": "Missing business:jobs:read scope"
          },
          "404": {
            "description": "Job not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one job",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:jobs:read"
        ]
      }
    },
    "$BUSINESS_API/ldap": {
      "delete": {
        "description": "Deletes the caller's tenant directory connection. Directory sign-in and synchronization stop; members already synchronized stay. Returns 404 when no connection is configured. Requires business:team:manage (the connection is first read with business:team:read). Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "deleteLdapConnection",
        "responses": {
          "204": {
            "description": "Connection removed"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No directory connection is configured"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove the tenant's directory connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      },
      "get": {
        "description": "Returns the caller's tenant LDAP or Active Directory connection, or a JSON null body with 200 when none is configured. The service account password is never returned. Requires business:team:read (owner and admin roles hold it).",
        "operationId": "getLdapConnection",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/EnterpriseLdapConnection"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            },
            "description": "The directory connection, or null when none is configured"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the tenant's directory connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      },
      "put": {
        "description": "Saves the caller's tenant directory settings, creating the connection on first use. A tenant has one connection; saving again replaces its settings. server_url must use ldap:// or ldaps:// and, outside development, ldap:// needs start_tls true and internal or private hosts are refused. base_dn is required; attribute names default to sAMAccountName, mail and displayName and may contain only letters, digits, underscore and hyphen. bind_password is write-only: omit it to keep the stored password; the response carries has_bind_password instead. Fields outside the input, id and tenant_id among them, are ignored, so a save always lands on the caller's own tenant. A failed validation returns 400. Requires business:team:manage and a person's session: API keys are refused with 403 api_key_not_allowed. The change is recorded in the audit log.",
        "operationId": "saveLdapConnection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseLdapConnectionInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseLdapConnection"
                }
              }
            },
            "description": "The saved connection"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create or replace the tenant's directory connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/ldap/sync": {
      "post": {
        "description": "Runs a synchronization against the configured directory: binds with the service account, searches base_dn (at most 1000 entries, 30 second limit) for entries with an email address, creates or updates tenant members, and suspends members whose directory account is disabled or locked out. The connection must exist and be enabled. Takes no request body. Requires business:team:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "syncLdapDirectory",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseLdapSyncResult"
                }
              }
            },
            "description": "Synchronization counts"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, scope not held, or the connection is turned off"
          },
          "404": {
            "description": "No directory connection is configured"
          },
          "502": {
            "description": "The directory server could not be reached, or refused the service account bind or the search"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Synchronize members from the directory now",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/ldap/test": {
      "post": {
        "description": "Connects to the configured directory server, completes the TLS handshake, binds with the service account when one is set, and reads the root DSE to identify the server. A failed connection or bind is reported in the body with success false and status 200. Takes no request body. Requires business:team:read. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "testLdapConnection",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseLdapTestResult"
                }
              }
            },
            "description": "Test outcome"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No directory connection is configured"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Test connectivity to the directory server",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      }
    },
    "$BUSINESS_API/leak-allowance-policy": {
      "get": {
        "description": "Returns the rules the tenant uses to grant credits for water lost to leaks: whether the allowance is enabled, the credit share and minimum excess in basis points, the history and cooldown months, whether proof of repair is required, and the repair window in days. A tenant that never saved a policy gets the defaults: disabled, 50% credit, 6 months of history, 12-month cooldown, 50% minimum excess, proof required and a 90-day window. Needs the business:leak-allowances:read scope.",
        "operationId": "getLeakAllowancePolicy",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the tenant leak allowance policy",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:leak-allowances:read"
        ]
      },
      "put": {
        "description": "Replaces the whole policy with the body you send; fields left out are saved as false or zero, so send every field. credit_percent_bp must be 0 to 10000, history_months 1 to 36 and cooldown_months 0 to 120, and min_excess_percent_bp and repair_window_days must not be negative (400 otherwise). The change is written to the audit trail. Needs the business:leak-allowances:policy scope.",
        "operationId": "saveLeakAllowancePolicy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "credit_percent_bp",
                  "history_months"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Save the tenant leak allowance policy",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:leak-allowances:policy"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances": {
      "get": {
        "description": "Pages the tenant's leak allowance applications with limit (default 20, max 100) and the after cursor. Filter by status (submitted, inspection_scheduled, inspected, credited or rejected) and account_id. Needs the business:leak-allowances:read scope.",
        "operationId": "listLeakAllowances",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeakAllowanceApplicationPage"
                }
              }
            },
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List leak allowance applications",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:leak-allowances:read"
        ]
      },
      "post": {
        "description": "Checks the invoice against the policy and, when it is eligible, creates an application in status submitted with the proposed credit, returned with status 201. Send a multipart form of up to 6 MB with invoice_id, an optional description and a proof file: a PDF, JPEG or PNG of at most 5 MB, required when the policy demands proof. An invoice that already has an open application returns 409, and an ineligible one returns 400 LEAK_ALLOWANCE_INELIGIBLE. Needs the business:leak-allowances:write scope, and the application is recorded in the audit trail.",
        "operationId": "applyLeakAllowance",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "description": {
                    "type": "string"
                  },
                  "invoice_id": {
                    "type": "string"
                  },
                  "proof": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "invoice_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Apply on behalf of a customer (multipart: invoice_id, description, proof)",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:leak-allowances:read",
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/assess": {
      "post": {
        "description": "Runs the policy against the invoice named by invoice_id and returns the outcome without saving anything. When the invoice is eligible, the result holds the consumption, historic average, excess volume and value, and the proposed credit. Otherwise it gives a reason_code: policy_disabled, invoice_not_open, repair_window_expired, cooldown_active, insufficient_history, below_excess_threshold or no_credit_value. It also says whether proof of repair will be required. Needs the business:leak-allowances:read scope.",
        "operationId": "assessLeakAllowance",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "invoice_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeakAllowanceAssessment"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request or invoice is ineligible (`LEAK_ALLOWANCE_INELIGIBLE`)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Assess an invoice against the policy without saving",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:leak-allowances:read"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/{id}": {
      "get": {
        "description": "Returns one application of the caller's tenant with its account and invoice, its status, the consumption figures and proposed credit, the inspection work order and findings, and the decision with any credit note issued. Returns 404 when the application does not exist in this tenant. Needs the business:leak-allowances:read scope.",
        "operationId": "getLeakAllowance",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a leak allowance application",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:leak-allowances:read"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/{id}/approve": {
      "post": {
        "description": "Issues a credit note for the proposed credit on the application's invoice, records the optional reason and the adjustment ID, and moves the application to credited. Only an inspected application can be approved (409 otherwise). The inspection must have confirmed a leak, and the policy cooldown is checked again at decision time; either failure returns 400 LEAK_ALLOWANCE_INELIGIBLE. The person who requested the application cannot approve it (403). Needs the business:leak-allowances:approve scope, and the decision is recorded in the audit trail.",
        "operationId": "approveLeakAllowance",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve and issue the credit note; the requester cannot approve",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:leak-allowances:approve"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/{id}/inspection": {
      "post": {
        "description": "Creates an inspection work order on the application's account and moves the application from submitted to inspection_scheduled, storing the work order ID. Optional notes are appended to the work order's description. Any status other than submitted returns 409. Needs the business:leak-allowances:write scope, and the action is recorded in the audit trail.",
        "operationId": "scheduleLeakInspection",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule the inspection work order",
        "x-roles": [
          "admin",
          "customer_service",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:leak-allowances:write"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/{id}/inspection-result": {
      "post": {
        "description": "Stores what the field visit found (leak_confirmed and the required notes), along with the inspector and time, and moves the application to inspected. The application must be in inspection_scheduled (409 otherwise), and empty notes return 400. Only an inspection that confirms a leak can lead to approval. Needs the business:leak-allowances:write scope, and the result is recorded in the audit trail.",
        "operationId": "recordLeakInspection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "leak_confirmed",
                  "notes"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record the inspection result",
        "x-roles": [
          "admin",
          "customer_service",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:leak-allowances:write"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/{id}/proof": {
      "get": {
        "description": "Streams the proof of repair uploaded with the application as an attachment, using the original file name and a content type taken from its extension (PDF, JPEG or PNG). Returns 404 when the application is not in the caller's tenant, has no proof, or the file cannot be opened. Needs the business:leak-allowances:read scope.",
        "operationId": "getLeakAllowanceProof",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download proof of repair",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:leak-allowances:read"
        ]
      }
    },
    "$BUSINESS_API/leak-allowances/{id}/reject": {
      "post": {
        "description": "Closes an application that is not yet decided, storing the required reason, the decider and the time, and moving it to rejected. It can be called at any stage before a decision. An application that is already credited or rejected returns 409, and an empty reason returns 400. Needs the business:leak-allowances:approve scope, and the rejection is recorded in the audit trail.",
        "operationId": "rejectLeakAllowance",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject an application with a reason",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:leak-allowances:approve"
        ]
      }
    },
    "$BUSINESS_API/ledger/accounts": {
      "get": {
        "description": "Returns the general ledger accounts of the caller's tenant, ordered by account number, with cursor pagination (limit defaults to 20, at most 100). The optional q parameter matches account names and numbers. Requires the ledger:read permission.",
        "operationId": "listLedgerAccounts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Filter by name or number",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filters by account state: the value true returns only active accounts, any other non-empty value returns only inactive accounts, and omitting it returns both.",
            "in": "query",
            "name": "active",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerAccountPage"
                }
              }
            },
            "description": "Accounts"
          },
          "403": {
            "description": "Missing ledger:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the tenant's chart of accounts",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "ledger:read"
        ]
      },
      "post": {
        "description": "Adds an account with the given account_number, account_name and account_type (asset, liability, equity, revenue or expense) to the tenant's chart; the account is created active and takes the currency of the existing chart. Returns 400 when a required field is missing, the type is invalid, or the tenant's chart has not been seeded yet. Requires the ledger:write permission.",
        "operationId": "createLedgerAccount",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/LedgerAccountInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerAccount"
                }
              }
            },
            "description": "Account"
          },
          "400": {
            "description": "Invalid account input"
          },
          "403": {
            "description": "Missing ledger:write scope"
          },
          "409": {
            "description": "Account number already exists"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a tenant-specific account to the chart",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "ledger:write"
        ]
      }
    },
    "$BUSINESS_API/ledger/entries": {
      "get": {
        "description": "Returns the tenant's posted journal entries, newest first, each with its debit and credit lines, using cursor pagination (limit defaults to 20, at most 100). Filters combine with AND; an invalid cursor or a from/to value that is not RFC 3339 returns 400. Requires the ledger:read permission.",
        "operationId": "listLedgerEntries",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Ledger account ID; returns only entries that have at least one line posted to this account.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Customer or tenant on a sub-ledger line",
            "in": "query",
            "name": "party_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact name of the module that posted the entry, such as ledger for manual reversals.",
            "in": "query",
            "name": "source_module",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact source reference the posting module recorded on the entry (for example the ID of the invoice or payment it came from, or reversal:<entry id> for a reversal).",
            "in": "query",
            "name": "source_reference_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp; returns only entries whose entry date is at or after this instant.",
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp; returns only entries whose entry date is at or before this instant.",
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerEntryPage"
                }
              }
            },
            "description": "Journal entries"
          },
          "400": {
            "description": "Invalid date filter"
          },
          "403": {
            "description": "Missing ledger:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List journal entries with their lines",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "ledger:read"
        ]
      }
    },
    "$BUSINESS_API/ledger/entries/{id}": {
      "get": {
        "description": "Returns the journal entry with its entry number, source module and reference, description, the user who posted it, the entry it reverses if any, and all of its lines. Returns 404 when the entry does not exist in the caller's tenant. Requires the ledger:read permission.",
        "operationId": "getLedgerEntry",
        "parameters": [
          {
            "description": "ID of the journal entry in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerEntry"
                }
              }
            },
            "description": "Journal entry"
          },
          "403": {
            "description": "Missing ledger:read scope"
          },
          "404": {
            "description": "Not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one journal entry and its lines",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "ledger:read"
        ]
      }
    },
    "$BUSINESS_API/ledger/entries/{id}/reverse": {
      "post": {
        "description": "Posts a new entry dated now that swaps the debit and credit side of every line of the original, which stays unchanged; the reversal is linked to the original and returned with 201. A non-empty reason is required and is added to the reversal's description. Returns 409 when the entry has already been reversed or is itself a reversing entry, and 404 when it does not exist. Requires the ledger:write permission.",
        "operationId": "reverseLedgerEntry",
        "parameters": [
          {
            "description": "ID of the journal entry to reverse, in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerEntry"
                }
              }
            },
            "description": "Reversing entry"
          },
          "400": {
            "description": "Invalid reversal request"
          },
          "403": {
            "description": "Missing ledger:write scope"
          },
          "404": {
            "description": "Entry not found"
          },
          "409": {
            "description": "Already reversed, or a reversal cannot be reversed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Correct an entry with a mirror-image reversing entry",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "ledger:write"
        ]
      }
    },
    "$BUSINESS_API/ledger/reconciliation": {
      "get": {
        "description": "Compares the balance of the receivable and unallocated cash control accounts, and of the stock control account where stock is valued, with the totals reported by the operational sub-ledgers. Each pair returns the control balance, the sub-ledger total and the difference in minor units, and balanced is true only when every difference is zero. Returns 400 when sub-ledger totals are not configured on the server. Requires the ledger:read permission.",
        "operationId": "getLedgerReconciliation",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerReconciliation"
                }
              }
            },
            "description": "Reconciliation"
          },
          "403": {
            "description": "Missing ledger:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Compare control accounts to the billing and payment sub-ledgers",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "ledger:read"
        ]
      }
    },
    "$BUSINESS_API/ledger/trial-balance": {
      "get": {
        "description": "Returns the debit and credit totals of every account in the tenant's chart, computed from all posted entries or, with the optional as_of RFC 3339 timestamp, only from entries up to that instant. Because every posting is validated as balanced, the debit and credit totals match. Returns 400 when as_of is not RFC 3339. Requires the ledger:read permission.",
        "operationId": "getLedgerTrialBalance",
        "parameters": [
          {
            "description": "Entries dated at or before this RFC 3339 instant",
            "in": "query",
            "name": "as_of",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerTrialBalance"
                }
              }
            },
            "description": "Trial balance"
          },
          "400": {
            "description": "Invalid as_of timestamp"
          },
          "403": {
            "description": "Missing ledger:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Trial balance; total debits equal total credits",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "ledger:read"
        ]
      }
    },
    "$BUSINESS_API/metadata": {
      "get": {
        "description": "Searches the metadata attached to the tenant's records and returns the matching resources with their full metadata, using cursor pagination. At least one of key or value must be given, otherwise the call returns 400; resource_type narrows the search to one kind of record (customer, account, property, meter, connection, invoice, payment, ticket, work_order, incident, tariff or reading_route). Requires the business:metadata:read permission.",
        "operationId": "listBusinessMetadataResources",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Metadata key to match; give key, value or both.",
            "example": "external_ref",
            "in": "query",
            "name": "key",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact metadata value to match; give key, value or both.",
            "in": "query",
            "name": "value",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Restrict to one resource type",
            "in": "query",
            "name": "resource_type",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntryPage"
                }
              }
            },
            "description": "Resources with metadata"
          },
          "400": {
            "description": "Neither key nor value was given (RFC 7807)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List resources by metadata; key or value is required",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      }
    },
    "$BUSINESS_API/meter-inspection-requests": {
      "get": {
        "description": "Returns inspection requests for the tenant's meters, both those raised by consumers and the field re-reads raised by staff, with cursor pagination. Filters combine with AND; an unknown status returns 400. Requires the business:inspection-requests:read permission.",
        "operationId": "listMeterInspectionRequests",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only requests raised for this customer account.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only requests for this meter.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Request state: open, scheduled, completed or cancelled; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "open",
                "scheduled",
                "completed",
                "cancelled"
              ],
              "type": "string"
            }
          },
          {
            "description": "Who raised the request: consumer for a request from the account holder, or field_reread for a re-read raised by staff.",
            "in": "query",
            "name": "kind",
            "schema": {
              "enum": [
                "consumer",
                "field_reread"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterInspectionRequestPage"
                }
              }
            },
            "description": "Tenant-scoped inspection requests"
          },
          "400": {
            "description": "Invalid filter or pagination"
          },
          "403": {
            "description": "Missing business:inspection-requests:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List consumer and field-reader meter-inspection requests",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:inspection-requests:read"
        ]
      }
    },
    "$BUSINESS_API/meter-inspection-requests/{id}/status": {
      "patch": {
        "description": "Moves an inspection request to a new status and returns 204 with no body. An open request can be scheduled (scheduled_at is required and must be in the future) or cancelled; only a scheduled request can be completed; completing or cancelling requires a non-empty resolution text. Returns 409 when the request's current status does not allow the change and 400 for a missing or invalid field. Requires the business:inspection-requests:manage permission.",
        "operationId": "updateMeterInspectionRequest",
        "parameters": [
          {
            "description": "ID of the inspection request in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InspectionRequestResolution"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Inspection request state updated"
          },
          "400": {
            "description": "Invalid status transition",
            "or resolution": null,
            "schedule time": null
          },
          "403": {
            "description": "Missing business:inspection-requests:manage scope"
          },
          "404": {
            "description": "Inspection request not found in the authenticated tenant"
          },
          "409": {
            "description": "Inspection request state conflicts with the requested transition"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule, complete, or cancel an inspection request",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:inspection-requests:manage"
        ]
      }
    },
    "$BUSINESS_API/meter-installations": {
      "get": {
        "description": "Returns installation records (meter, connection, account, installation time, initial reading and seal number) across the tenant, with cursor pagination. With no filter every installation is returned. Requires the business:meters:read permission.",
        "operationId": "listMeterInstallations",
        "parameters": [
          {
            "description": "Returns only installations on this connection.",
            "in": "query",
            "name": "connection_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only installations of this meter.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "When true or 1, returns only installations that are still in place (the meter has not been removed); any other value returns open and closed installations.",
            "in": "query",
            "name": "open",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterInstallationPage"
                }
              }
            },
            "description": "Installations, newest first"
          },
          "400": {
            "description": "Invalid pagination"
          },
          "403": {
            "description": "Missing business:meters:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Installation history filtered by connection or meter",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:meters:read"
        ]
      }
    },
    "$BUSINESS_API/metered-reconciliations": {
      "get": {
        "description": "Returns the tenant's metered reconciliations with their computed expected amount, variances, flags and status (draft, confirmed or settled), using cursor pagination. The optional status, meter_id and account_id query values filter the list. Requires the business:reconciliations:read permission.",
        "operationId": "listMeteredReconciliations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List metered volume and remittance reconciliations",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      },
      "post": {
        "description": "Creates a draft reconciliation for one meter and period: it reads the metered volume from the meter's readings (or uses metered_litres when no readings span the period), prices it with the reconciliation tariff active at period_end, and compares it with the reported volume, reported revenue and remitted cash. Differences beyond the tariff's tolerance raise flags. Returns 400 when the period is invalid, figures are negative, the meter has no active operator contract, no tariff covers the period, or no metered volume is available. Requires the business:reconciliations:write permission.",
        "operationId": "createMeteredReconciliation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "meter_id",
                  "period_start",
                  "period_end",
                  "reported_cents",
                  "remitted_cents"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reconcile metered volume against reported sales and remitted cash",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reconciliations:write"
        ]
      }
    },
    "$BUSINESS_API/metered-reconciliations/{id}": {
      "get": {
        "description": "Returns one reconciliation with the metered and reported volumes, where the metered volume came from (meter_readings or entered), the expected, reported and remitted amounts, the variances and the flags raised. Returns 404 when it does not exist in the caller's tenant. Requires the business:reconciliations:read permission.",
        "operationId": "getMeteredReconciliation",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a metered reconciliation with variance flags",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      }
    },
    "$BUSINESS_API/metered-reconciliations/{id}/confirm": {
      "post": {
        "description": "Moves a draft reconciliation to confirmed, which makes it eligible for settlement, and returns the updated record. Returns 409 when the reconciliation is not in draft. Requires the business:reconciliations:settle permission.",
        "operationId": "confirmMeteredReconciliation",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm a metered reconciliation",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:reconciliations:settle"
        ]
      }
    },
    "$BUSINESS_API/metered-reconciliations/{id}/settle": {
      "post": {
        "description": "Issues the settlement statement for a confirmed reconciliation: the commission is computed from the remitted amount and the contract's commission rate, the balance is the expected amount minus commission and remittance, and the reconciliation moves to settled. Returns the new settlement with 201. Returns 409 when the reconciliation is not confirmed, so a second call cannot issue a duplicate statement. Requires the business:reconciliations:settle permission.",
        "operationId": "settleMeteredReconciliation",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue the reconciliation settlement statement",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:reconciliations:settle"
        ]
      }
    },
    "$BUSINESS_API/meters": {
      "get": {
        "description": "Returns the tenant's meters with cursor pagination. The optional q parameter searches meters and also matches meters of accounts whose holder matches the text. An unknown status value returns 400. Requires the business:meters:read permission.",
        "operationId": "listMeters",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "description": "Returns only meters assigned to this customer account.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Operational status: active, inactive or retired; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "active",
                "inactive",
                "retired"
              ],
              "type": "string"
            }
          },
          {
            "description": "Physical device state: in_warehouse, installed, in_testing or scrapped.",
            "in": "query",
            "name": "device_status",
            "schema": {
              "enum": [
                "in_warehouse",
                "installed",
                "in_testing",
                "scrapped"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterPage"
                }
              }
            },
            "description": "Meters in the authenticated utility tenant"
          },
          "400": {
            "description": "Invalid meter filter or pagination"
          },
          "403": {
            "description": "Missing business:meters:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List tenant-owned meters",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:meters:read"
        ]
      },
      "post": {
        "description": "Registers a meter with its serial number (stored upper case), unit, precision (0 to 9) and optional device details, and returns it with 201. A meter registered as in_warehouse or in_testing may have no account and starts inactive; otherwise account_id must name an active account and the meter starts active and installed. Returns 400 for invalid fields or an installed_at in the future, and 404 when the account does not exist. Requires the business:meters:create permission.",
        "operationId": "createMeter",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMeter"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meter"
                }
              }
            },
            "description": "Meter registered"
          },
          "400": {
            "description": "Invalid meter or account input"
          },
          "403": {
            "description": "Missing business:meters:create scope"
          },
          "409": {
            "description": "Meter serial number conflicts with an existing record"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a meter against a utility account",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meters:create"
        ]
      }
    },
    "$BUSINESS_API/meters/exchange": {
      "post": {
        "description": "Closes the old installation, opens the new one, records final and start readings, flips both devices and supersedes the bi-temporal binding in one transaction. Idempotent on idempotency_key.",
        "operationId": "exchangeMeter",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MeterExchangeInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterExchangeResult"
                }
              }
            },
            "description": "Exchange recorded"
          },
          "400": {
            "description": "Invalid meter exchange"
          },
          "403": {
            "description": "Missing business:meters:manage scope"
          },
          "404": {
            "description": "Connection",
            "old meter": null,
            "or new meter not found in the authenticated tenant": null
          },
          "409": {
            "description": "Meter exchange conflicts with current installation state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace an installed meter atomically",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meters:manage"
        ]
      }
    },
    "$BUSINESS_API/meters/install": {
      "post": {
        "description": "Installs a meter on a connection in one transaction: it records the installation, binds the meter to the connection from installed_at, marks the meter active and installed, records an accepted initial reading, and emits a meter.installed event. idempotency_key is required; repeating it with the same meter and connection returns the existing installation, and with different values returns 409. Returns 409 when the connection or the meter already has an open installation or the meter is scrapped, and 400 when no active account can be resolved. Requires the business:meters:manage permission.",
        "operationId": "installMeter",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MeterInstallInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterInstallation"
                }
              }
            },
            "description": "Installation recorded"
          },
          "400": {
            "description": "Invalid meter installation"
          },
          "403": {
            "description": "Missing business:meters:manage scope"
          },
          "404": {
            "description": "Connection or meter not found in the authenticated tenant"
          },
          "409": {
            "description": "Meter installation conflicts with current device or connection state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Install a meter on a connection, writing the installation, start reading and bi-temporal binding atomically",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meters:manage"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}": {
      "get": {
        "description": "Returns the meter with its serial number, account, unit and precision, status, device status, role (standard, master or submeter) and installation dates. Returns 404 when the meter does not exist in the caller's tenant. Requires the business:meters:read permission.",
        "operationId": "getMeter",
        "parameters": [
          {
            "description": "ID of the meter in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Meter"
                }
              }
            },
            "description": "Meter details"
          },
          "403": {
            "description": "Missing business:meters:read scope"
          },
          "404": {
            "description": "Meter not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a tenant-owned meter",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:meters:read"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/balance": {
      "get": {
        "description": "Sums the consumption recorded for the master meter and for each of its sub-meters over the period (litres are converted to cubic metres) and returns the unaccounted loss, the loss percentage and a negative_balance flag when the sub-meters add up to more than the master. Returns 400 when the meter is not a master meter or the period ends before it starts. Requires the business:meters:read permission.",
        "operationId": "getMasterMeterBalance",
        "parameters": [
          {
            "description": "ID of a meter whose role is master.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 start of the period, matched against the end of each consumption period; defaults to the first day of the current month in UTC.",
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 end of the period; defaults to the first day of next month in UTC and must not be before from.",
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MasterMeterBalance"
                }
              }
            },
            "description": "Master meter water balance"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Compute water balance for a master meter against its sub-meters",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:meters:read"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/commands": {
      "get": {
        "description": "Returns the commands queued for the meter with their status, type, assigned collector and timestamps, using cursor pagination. Requires the business:meter-commands:read permission.",
        "operationId": "listMeterCommands",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "ID of the meter whose commands are listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterCommandPage"
                }
              }
            },
            "description": "Meter commands"
          },
          "400": {
            "description": "Invalid pagination"
          },
          "403": {
            "description": "Missing business:meter-commands:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List meter commands",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meter-commands:read"
        ]
      },
      "post": {
        "description": "Queues the command for the collector assigned to the meter and returns it with 201 in queued status; it expires after 24 hours and is tried at most 5 times. An idempotency_key repeated for the same meter and type returns the existing command, and for a different meter or type returns 409. Returns 409 with code METER_NO_COLLECTOR when no collector is assigned, 404 when the meter is not in the tenant, and 400 for an unknown type or parameters larger than 8 KB.",
        "operationId": "createMeterCommand",
        "parameters": [
          {
            "description": "ID of the meter in the caller's tenant that the command is sent to.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateMeterCommand"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterCommand"
                }
              }
            },
            "description": "Command queued"
          },
          "400": {
            "description": "Invalid command type or parameters"
          },
          "403": {
            "description": "Missing the scope required by the command type"
          },
          "404": {
            "description": "Meter not found in the authenticated tenant"
          },
          "409": {
            "description": "No active collector is assigned",
            "or the command conflicts with an existing command": null
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue a command against a meter. read and inspect need business:meter-commands:create, synchronize and reset-alarm need supervise, disconnect and reconnect need actuate and are audited.",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meter-commands:create"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/commands/capability": {
      "get": {
        "description": "A meter without an active collector assignment cannot receive commands; creating one then answers 409 with code METER_NO_COLLECTOR.",
        "operationId": "getMeterCommandCapability",
        "parameters": [
          {
            "description": "ID of the meter to check; the response says whether a collector is assigned to it and which one.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterCommandCapability"
                }
              }
            },
            "description": "Command capability"
          },
          "403": {
            "description": "Missing business:meter-commands:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Report whether remote commands can reach a meter",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meter-commands:read"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/commands/{command_id}": {
      "get": {
        "description": "Returns one command with its type, status, parameters, assigned collector and timing. Returns 404 when the command does not exist in the tenant or belongs to a different meter than the one in the path. Requires the business:meter-commands:read permission.",
        "operationId": "getMeterCommand",
        "parameters": [
          {
            "description": "ID of the meter the command was sent to.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the command; it must belong to the meter given in id.",
            "in": "path",
            "name": "command_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterCommand"
                }
              }
            },
            "description": "Meter command"
          },
          "403": {
            "description": "Missing business:meter-commands:read scope"
          },
          "404": {
            "description": "Meter or command not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a meter command",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meter-commands:read"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/device-status": {
      "post": {
        "description": "The meter module stays the owner of the meter; inventory moves its serial in the same transaction and refuses the change when the serial is not where the action claims. Installed meters leave their connection through an exchange.",
        "operationId": "changeMeterDeviceStatus",
        "parameters": [
          {
            "description": "Meter ID (mtr_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MeterDeviceStatusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Meter with its new device status"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing business:meters:manage scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Move a meter that is not on a connection: testing, back to a warehouse, or scrap",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meters:manage"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/installations": {
      "get": {
        "description": "Returns every installation of this meter, past and current, with the connection, account, installation time, initial reading and seal number, using cursor pagination. Requires the business:meters:read permission.",
        "operationId": "listMeterInstallationsForMeter",
        "parameters": [
          {
            "description": "ID of the meter whose installation history is listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterInstallationPage"
                }
              }
            },
            "description": "Installations, newest first"
          },
          "400": {
            "description": "Invalid pagination"
          },
          "403": {
            "description": "Missing business:meters:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Installation history of one meter",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:meters:read"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/metadata": {
      "get": {
        "description": "Returns the key-value metadata stored on the meter, or an empty map when none is set. Returns 404 when the meter does not exist in the caller's tenant. Requires the business:metadata:read permission.",
        "operationId": "getBusinessMeterMetadata",
        "parameters": [
          {
            "description": "ID of the meter in the caller's tenant, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a meter",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the given keys into the meter's existing metadata and returns the full result; keys not sent are kept, and sending a key with an empty string removes it. Keys must be 1 to 40 characters with no square brackets or control characters, values at most 500 characters, and a meter can hold at most 50 keys; violations return 400 listing each invalid field. Requires the business:metadata:write permission.",
        "operationId": "putBusinessMeterMetadata",
        "parameters": [
          {
            "description": "ID of the meter in the caller's tenant, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/reset": {
      "post": {
        "description": "Records a reset of the meter's register: reset_reading_value becomes the new baseline and prior_reading_value (defaulting to the last accepted reading at or before reset_at) is kept for audit; reset_at defaults to now and must fall between installation and now. reason and idempotency_key are required; repeating the key with identical values returns the existing reset, and with different values returns 409. Returns 409 when the meter is not active. Requires the business:meters:manage permission.",
        "operationId": "resetMeter",
        "parameters": [
          {
            "description": "ID of the active meter being reset.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "idempotency_key": {
                    "maxLength": 160,
                    "type": "string"
                  },
                  "prior_reading_value": {
                    "type": "string"
                  },
                  "reason": {
                    "maxLength": 500,
                    "type": "string"
                  },
                  "reset_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "reset_reading_value": {
                    "type": "string"
                  }
                },
                "required": [
                  "reset_reading_value",
                  "reason",
                  "idempotency_key"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterReset"
                }
              }
            },
            "description": "Meter reset recorded"
          },
          "400": {
            "description": "Invalid reset values",
            "or idempotency input": null,
            "reason": null
          },
          "403": {
            "description": "Missing business:meters:manage scope"
          },
          "404": {
            "description": "Meter not found in the authenticated tenant"
          },
          "409": {
            "description": "Reset idempotency key conflicts with a previous reset"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an authorized meter reset baseline",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meters:manage"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/resets": {
      "get": {
        "description": "Returns the resets recorded for the meter, each with the prior and new reading values, reason, reset time and the user who authorized it, using cursor pagination. Requires the business:meters:read permission.",
        "operationId": "listMeterResets",
        "parameters": [
          {
            "description": "ID of the meter whose resets are listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterResetPage"
                }
              }
            },
            "description": "Meter resets recorded for this meter"
          },
          "400": {
            "description": "Invalid pagination"
          },
          "403": {
            "description": "Missing business:meters:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List audit resets recorded for a meter",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:meters:read"
        ]
      }
    },
    "$BUSINESS_API/meters/{id}/status": {
      "patch": {
        "description": "Sets the meter's status to active, inactive or retired and returns 204 with no body; setting the status it already has changes nothing. Retiring a meter records its removal time and marks the device as scrapped. Returns 400 for any other status and 404 when the meter does not exist. Requires the business:meters:manage permission.",
        "operationId": "setMeterStatus",
        "parameters": [
          {
            "description": "ID of the meter in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "inactive",
                      "retired"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Meter status updated"
          },
          "400": {
            "description": "Invalid meter status or state transition"
          },
          "403": {
            "description": "Missing business:meters:manage scope"
          },
          "404": {
            "description": "Meter not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a meter's operational status",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:meters:manage"
        ]
      }
    },
    "$BUSINESS_API/metrics": {
      "get": {
        "description": "Returns, under data, the tenant's month-to-date operational figures, each with a key, name, unit, value and computation timestamp: billed and collected amounts, collection efficiency, billed volume, open receivables, active connections and active meters. Values are computed on each call. Requires the reports:read permission.",
        "operationId": "listBusinessMetrics",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Metrics catalog"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility governed metrics catalog",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      }
    },
    "$BUSINESS_API/next-steps": {
      "get": {
        "description": "Returns the next one to three actionable steps for the signed-in utility user and their tenant, chosen and ordered by the server from progress, review state, capabilities, counts and connectors; an empty list when nothing is waiting. Each step has a stable ID, localized title and line (saved language, then Accept-Language, then the platform default), the role that acts, a portable action ID the client maps to its own screen, and a help article ID from the shared help registry. Clients keep no step list or order of their own. GET is safe to retry and completes nothing. Requires business:onboarding:read for the utility owner and admins (test-account tour, then the real-account checklist). A field reader, cashier or finance user without that scope gets their own role's first-run step, authorized by the entitlement of that action; the role comes from the principal's assigned roles.",
        "operationId": "getBusinessNextSteps",
        "parameters": [
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NextSteps"
                }
              }
            },
            "description": "Next steps"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or entitlement"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The next one to three first-use steps"
      }
    },
    "$BUSINESS_API/notification-intents": {
      "get": {
        "description": "Message rendering and channel delivery are performed externally.",
        "operationId": "listNotificationIntents",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/NotificationEventType"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationIntentPage"
                }
              }
            },
            "description": "Utility-scoped notification intents"
          },
          "403": {
            "description": "Missing business:notification-intents:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List durable business notification intents",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:notification-intents:read"
        ]
      },
      "post": {
        "description": "Captures the recipient's preferred locale at creation time; message rendering and channel delivery are performed externally.",
        "operationId": "createNotificationIntent",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateNotificationIntent"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationIntent"
                }
              }
            },
            "description": "Notification intent queued"
          },
          "400": {
            "description": "Invalid notification intent"
          },
          "403": {
            "description": "Missing business:notification-intents:create"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue a recipient notification intent",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:notification-intents:create"
        ]
      }
    },
    "$BUSINESS_API/notification-intents/{id}": {
      "get": {
        "description": "Returns one notification intent with its event type, recipient, related resource, inbox text, template, delivery plan, status and, when present, its delivery. Returns 404 when the intent does not exist in the caller's tenant. Requires the business:notification-intents:read permission.",
        "operationId": "getNotificationIntent",
        "parameters": [
          {
            "description": "ID of the notification intent in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationIntent"
                }
              }
            },
            "description": "Utility-scoped notification intent"
          },
          "403": {
            "description": "Missing business:notification-intents:read"
          },
          "404": {
            "description": "Notification intent not found in the active utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a notification intent",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:notification-intents:read"
        ]
      }
    },
    "$BUSINESS_API/notification-preferences": {
      "get": {
        "description": "Returns the recorded communication preferences of the tenant's recipients: consent status, preferred locale, per-event and per-channel choices, quiet hours and time zone. The optional recipient_type and recipient_id query values narrow the list, and results use cursor pagination. Requires the notifications:read permission.",
        "operationId": "listBusinessNotificationPreferences",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreferencePage"
                }
              }
            },
            "description": "Utility-scoped, channel-neutral preferences"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility communication preferences and consent policies",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "notifications:read"
        ]
      },
      "patch": {
        "description": "Requires notifications:write. The change is written to the audit log.",
        "operationId": "updateBusinessNotificationPreference",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "channels": {
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "description": "Per-channel delivery choices for email, push, and in_app",
                    "type": "object"
                  },
                  "consent_status": {
                    "enum": [
                      "granted",
                      "withdrawn",
                      "required_notice_only"
                    ],
                    "type": "string"
                  },
                  "events": {
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "description": "Per-event delivery choices",
                    "type": "object"
                  },
                  "preferred_locale": {
                    "enum": [
                      "pt-MZ",
                      "en-US"
                    ],
                    "type": "string"
                  },
                  "quiet_hours_end": {
                    "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                    "type": "string"
                  },
                  "quiet_hours_start": {
                    "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                    "type": "string"
                  },
                  "recipient_id": {
                    "maxLength": 120,
                    "type": "string"
                  },
                  "recipient_type": {
                    "maxLength": 32,
                    "type": "string"
                  },
                  "timezone": {
                    "description": "IANA time zone required when quiet hours are set",
                    "type": "string"
                  }
                },
                "required": [
                  "recipient_type",
                  "recipient_id",
                  "consent_status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreference"
                }
              }
            },
            "description": "Stored preference"
          },
          "400": {
            "description": "Invalid recipient or consent status"
          },
          "403": {
            "description": "Missing notifications:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a recipient's consent, channel and event choices, locale, or quiet hours",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "notifications:write"
        ]
      }
    },
    "$BUSINESS_API/onboarding": {
      "get": {
        "description": "Returns the tenant's onboarding application with its status, the requirements currently due, pending verification and satisfied, any information requests from reviewers, and the capabilities the tenant has. If the tenant has no application yet, one is created in not_started status. Requires the business:onboarding:read permission.",
        "operationId": "getBusinessOnboarding",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application with computed requirements, capabilities and documents"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the utility onboarding application, created on first read",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:read"
        ]
      },
      "patch": {
        "description": "Updates only the sections and fields sent (business profile, representative, collection channels, settlement account, terms acceptance) and returns the recomputed application; a not_started application moves to in_progress. Fields that fail validation are all reported in one 400 response, and updating a field clears the reviewer's information request for it. Returns 409 when the application is not editable; an approved application may still change payment details or correct its tax number.",
        "operationId": "updateBusinessOnboarding",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOnboarding"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Updated application"
          },
          "400": {
            "description": "invalid_params lists each failing field"
          },
          "409": {
            "description": "Application is not editable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Partially update onboarding sections, validated field by field",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:write"
        ]
      }
    },
    "$BUSINESS_API/onboarding/documents": {
      "get": {
        "description": "Returns, under data, every document uploaded for the tenant's onboarding application with its type, file name, content type, size and review status. The file contents are not included; use the file download operation for that. Requires the business:onboarding:read permission.",
        "operationId": "getOnboardingDocumentsBusiness",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingDocumentList"
                }
              }
            },
            "description": "Documents"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List uploaded onboarding documents",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:read"
        ]
      },
      "post": {
        "description": "Accepts a multipart form with a type field (incorporation, tax_certificate, concession_licence or representative_id) and a file field, and stores the document in pending status with 201. The file type is detected from its content; anything other than PDF, JPEG or PNG returns 415, and a file over 10 MiB returns 413. Returns 409 when the application is not editable (not_started, in_progress or action_required).",
        "operationId": "uploadOnboardingDocument",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OnboardingDocumentUpload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingDocument"
                }
              }
            },
            "description": "Stored document"
          },
          "400": {
            "description": "Unknown type or missing file"
          },
          "413": {
            "description": "Too large"
          },
          "415": {
            "description": "Content type not allowed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload a document (PDF, JPEG or PNG, up to 10 MiB)",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:write"
        ]
      }
    },
    "$BUSINESS_API/onboarding/documents/{id}": {
      "delete": {
        "description": "Removes the document record and its stored file and returns 204. Returns 409 when the application is no longer editable (for example once it has been submitted), and 404 when the document does not exist. Requires the business:onboarding:write permission.",
        "operationId": "deleteOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a document while the application is editable",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:write"
        ]
      },
      "get": {
        "description": "Returns the document's type, file name, content type, size and review status without its contents. Returns 404 when the document does not exist in the caller's tenant. Requires the business:onboarding:read permission.",
        "operationId": "getOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingDocument"
                }
              }
            },
            "description": "Document"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get document metadata",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:read"
        ]
      }
    },
    "$BUSINESS_API/onboarding/documents/{id}/file": {
      "get": {
        "description": "Streams the stored file as an attachment with its original file name and the content type detected at upload. Returns 404 when the document or its stored file is missing. Requires the business:onboarding:read permission.",
        "operationId": "downloadOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File bytes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the stored document",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:read"
        ]
      }
    },
    "$BUSINESS_API/onboarding/handover": {
      "get": {
        "description": "Returns, to the invited owner only, what the platform completed (step IDs, who and when) and the outstanding real-account steps, before and after acceptance. Requires business:onboarding:read; other principals get 404.",
        "operationId": "getUtilityHandover",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityHandoverSummary"
                }
              }
            },
            "description": "Handover summary"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No handover for this owner"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The handover summary of a utility the platform set up"
      }
    },
    "$BUSINESS_API/onboarding/handover/accept": {
      "post": {
        "description": "The invited owner accepts the summary: the utility becomes owner managed, the event is audited with the operator's ID and name, platform-completed steps are carried into the owner's checklist with their attribution, and the operator's setup access ends. The owner's existing session then reaches every business route without signing in again. Only the owner can call it, with business:onboarding:write. Repeating it returns the summary.",
        "operationId": "acceptUtilityHandover",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityHandoverSummary"
                }
              }
            },
            "description": "Accepted handover summary"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No handover for this owner"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The invitation is not accepted yet"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept the handover of a utility the platform set up"
      }
    },
    "$BUSINESS_API/onboarding/requirements/{key}": {
      "post": {
        "description": "Stores the given text value (1 to 4000 characters) as evidence for a manual-review requirement configured in the verification catalog and marks it submitted for platform review. Returns 400 when the key is not a manual requirement or is not required for this tenant, and 409 when the requirement is already verified or the application is submitted or under review.",
        "operationId": "submitCustomOnboardingRequirement",
        "parameters": [
          {
            "description": "Key of a manual-review requirement from the verification catalog, in the form custom.<name> where the name uses lower-case letters, digits, dots, underscores and hyphens, up to 80 characters in total.",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "pattern": "^custom\\.[a-z0-9][a-z0-9._-]*$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "value": {
                    "maxLength": 4000,
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "value"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application with submitted evidence state"
          },
          "400": {
            "description": "Invalid or inactive requirement"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "409": {
            "description": "Application state does not allow evidence submission"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit text evidence for a configured manual verification requirement",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:write"
        ]
      }
    },
    "$BUSINESS_API/onboarding/submit": {
      "post": {
        "description": "Moves the application to submitted so the platform can review it, records the submission time and returns the updated application. Returns 409 listing every outstanding requirement while anything is currently due, and 409 when the application is not in not_started, in_progress or action_required. Requires the business:onboarding:submit permission.",
        "operationId": "submitBusinessOnboarding",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Submitted application"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProblemDetails"
                    },
                    {
                      "properties": {
                        "code": {
                          "enum": [
                            "REQUIREMENTS_OUTSTANDING",
                            "APPLICATION_STATE",
                            "APPLICATION_CHANGED"
                          ],
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Not submittable. The problem's code says why: REQUIREMENTS_OUTSTANDING (invalid_params name every currently_due requirement, each with code outstanding), APPLICATION_STATE (the application's status does not allow a submit, for example it is already submitted or approved) or APPLICATION_CHANGED (it changed concurrently; reload and retry)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit the application for review",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:submit"
        ]
      }
    },
    "$BUSINESS_API/organization": {
      "get": {
        "description": "Returns the organization that owns the caller's tenant: its name, type, utility kind, billing mode and status. Requires the business:organization:read permission.",
        "operationId": "getBusinessOrganization",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            },
            "description": "Utility organization and tenant settings"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the authenticated utility profile",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/organization-links/{linkID}/approve": {
      "post": {
        "description": "Activates a pending request from another organization to administer this tenant, recording the approver and the grants given; grants map a role to scopes and only admin: accounts:read, finance: billing:read, analyst: portfolio:read and support: support:read are accepted. Only a staff member with the owner role in the linked tenant may approve; others get 403. Returns 400 for invalid grants or a link that is not pending, and 429 when the organization's plan account limit is reached; the decision is audited.",
        "operationId": "approveOrganizationAccountLink",
        "parameters": [
          {
            "description": "ID of the pending organization link request for the caller's tenant.",
            "in": "path",
            "name": "linkID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "grants": {
                    "additionalProperties": {
                      "items": {
                        "enum": [
                          {
                            "accounts": "read"
                          },
                          {
                            "billing": "read"
                          },
                          {
                            "portfolio": "read"
                          },
                          {
                            "support": "read"
                          }
                        ],
                        "type": "string"
                      },
                      "type": "array"
                    },
                    "type": "object"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTenantLink"
                }
              }
            },
            "description": "Owner consent recorded and link activated"
          },
          "400": {
            "description": "Unsupported grants"
          },
          "403": {
            "description": "Authenticated tenant owner consent required"
          },
          "404": {
            "description": "Link request not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve an organization link as the tenant owner and grant scoped access",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/organization-links/{linkID}/reject": {
      "post": {
        "description": "Declines a pending request from another organization to administer this tenant; the link is marked removed, no access is granted, and the decision is audited. Only a staff member with the owner role in the linked tenant may reject; others get 403. Returns 409 when the link is no longer pending and 404 when it does not exist.",
        "operationId": "rejectOrganizationAccountLink",
        "parameters": [
          {
            "description": "ID of the pending organization link request for the caller's tenant.",
            "in": "path",
            "name": "linkID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTenantLink"
                }
              }
            },
            "description": "Consent request rejected"
          },
          "403": {
            "description": "Authenticated tenant owner required"
          },
          "404": {
            "description": "Link request not found"
          },
          "409": {
            "description": "Link request is no longer pending"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a pending organization link request as the tenant owner",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}": {
      "get": {
        "description": "Returns the organization record, including its status and billing mode, to staff signed in to that organization. The caller must be acting in an organization context whose ID matches the path and must hold the organization:accounts:read scope; otherwise the call returns 403.",
        "operationId": "getOrganizationProfile",
        "parameters": [
          {
            "description": "ID of the organization; it must equal the organization the caller is currently acting in, or the request is refused.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            },
            "description": "Organization profile"
          },
          "403": {
            "description": "Organization account read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the authenticated organization profile and billing mode",
        "x-roles": [
          "account_admin",
          "account_analyst",
          "account_finance",
          "account_owner",
          "account_support"
        ],
        "x-scopes": [
          "organization:accounts:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/accounts": {
      "get": {
        "description": "Returns every link record the organization has (pending consent, active, removal pending, removed), each with the account's name and slug, followed by synthetic entries with state owned and an ID of the form owned:<tenant ID> for accounts the organization owns outright. Only organization owners and admins with the organization:accounts:read scope may call it. A closed or unknown organization returns 404. The list is not paginated.",
        "operationId": "getOrganizationAccountLinks",
        "parameters": [
          {
            "description": "ID of the organization whose account links are listed; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/OrganizationTenantLink"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Owned accounts plus linked accounts and pending consent requests visible to organization members"
          },
          "403": {
            "description": "Organization account read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List owned, linked, and pending accounts in the active organization",
        "x-roles": [
          "account_admin",
          "account_analyst",
          "account_finance",
          "account_owner",
          "account_support"
        ],
        "x-scopes": [
          "organization:accounts:read"
        ]
      },
      "post": {
        "description": "Creates a link in the pending_consent state with no grants and returns it with 202 Accepted. The link only takes effect after an owner of that account approves it and chooses the grants. The account must be active and not already owned by this organization (400 otherwise), and a 409 is returned if the account already has an active or pending link. Requires the organization:accounts:manage scope in the matching organization context and records an audit entry.",
        "operationId": "requestOrganizationAccountLink",
        "parameters": [
          {
            "description": "ID of the organization asking to link the account; it must equal the caller's active organization context and the organization must be active.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "tenant_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "tenant_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTenantLink"
                }
              }
            },
            "description": "Link request pending consent from the account owner"
          },
          "400": {
            "description": "Invalid tenant or organization link request"
          },
          "403": {
            "description": "Organization account management scope required"
          },
          "409": {
            "description": "Tenant already has an active administrative organization"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request to add an account, pending its owner's consent",
        "x-roles": [
          "account_admin",
          "account_owner"
        ],
        "x-scopes": [
          "organization:accounts:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/accounts/{tenantID}": {
      "delete": {
        "description": "Moves an active link to removal_pending and sets notice_period_until to now plus the deployment's configured notice period. Access ends when a scheduled sweep runs after that date, and the account keeps its data and ownership. Either an organization owner with organization:accounts:manage or an owner of the account itself may call it. If the organization pays for the account, direct billing is scheduled for the deadline and the account's owners are notified. Returns 202 with the updated link, 404 when there is no active link between the two, and 400 when the link is not active.",
        "operationId": "requestOrganizationAccountRemoval",
        "parameters": [
          {
            "description": "ID of the organization the account is linked to.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the linked account (utility workspace) to remove from the organization.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTenantLink"
                }
              }
            },
            "description": "Account link removal scheduled; account ownership and data are retained"
          },
          "403": {
            "description": "Organization owner or linked account owner required"
          },
          "404": {
            "description": "Active organization account link not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule removal of an account after the configured notice period",
        "x-roles": [],
        "x-scopes": [
          "business:organization:read",
          "organization:accounts:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/billing": {
      "put": {
        "description": "Only an organization owner can change billing mode. The change is audited.",
        "operationId": "setOrganizationBillingMode",
        "parameters": [
          {
            "description": "ID of the organization whose billing mode is changed; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "billing_mode": {
                    "enum": [
                      "account",
                      "organization"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "billing_mode"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            },
            "description": "Updated organization profile"
          },
          "400": {
            "description": "Invalid billing mode"
          },
          "403": {
            "description": "Organization owner with billing management scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Choose account-level or organization-level subscription ownership",
        "x-roles": [
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/close": {
      "post": {
        "description": "Marks an active organization as closed, detaches all organization memberships and records an audit entry, then returns the closed organization. Only an organization owner with the organization:accounts:manage scope may close it, and the body must name successor_member_id: another active owner, not the caller. A missing or invalid successor returns 409. The organization must be active (404 otherwise), and the call returns 409 while the organization still owns accounts that need to be transferred first.",
        "operationId": "closeOrganization",
        "parameters": [
          {
            "description": "ID of the organization to close; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "successor_member_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "successor_member_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Organization closed; linked accounts were detached and retained"
          },
          "403": {
            "description": "Active organization owner with account management scope required"
          },
          "409": {
            "description": "A successor owner is required or owned accounts must be transferred first"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Close an organization and detach its linked accounts",
        "x-roles": [
          "account_admin",
          "account_owner"
        ],
        "x-scopes": [
          "organization:accounts:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/plans": {
      "get": {
        "description": "Returns the plans an organization can subscribe to, wrapped in a data array. Requires the organization:billing:read scope in the matching organization context (403 otherwise). The list is not paginated.",
        "operationId": "listOrganizationSubscriptionPlans",
        "parameters": [
          {
            "description": "ID of the organization browsing plans; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PlanLang"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/Plan"
                      },
                      "type": "array"
                    },
                    "offers": {
                      "description": "Offers listed beside the plans; the custom offer (code custom) when a published plan has a connection limit.",
                      "items": {
                        "$ref": "#/components/schemas/PlanOffer"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Available platform plans, name, tagline and capability labels in the caller's language"
          },
          "403": {
            "description": "Organization billing read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List plans available to an organization payer",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/portfolio": {
      "get": {
        "description": "Returns only aggregate counts: the total number of accounts, plus counts by account status and by workspace state. No account details are included. Owners see the accounts the organization owns. For linked accounts in the active or removal_pending state, a caller's role is counted only when the account owner granted that role portfolio:read. Requires the organization:portfolio:read scope, and a closed organization returns 404.",
        "operationId": "getOrganizationPortfolio",
        "parameters": [
          {
            "description": "ID of the organization whose portfolio is summarised; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationPortfolio"
                }
              }
            },
            "description": "Aggregate counts only; linked accounts require explicit portfolio:read consent"
          },
          "403": {
            "description": "Organization portfolio scope required"
          },
          "404": {
            "description": "Active organization not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read aggregate account lifecycle counts permitted by organization grants",
        "x-roles": [
          "account_analyst",
          "account_owner"
        ],
        "x-scopes": [
          "organization:portfolio:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription": {
      "get": {
        "description": "Returns the organization's own subscription: plan, status (for example trialing or active), current period and trial end. Requires the organization:billing:read scope in the matching organization context. Returns 404 when the organization has no subscription.",
        "operationId": "getOrganizationSubscription",
        "parameters": [
          {
            "description": "ID of the organization; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationSubscription"
                }
              }
            },
            "description": "Organization subscription and billing period"
          },
          "403": {
            "description": "Organization billing read scope required"
          },
          "404": {
            "description": "Organization subscription not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the organization-owned SaaS subscription",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      },
      "post": {
        "description": "Requires organization billing mode and the organization owner; the subscription covers administered member accounts.",
        "operationId": "createOrganizationSubscription",
        "parameters": [
          {
            "description": "ID of the organization to subscribe; it must equal the caller's active organization context, and the caller must be an owner with organization:billing:manage.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "plan_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "plan_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationSubscription"
                }
              }
            },
            "description": "Organization subscription created"
          },
          "403": {
            "description": "Organization owner with billing management scope required"
          },
          "409": {
            "description": "Organization billing mode is not organization-level or a subscription already exists"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Attach a platform plan to an organization",
        "x-roles": [
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription/invoices": {
      "get": {
        "description": "Returns one cursor-paginated page of the invoices the platform issued to the organization for its subscription. Pass limit and after to page, and status to filter. Requires the organization:billing:read scope in the matching organization context.",
        "operationId": "listOrganizationSubscriptionInvoices",
        "parameters": [
          {
            "description": "ID of the organization whose subscription invoices are listed; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformInvoicePage"
                }
              }
            },
            "description": "Organization invoices and account-level plan lines"
          },
          "403": {
            "description": "Organization billing read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List organization subscription invoices itemized by account",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription/invoices/{id}": {
      "get": {
        "description": "Returns one platform invoice issued to the organization. An invoice that belongs to another organization or to a single account returns 404. Requires the organization:billing:read scope in the matching organization context.",
        "operationId": "getOrganizationSubscriptionInvoice",
        "parameters": [
          {
            "description": "ID of the organization that owns the invoice; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the platform invoice.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformInvoice"
                }
              }
            },
            "description": "Organization subscription invoice"
          },
          "403": {
            "description": "Organization billing read scope required"
          },
          "404": {
            "description": "Invoice not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one invoice owned by the organization",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription/invoices/{id}/payment-proofs": {
      "post": {
        "description": "Accepts a multipart/form-data upload with a file field (PDF, JPEG or PNG, up to 5 MB by default) and the form fields amount_cents, method, reference (up to 128 characters), paid_on (YYYY-MM-DD, not in the future) and an optional note (up to 500 characters). It stores the proof as pending for platform staff to review and returns 201. Only an organization owner with organization:billing:manage may submit. The invoice must be open (409 otherwise), the method must be one of the enabled platform payment methods, and an open proof with the same method and reference returns 409.",
        "operationId": "submitOrganizationSubscriptionPaymentProof",
        "parameters": [
          {
            "description": "ID of the organization paying the invoice; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the open platform invoice that the proof pays.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "amount_cents": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "file": {
                    "format": "binary",
                    "type": "string"
                  },
                  "method": {
                    "description": "A method code from the invoice's payment_methods: the platform's configured payment methods.",
                    "type": "string"
                  },
                  "note": {
                    "maxLength": 500,
                    "type": "string"
                  },
                  "paid_on": {
                    "format": "date",
                    "type": "string"
                  },
                  "reference": {
                    "maxLength": 128,
                    "type": "string"
                  }
                },
                "required": [
                  "amount_cents",
                  "method",
                  "reference",
                  "paid_on",
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created; the proof waits for platform review"
          },
          "403": {
            "description": "Organization owner with billing management scope required"
          },
          "409": {
            "description": "The invoice is not open",
            "or the reference was already sent": null
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit payment evidence for an organization invoice",
        "x-roles": [
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:manage",
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription/payment-instructions": {
      "get": {
        "description": "Returns the payment instructions the platform operator has configured, such as bank or mobile money details, wrapped in a data array that is empty when none are set. Requires the organization:billing:read scope in the matching organization context.",
        "operationId": "getOrganizationSubscriptionPaymentInstructions",
        "parameters": [
          {
            "description": "ID of the organization; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Organization payment instructions"
          },
          "403": {
            "description": "Organization billing read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Payment instructions for an organization payer",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription/payment-proofs": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the proofs of payment the organization has sent for its subscription invoices, with each proof's review status. Requires the organization:billing:read scope in the matching organization context.",
        "operationId": "listOrganizationSubscriptionPaymentProofs",
        "parameters": [
          {
            "description": "ID of the organization whose proofs are listed; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional platform invoice ID; when set, only proofs sent for that invoice are returned.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional review status filter: pending, approved or rejected.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "approved",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Organization payment proofs"
          },
          "403": {
            "description": "Organization billing read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List an organization's proofs of payment to the platform",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/subscription/payment-proofs/{id}/file": {
      "get": {
        "description": "Streams the stored proof file inline with its original content type and file name, using no-store caching and a sandboxing Content-Security-Policy. A proof that belongs to another organization, or whose file is no longer in storage, returns 404. Requires the organization:billing:read scope in the matching organization context.",
        "operationId": "getOrganizationSubscriptionPaymentProofFile",
        "parameters": [
          {
            "description": "ID of the organization that sent the proof; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the subscription payment proof.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "JPEG or PNG": null,
            "description": "The stored PDF"
          },
          "403": {
            "description": "Organization billing read scope required"
          },
          "404": {
            "description": "Proof not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download an organization's payment proof",
        "x-roles": [
          "account_finance",
          "account_owner"
        ],
        "x-scopes": [
          "organization:billing:read"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/templates": {
      "get": {
        "description": "Returns the organization's setting templates, both draft and published, without pagination. Every caller needs the organization:accounts:read scope in the matching organization context. Listing drafts also requires an owner or admin with organization:accounts:manage, so other members must pass published_only=true. A closed organization returns 404.",
        "operationId": "listOrganizationTemplates",
        "parameters": [
          {
            "description": "ID of the organization whose templates are listed; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Set to true to return only published templates; any other value or no value includes drafts, which only owners and admins may see.",
            "in": "query",
            "name": "published_only",
            "required": false,
            "schema": {
              "default": false,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/OrganizationTemplate"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Organization templates visible in the active organization context"
          },
          "403": {
            "description": "Organization settings scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List organization setting templates",
        "x-roles": [
          "account_admin",
          "account_owner"
        ],
        "x-scopes": [
          "organization:accounts:manage",
          "organization:accounts:read"
        ]
      },
      "post": {
        "description": "Saves a new template in the draft state with a generated ID and returns it with 201. The body needs a key, version (up to 40 characters), name (up to 160 characters), an optional description (up to 1000 characters) and a non-empty settings map. Allowed settings keys are tariffs, billing_schedules, notification_templates, automation_rules, connector_definitions, roles, custom_fields, document_layouts, branding and domains. Each value must be valid JSON up to 256 KB and must not contain secrets; otherwise the call returns 400. Requires an owner or admin with organization:accounts:manage, and the organization must be active.",
        "operationId": "createOrganizationTemplate",
        "parameters": [
          {
            "description": "ID of the organization that will own the template; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/OrganizationTemplateDraft"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTemplate"
                }
              }
            },
            "description": "Draft created"
          },
          "400": {
            "description": "Invalid or secret-bearing settings snapshot"
          },
          "403": {
            "description": "Organization owner or admin required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an unpublished organization setting template draft",
        "x-roles": [
          "account_admin",
          "account_owner"
        ],
        "x-scopes": [
          "organization:accounts:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/templates/{templateID}/adoptions": {
      "post": {
        "description": "Creates a pending adoption of the template's current version for the account named by tenant_id in the body and returns it with 202. An owner of that account must then accept it. The template must be published, and a draft returns 409. Requires an owner or admin with organization:accounts:manage in the matching organization context, and an audit entry is recorded.",
        "operationId": "requestOrganizationTemplateAdoption",
        "parameters": [
          {
            "description": "ID of the organization that owns the template; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the published organization template to offer.",
            "in": "path",
            "name": "templateID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "tenant_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "tenant_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTemplateAdoption"
                }
              }
            },
            "description": "Adoption awaits explicit account-owner acceptance"
          },
          "403": {
            "description": "Organization owner or admin required"
          },
          "404": {
            "description": "Published template or member account not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Ask a member account owner to accept a template",
        "x-roles": [
          "account_admin",
          "account_owner"
        ],
        "x-scopes": [
          "organization:accounts:manage"
        ]
      }
    },
    "$BUSINESS_API/organizations/{organizationID}/templates/{templateID}/publish": {
      "post": {
        "description": "Checks a draft template against the settings it would apply, then marks it published with the publisher and time, records an audit entry and returns it. Published templates can be offered to member accounts. Only an organization owner with organization:accounts:manage may publish. A template that is not a draft returns 409, and an unknown template or closed organization returns 404.",
        "operationId": "publishOrganizationTemplate",
        "parameters": [
          {
            "description": "ID of the organization that owns the template; it must equal the caller's active organization context.",
            "in": "path",
            "name": "organizationID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the draft template to publish.",
            "in": "path",
            "name": "templateID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTemplate"
                }
              }
            },
            "description": "Published version"
          },
          "403": {
            "description": "Organization owner required to publish"
          },
          "409": {
            "description": "Template is already published"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Publish an immutable organization template version",
        "x-roles": [
          "account_admin",
          "account_owner"
        ],
        "x-scopes": [
          "organization:accounts:manage"
        ]
      }
    },
    "$BUSINESS_API/outbox/events": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the tenant's outbox records, newest first, ordered by occurrence time. Each record includes its type, aggregate, payload, publish time, retry count and last error. Use it to see which events were delivered and which are stuck. Requires the events:read permission in the tenant.",
        "operationId": "listDomainEvents",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Optional delivery state filter: published (delivered), pending (not yet delivered and never retried) or failed (not delivered after at least one retry); any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "published",
                "failed"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Outbox events"
          },
          "403": {
            "description": "Missing events:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the tenant's outbox events and their delivery state",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "events:read"
        ]
      }
    },
    "$BUSINESS_API/outbox/transitions": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the tenant's status transition log, newest first. Each entry has the from and to status, the actor with a resolved display name where available, the reason and the time. Requires the events:read permission in the tenant.",
        "operationId": "listDomainTransitions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Optional aggregate type (for example payment or collection_case) to return only transitions of that kind of record; matched exactly.",
            "in": "query",
            "name": "aggregate_type",
            "schema": {
              "enum": [
                "invoice",
                "payment",
                "reading",
                "connection",
                "collection_case",
                "work_order",
                "platform_invoice"
              ],
              "type": "string"
            }
          },
          {
            "description": "Optional ID of one record to return only its transitions; combine with aggregate_type to target one record unambiguously.",
            "in": "query",
            "name": "aggregate_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Transitions. Each has actor_id, actor_type and actor_name, the actor's display label."
          },
          "403": {
            "description": "Missing events:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Audit log of status transitions for an aggregate",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "events:read"
        ]
      }
    },
    "$BUSINESS_API/overview": {
      "get": {
        "description": "Requires business:overview:read. Each returned data group is filtered by its own domain read scope; overview access alone does not grant access to billing, payment, reading, consumption, operations, or support totals.",
        "operationId": "getBusinessOverview",
        "parameters": [
          {
            "description": "Month as YYYY-MM; defaults to the current month",
            "in": "query",
            "name": "period",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessOverview"
                }
              }
            },
            "description": "Overview"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Billed, collected, volume, readings, receivables ageing, collection and read rate, open work, series",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:overview:read"
        ]
      }
    },
    "$BUSINESS_API/payment-allocations": {
      "get": {
        "description": "Each allocation carries the target invoice's number and current status (invoice_status), read in one batched lookup per response, so clients can filter allocations by invoice state without paging the invoice list.",
        "operationId": "listPaymentAllocations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Optional payment ID; when set, only the allocations of that payment are returned.",
            "in": "query",
            "name": "payment_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional invoice ID; when set, only the allocations applied to that invoice are returned.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/PaymentAllocation"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data",
                    "has_more"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Payment allocations in the authenticated utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List allocations of confirmed payments to invoices",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payment-connectors": {
      "get": {
        "description": "Returns the payment connectors registered for the tenant, sorted by ID, in a response with connectors, has_more and next_cursor. Paging uses limit and an after cursor, and a malformed cursor returns 400. Requires the payments:read permission.",
        "operationId": "listPaymentConnectors",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "connectors": {
                      "items": {
                        "properties": {
                          "agent_version": {
                            "type": "string"
                          },
                          "currency": {
                            "type": "string"
                          },
                          "hostname": {
                            "type": "string"
                          },
                          "id": {
                            "pattern": "^pcn_[A-Za-z0-9]+$",
                            "type": "string"
                          },
                          "last_heartbeat_at": {
                            "format": "date-time",
                            "type": [
                              "string",
                              "null"
                            ]
                          },
                          "mode": {
                            "enum": [
                              "pull",
                              "push"
                            ],
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "operational_methods": {
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "status": {
                            "enum": [
                              "online",
                              "busy",
                              "offline",
                              "decommissioned",
                              "revoked"
                            ],
                            "type": "string"
                          },
                          "supported_methods": {
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "tenant_id": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "tenant_id",
                          "id",
                          "name",
                          "supported_methods",
                          "operational_methods",
                          "currency",
                          "status"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "connectors",
                    "has_more"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Connectors"
          },
          "403": {
            "description": "Missing payments:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the tenant's payment connectors with their mode and operational_methods",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payment-connectors/enrollment-tokens": {
      "post": {
        "description": "Creates a one-time-visible enrollment token (prefixed enr_) that a payment connector exchanges to register itself with this tenant, and returns it with 201. The raw token is in the response only; just its hash is stored. The body takes an optional name (defaults to \"default\"), max_uses (0 means unlimited) and valid_duration_seconds (defaults to 30 days). Requires the payments:write permission.",
        "operationId": "createPaymentEnrollmentToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "max_uses": {
                    "type": "integer"
                  },
                  "name": {
                    "type": "string"
                  },
                  "valid_duration_seconds": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "created_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "expires_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "id": {
                      "pattern": "^etk_[A-Za-z0-9]+$",
                      "type": "string"
                    },
                    "max_uses": {
                      "type": "integer"
                    },
                    "name": {
                      "type": "string"
                    },
                    "tenant_id": {
                      "type": "string"
                    },
                    "token": {
                      "description": "Returned once; store securely before closing the dialog",
                      "type": "string"
                    },
                    "uses_count": {
                      "type": "integer"
                    }
                  },
                  "required": [
                    "tenant_id",
                    "id",
                    "token",
                    "name",
                    "max_uses",
                    "uses_count",
                    "expires_at",
                    "created_at"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Token issued"
          },
          "400": {
            "description": "Invalid request body or enrollment parameters"
          },
          "403": {
            "description": "Missing payments:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a payment connector enrollment token for the caller's tenant, returned once",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payment-connectors/{id}": {
      "delete": {
        "description": "Removes the connector registration from the tenant, so it can no longer pick up payment jobs for this tenant, and returns 204. The delete is idempotent: an unknown ID also returns 204. Requires the payments:write permission.",
        "operationId": "deletePaymentConnector",
        "parameters": [
          {
            "description": "ID of the registered payment connector (prefixed pcn_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          },
          "403": {
            "description": "Missing payments:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a payment connector",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payment-methods": {
      "get": {
        "description": "Derived from the utility's configured collection channels (mobile money, bank transfer, the cash counter) and from the methods its payment connectors declare; nothing is listed that the utility did not configure. Clients word each method from its code. Readable with payments:read, payments:write or business:prepaid:vend.",
        "operationId": "getStaffPaymentMethods",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "properties": {
                          "available": {
                            "type": "boolean"
                          },
                          "channel": {
                            "description": "Collection channel type the method comes from.",
                            "type": "string"
                          },
                          "code": {
                            "description": "Method code sent when recording the payment.",
                            "type": "string"
                          },
                          "connector": {
                            "description": "Whether a live connector of the utility can complete the method now, or only lists it. Absent when no connector offers it.",
                            "enum": [
                              "operational",
                              "declared"
                            ],
                            "type": "string"
                          },
                          "counter": {
                            "description": "Taken at a counter (cash or a card terminal); the cash desk offers these.",
                            "type": "boolean"
                          },
                          "label": {
                            "description": "The utility's own name for the channel (the operator's label, or a neutral sample label in a test account), when a channel of this type has one; never derived from the code.",
                            "type": "string"
                          },
                          "requires_phone": {
                            "type": "boolean"
                          },
                          "requires_reference": {
                            "type": "boolean"
                          },
                          "requires_shift": {
                            "description": "Cash taken at a counter; recorded from the cash desk during an open shift.",
                            "type": "boolean"
                          },
                          "source": {
                            "enum": [
                              "channel",
                              "connector"
                            ],
                            "type": "string"
                          },
                          "unavailable_reason": {
                            "enum": [
                              "channel_disabled",
                              "connector_unavailable",
                              "payments_inactive"
                            ],
                            "type": "string"
                          }
                        },
                        "required": [
                          "code",
                          "source",
                          "requires_reference",
                          "requires_phone",
                          "requires_shift",
                          "available"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    },
                    "payments_active": {
                      "description": "False while the payments capability is not active; every method is then unavailable.",
                      "type": "boolean"
                    }
                  },
                  "required": [
                    "data",
                    "payments_active"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Methods for the authenticated utility tenant, in configuration order"
          },
          "401": {
            "description": "Authenticated utility tenant context required"
          },
          "403": {
            "description": "Requires payments:read",
            "payments": "write or business:prepaid:vend"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the payment methods staff can record for this utility",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:prepaid:vend"
        ]
      }
    },
    "$BUSINESS_API/payment-plans": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the tenant's debt payment plans. The account_id, case_id and status (active, completed, defaulted or cancelled) query parameters narrow the list. Requires read access to collections.",
        "operationId": "listPaymentPlans",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Payment plans"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List customer payment installment plans",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      },
      "post": {
        "description": "Turns a collection case's total debt into a payment plan and returns it with 201. Simple interest from interest_basis_points is added and the total is split into equal installments (default 3), with the rounding remainder on the last one. Installments fall due every interval_months (default 1) from first_due_date (default one month from now). Any interest is charged to the account's receivables, a payment plan created event is emitted, and the case moves to payment_plan_active. Requires the collections:write permission. Returns 404 for an unknown case and 400 for negative interest.",
        "operationId": "createPaymentPlan",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentPlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Payment plan created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Agree on a payment plan",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/payment-plans/{id}": {
      "get": {
        "description": "Returns a payment plan with its installments, including each installment's due date, amount and status. Requires read access to collections in the tenant, and returns 404 when the plan does not exist.",
        "operationId": "getPaymentPlan",
        "parameters": [
          {
            "description": "ID of the payment plan (prefixed pln_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentPlan"
                }
              }
            },
            "description": "Payment plan details"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Payment plan not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a payment installment plan with its installments",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "collections:read"
        ]
      }
    },
    "$BUSINESS_API/payment-plans/{id}/default": {
      "post": {
        "description": "Changes an active plan's status to defaulted and returns it, which makes the account eligible for cutoff again. Only an active plan can default; any other status returns 409. Requires the collections:write permission.",
        "operationId": "defaultPaymentPlan",
        "parameters": [
          {
            "description": "ID of the active payment plan to mark as defaulted.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentPlan"
                }
              }
            },
            "description": "Payment plan declared in default"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Payment plan not found in the authenticated tenant"
          },
          "409": {
            "description": "Payment plan cannot be defaulted in its current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Declare a payment plan in default",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "collections:write"
        ]
      }
    },
    "$BUSINESS_API/payment-proofs": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the proofs of payment that customers sent to the tenant or staff attached to payments, for review. Requires the payments:read permission.",
        "operationId": "listPaymentProofs",
        "parameters": [
          {
            "description": "Optional review status filter: pending, approved or rejected.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "approved",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "description": "Optional account ID; only proofs for that customer account are returned.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional invoice ID; only proofs that reference that invoice are returned.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional payment ID; only proofs linked to that recorded payment are returned.",
            "in": "query",
            "name": "payment_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List proofs of payment, such as those waiting for review",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payment-proofs/{id}": {
      "get": {
        "description": "Returns a proof's details: account, amount, method, reference, payment date, file metadata, review status and, once approved, the payment it produced. Requires the payments:read permission, and returns 404 when the proof is not in the tenant.",
        "operationId": "getPaymentProof",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a proof of payment",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payment-proofs/{id}/approve": {
      "post": {
        "description": "Records the payment the proof describes and marks the proof approved. It returns both the proof and the payment result. The optional body can correct amount_minor or reference and add a review note (up to 500 characters). The payment is recorded with an idempotency key derived from the proof, so a retry never records it twice. A proof that was already reviewed returns 409. Requires the payments:write permission.",
        "operationId": "approvePaymentProof",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount_minor": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "note": {
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "The approved proof and the recorded payment"
          },
          "409": {
            "description": "The proof was already reviewed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve a proof: records the payment, optionally with the amount or reference the bank shows",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payment-proofs/{id}/file": {
      "get": {
        "description": "Streams the uploaded proof file (PDF, JPEG or PNG) inline with its original file name, using no-store caching and a sandboxing Content-Security-Policy. Requires the payments:read permission. Returns 404 when the proof is not in the tenant or its file is no longer in storage.",
        "operationId": "getPaymentProofFile",
        "responses": {
          "200": {
            "description": "The stored PDF, JPEG or PNG"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the proof file",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payment-proofs/{id}/reject": {
      "post": {
        "description": "Marks a pending proof as rejected without recording any payment and returns the proof. The body must include a reason (up to 500 characters), which is shown to the payer. A proof that was already reviewed returns 409. Requires the payments:write permission.",
        "operationId": "rejectPaymentProof",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "maxLength": 500,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a proof with a reason the payer will read",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payments": {
      "get": {
        "description": "Does not initiate or process payment instruments.",
        "operationId": "listRecordedPayments",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordedPaymentPage"
                }
              }
            },
            "description": "Recorded payments in the authenticated utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List recorded payment confirmations",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      },
      "post": {
        "description": "The method must be one the utility configured and has enabled (see GET $BUSINESS_API/payment-methods); any other is refused with 400 payment.method_not_configured.",
        "operationId": "recordPayment",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "account_id": {
                    "type": "string"
                  },
                  "amount_minor": {
                    "type": "integer"
                  },
                  "counter_id": {
                    "type": "string"
                  },
                  "currency": {
                    "type": "string"
                  },
                  "customer_id": {
                    "type": "string"
                  },
                  "idempotency_key": {
                    "type": "string"
                  },
                  "method": {
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  },
                  "shift_id": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a payment and allocate it FIFO across unpaid invoices by due date; the remainder is held as unallocated credit",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payments/confirm": {
      "post": {
        "description": "Records a payment confirmed outside the platform (counter, transfer, mobile money) and applies it to the invoice named in invoice_id. Repeating the same idempotency_key returns the original payment. The method must be one the utility configured and has enabled; any other is refused with payment.method_not_configured.",
        "operationId": "confirmPayment",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "account_id": {
                    "type": "string"
                  },
                  "amount": {
                    "description": "Amount in minor units",
                    "type": "integer"
                  },
                  "confirmed_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "currency": {
                    "type": "string"
                  },
                  "customer_id": {
                    "type": "string"
                  },
                  "idempotency_key": {
                    "type": "string"
                  },
                  "invoice_id": {
                    "type": "string"
                  },
                  "method": {
                    "type": "string"
                  },
                  "payment_session_id": {
                    "type": "string"
                  },
                  "provider_reference": {
                    "type": "string"
                  }
                },
                "required": [
                  "account_id",
                  "amount",
                  "currency",
                  "method",
                  "idempotency_key"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The payment already recorded with this idempotency key"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a payment against a specific invoice",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payments/{id}": {
      "get": {
        "description": "Returns one payment recorded in the caller's tenant: amount in minor units, currency, method, the reference the payer or connector supplied, receipt number, status (posted, reconciled or reversed), payment time, the cashier shift and counter when it was taken at a counter, and reversal details when reversed. Account and customer references carry the holder's display name. Requires payments:read; an id that does not exist in the caller's tenant returns 404.",
        "operationId": "getPayment",
        "parameters": [
          {
            "description": "Identifier of the payment, matched within the caller's tenant only.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RecordedPayment"
                }
              }
            },
            "description": "Payment"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing payments:read scope"
          },
          "404": {
            "description": "Payment not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one recorded payment",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payments/{id}/metadata": {
      "get": {
        "description": "Returns the custom key/value metadata stored on a payment, as a metadata map that is empty when nothing is set. The payment must exist in the tenant (404 otherwise), and the caller needs the business:metadata:read permission.",
        "operationId": "getBusinessPaymentMetadata",
        "parameters": [
          {
            "description": "ID of the payment, up to 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a payment",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the metadata map in the body into the payment's existing metadata and returns the full result. Keys not in the body are left alone, and a key sent with an empty string value is removed. At most 50 keys may be sent at once or stored in total. Keys can be up to 40 characters, with no square brackets or control characters, and values up to 500 characters; invalid fields return 400 with one entry per problem. Requires the business:metadata:write permission.",
        "operationId": "putBusinessPaymentMetadata",
        "parameters": [
          {
            "description": "ID of the payment, up to 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/payments/{id}/proof": {
      "post": {
        "description": "Stores a staff-supplied file as evidence for a payment that has already been recorded, such as a slip a customer handed in at the office, and returns it with 201. Send it as multipart/form-data with a file field (PDF, JPEG or PNG, up to 5 MB by default). The proof copies the payment's account, amount, method and reference and is approved at once, because the payment already exists. Requires the payments:write permission, and an unknown payment returns 404.",
        "operationId": "attachPaymentProof",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Attach a proof file to a recorded payment (multipart: file)",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:read",
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/payments/{id}/receipt/thermal": {
      "get": {
        "description": "Returns the payment's receipt as ESC/POS printer commands for an 80 mm thermal printer. The response has content type application/vnd.escpos and is sent as an attachment named receipt-<id>.bin. The receipt uses the tenant's receipt profile and lists the invoices the payment was allocated to, plus any unallocated credit. Requires the payments:read permission.",
        "operationId": "getThermalReceipt",
        "parameters": [
          {
            "description": "ID of the payment whose receipt is printed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "80 mm ESC/POS thermal receipt (application/vnd.escpos)",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/payments/{id}/reverse": {
      "post": {
        "description": "Reverses a recorded payment, which needs a non-empty reason. Each invoice application is undone, the payment's allocations are reversed, a transition to reversed is recorded, and payment.reversed and allocation reversed events are emitted. When the payment came through a provider checkout, one refund job is queued for the connector. The call is idempotent: reversing an already reversed payment returns it unchanged, and a retry after a partial failure finishes the job. Requires the payments:write permission. Returns 409 when reversal is not configured and 503 when the refund cannot be queued.",
        "operationId": "reversePayment",
        "parameters": [
          {
            "description": "ID of the payment to reverse.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reverse a payment: restore invoice balances, undo allocations and mirror journal entries",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/plans": {
      "get": {
        "description": "Returns the published plans plus the tenant's own plan, wrapped in a data array, with the offers beside them (the custom offer past the largest plan). Name, tagline, capability labels and offer text are in the caller's language: lang, else Accept-Language, else the plan's default text. Clients show these and build no plan text of their own. Requires the business:subscription:read permission. The list is not paginated.",
        "operationId": "listBusinessPlans",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PlanLang"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/Plan"
                      },
                      "type": "array"
                    },
                    "offers": {
                      "description": "Offers listed beside the plans; the custom offer (code custom) when a published plan has a connection limit.",
                      "items": {
                        "$ref": "#/components/schemas/PlanOffer"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Plans"
          },
          "403": {
            "description": "Missing business:subscription:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the plans a utility may choose from",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/portfolio-overview": {
      "get": {
        "description": "Builds the business overview for one month for the caller's own account and for every descendant account in its organization tree where the caller holds business:overview:read directly or through an inherited membership; owning the parent alone does not open the children. Each account is returned with its own overview, and billed, collected, volume and reading totals and daily series are summed across them. As in the single-account overview, each data group of each account is shown only when the caller holds that domain's read scope on that account (invoices:read, payments:read, collections:read, business:readings:read, business:consumptions:read, operations:read, support:read). Requires business:overview:read on the caller's tenant. A period that is not YYYY-MM returns 400, and accounts that report in different currencies return 409.",
        "operationId": "getPortfolioOverview",
        "parameters": [
          {
            "description": "Month to report as YYYY-MM, in UTC; defaults to the current month.",
            "in": "query",
            "name": "period",
            "schema": {
              "example": "2026-10",
              "pattern": "^\\d{4}-\\d{2}$",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessPortfolioOverview"
                }
              }
            },
            "description": "Portfolio overview"
          },
          "400": {
            "description": "Invalid period (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing business:overview:read scope"
          },
          "404": {
            "description": "Reporting is not available on this installation"
          },
          "409": {
            "description": "Accounts in the portfolio use different currencies"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Overview totals across the caller's account and its sub-accounts",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:overview:read"
        ]
      }
    },
    "$BUSINESS_API/prepaid/meters": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the tenant's meters enrolled for prepaid vending, with each one's linked account, tariff, status and wallet balance. Requires the business:prepaid:read permission.",
        "operationId": "listPrepaidMeters",
        "parameters": [
          {
            "description": "Optional enrollment status filter: active or suspended.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "active",
                "suspended"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidMeterPage"
                }
              }
            },
            "description": "Prepaid meters in the authenticated utility tenant"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List prepaid meters",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      },
      "post": {
        "description": "Enrolls an existing meter for prepaid vending and returns the enrollment with status active and 201. The body needs meter_id and accepts an optional tariff_id and vending_key_ref. The meter must exist and be linked to an account (400 otherwise), and a meter that is already prepaid returns 409. Requires the business:prepaid:manage permission and records an audit entry.",
        "operationId": "enrollPrepaidMeter",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnrollPrepaidMeterRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidMeter"
                }
              }
            },
            "description": "Meter enrolled as prepaid"
          },
          "400": {
            "description": "Invalid meter enrollment request"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:manage scope"
          },
          "404": {
            "description": "Meter not found in the authenticated tenant"
          },
          "409": {
            "description": "Meter already enrolled as prepaid"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Flag a meter as prepaid",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:prepaid:manage"
        ]
      }
    },
    "$BUSINESS_API/prepaid/meters/{id}": {
      "get": {
        "description": "Returns one prepaid enrollment with its meter serial, account, customer, tariff, status and current wallet balance. Requires the business:prepaid:read permission, and returns 404 when the enrollment does not exist.",
        "operationId": "getPrepaidMeter",
        "parameters": [
          {
            "description": "ID of the prepaid meter enrollment (prefixed ppm_), not the underlying meter ID.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^ppm_",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidMeter"
                }
              }
            },
            "description": "Prepaid meter in the authenticated utility tenant"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          },
          "404": {
            "description": "Prepaid meter not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a prepaid meter with its wallet balance",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      }
    },
    "$BUSINESS_API/prepaid/meters/{id}/quote": {
      "post": {
        "description": "Converts the amount_cents in the body into the largest whole number of litres it buys under the meter's tariff, without taking payment or issuing a token. The quote accounts for volume already vended this month, and a first purchase in the month includes the period's fixed charge. It returns the litres, the net, sanitation and tax split, and the remainder. A non-positive amount, or one too small to buy any water, returns 400. Requires the business:prepaid:read permission.",
        "operationId": "quotePrepaidVend",
        "parameters": [
          {
            "description": "ID of the prepaid meter enrollment to price the purchase for.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^ppm_",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/QuotePrepaidVendRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidQuote"
                }
              }
            },
            "description": "Amount converted to water volume"
          },
          "400": {
            "description": "Invalid or too-small vend amount"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          },
          "404": {
            "description": "Prepaid meter or tariff not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Convert an amount to water volume with the tariff",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      }
    },
    "$BUSINESS_API/prepaid/meters/{id}/status": {
      "post": {
        "description": "Sets the enrollment status to the status in the body and returns the updated enrollment. Only active and suspended are accepted (400 otherwise), and a suspended meter cannot be vended to. Requires the business:prepaid:manage permission.",
        "operationId": "setPrepaidMeterStatus",
        "parameters": [
          {
            "description": "ID of the prepaid meter enrollment to update.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^ppm_",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SetPrepaidMeterStatusRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidMeter"
                }
              }
            },
            "description": "Updated prepaid meter"
          },
          "400": {
            "description": "Invalid status"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:manage scope"
          },
          "404": {
            "description": "Prepaid meter not found in the authenticated tenant"
          },
          "409": {
            "description": "Status transition is not valid"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Suspend or resume a prepaid meter",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:prepaid:manage"
        ]
      }
    },
    "$BUSINESS_API/prepaid/meters/{id}/wallet": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the credit and debit movements in a prepaid meter's wallet. Each vend posts a credit for the payment and a debit for the water bought, both referencing the vend ID. Requires the business:prepaid:read permission.",
        "operationId": "listPrepaidWallet",
        "parameters": [
          {
            "description": "ID of the prepaid meter enrollment whose wallet is listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^ppm_",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidWalletPage"
                }
              }
            },
            "description": "Wallet entries for the prepaid meter"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List wallet ledger entries",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      }
    },
    "$BUSINESS_API/prepaid/vends": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the tenant's prepaid vends, from counter sales and customer purchases, with each vend's amount, litres, token and status. Requires the business:prepaid:read permission.",
        "operationId": "listPrepaidVends",
        "parameters": [
          {
            "description": "Optional vend status filter: pending_payment, issued or failed.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "pending_payment",
                "issued",
                "failed"
              ],
              "type": "string"
            }
          },
          {
            "description": "Optional prepaid meter enrollment ID; only vends for that meter are returned.",
            "in": "query",
            "name": "prepaid_meter_id",
            "required": false,
            "schema": {
              "pattern": "^ppm_",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidVendPage"
                }
              }
            },
            "description": "Vends in the authenticated utility tenant"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List vending transactions",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      },
      "post": {
        "description": "Takes a counter payment and issues the token in one step, then returns the vend with 201. The body needs prepaid_meter_id, amount_cents and an idempotency_key, and method defaults to cash. Repeating a key returns the existing vend. The payment is recorded only after the token generator reports it is ready; then the wallet is credited and debited, the token is minted and the sale is posted to the ledger. A suspended meter returns 409, an unavailable token generator returns 503, and a failure after recording marks the vend failed. Requires the business:prepaid:vend permission.",
        "operationId": "createPrepaidVend",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/StaffPrepaidVendRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidVend"
                }
              }
            },
            "description": "Vend created"
          },
          "400": {
            "description": "Invalid vend request"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:vend scope"
          },
          "404": {
            "description": "Prepaid meter not found in the authenticated tenant"
          },
          "409": {
            "description": "Vend request conflicts with the existing state"
          },
          "503": {
            "description": "Payment provider or token generator is unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Vend at the counter (token issued only by a configured generator)",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:prepaid:vend"
        ]
      }
    },
    "$BUSINESS_API/prepaid/vends/{id}": {
      "get": {
        "description": "Returns one vend with its status, amount, litres, token (when issued), charge breakdown, payment ID, receipt number and failure reason (when failed). Requires the business:prepaid:read permission, and returns 404 when the vend does not exist.",
        "operationId": "getPrepaidVend",
        "parameters": [
          {
            "description": "ID of the vend (prefixed vnd_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^vnd_",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidVend"
                }
              }
            },
            "description": "Vend in the authenticated utility tenant"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          },
          "404": {
            "description": "Vend not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a vend",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      }
    },
    "$BUSINESS_API/prepaid/vends/{id}/receipt.pdf": {
      "get": {
        "description": "Renders the vend's receipt as a PDF and returns it as an attachment. Receipts exist only for issued vends: a pending or failed vend, or a deployment without receipt rendering, returns 404. Requires the business:prepaid:read permission.",
        "operationId": "getPrepaidVendReceipt",
        "parameters": [
          {
            "description": "ID of the issued vend whose receipt is rendered.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^vnd_",
              "type": "string"
            }
          },
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Vend receipt PDF"
          },
          "401": {
            "description": "Authenticated utility context required"
          },
          "403": {
            "description": "Missing business:prepaid:read scope"
          },
          "404": {
            "description": "Vend or receipt not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the vend receipt PDF",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:prepaid:read"
        ]
      }
    },
    "$BUSINESS_API/price-revisions": {
      "get": {
        "description": "Returns one cursor-paginated page (limit, after) of the tenant's price revisions, filtered by the optional status query parameter (proposed, applied or rejected). Requires the tariffs:read permission.",
        "operationId": "listPriceRevisions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Price revisions and generic before-and-after samples"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List proposed and applied price revisions",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "tariffs:read"
        ]
      },
      "post": {
        "description": "Proposes a bulk price change and stores it as proposed, with a preview of every affected price, so another person can review it before it takes effect. The body needs at least one of percent_bp (-5000 to 50000) and fixed_delta_minor, an effective_from in the future, and a reason. Optional fields are scope_target (all, rates only or fixed fees only), rounding_step_minor, and either target_ids or category, not both. Returns 400 when no active price matches, or when a listed target is inactive or outside the category. Requires the tariffs:write permission and records an audit entry.",
        "operationId": "proposePriceRevision",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "anyOf": [
                  {
                    "required": [
                      "percent_bp"
                    ]
                  },
                  {
                    "required": [
                      "fixed_delta_minor"
                    ]
                  }
                ],
                "properties": {
                  "category": {
                    "description": "Target price category; mutually exclusive with target_ids",
                    "type": "string"
                  },
                  "effective_from": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "fixed_delta_minor": {
                    "description": "Fixed adjustment in currency minor units; may be combined with percent_bp",
                    "type": "integer"
                  },
                  "percent_bp": {
                    "description": "Basis-point percentage adjustment; 750 means +7.5 percent",
                    "maximum": 50000,
                    "minimum": -5000,
                    "type": "integer"
                  },
                  "reason": {
                    "minLength": 1,
                    "type": "string"
                  },
                  "rounding_step_minor": {
                    "description": "Round adjusted amounts to the nearest number of minor units",
                    "minimum": 0,
                    "type": "integer"
                  },
                  "scope_target": {
                    "default": "all",
                    "enum": [
                      "all",
                      "rates_only",
                      "fixed_fees_only"
                    ],
                    "type": "string"
                  },
                  "target_ids": {
                    "description": "Explicit active price or tariff IDs; mutually exclusive with category",
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "effective_from",
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Proposed price revision with generic impact preview"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Preview and propose an effective-dated price revision",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "tariffs:write"
        ]
      }
    },
    "$BUSINESS_API/price-revisions/{id}": {
      "get": {
        "description": "Returns one price revision with its adjustment, targets, effective date, preview lines, status and, once decided, who decided, when and the IDs of the prices it created. Requires the tariffs:read permission, and returns 404 when the revision does not exist.",
        "operationId": "getPriceRevision",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a price revision and its impact preview",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "tariffs:read"
        ]
      }
    },
    "$BUSINESS_API/price-revisions/{id}/approve": {
      "post": {
        "description": "Applies a proposed revision: it creates new price versions effective from the revision's date, marks the revision applied and records an audit entry. The optional body carries a decision reason. The proposer cannot approve their own revision (403). A revision that is no longer proposed, or whose effective date has passed, returns 409. A 409 is also returned when the affected prices changed since the preview, and then a new revision must be proposed. Requires the tariffs:approve permission.",
        "operationId": "approvePriceRevision",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create effective-dated price versions; the proposer cannot approve",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "tariffs:approve"
        ]
      }
    },
    "$BUSINESS_API/price-revisions/{id}/reject": {
      "post": {
        "description": "Marks a proposed revision as rejected without changing any price, storing who decided, when and the optional reason from the body. A revision that is no longer proposed returns 409. Requires the tariffs:approve permission and records an audit entry.",
        "operationId": "rejectPriceRevision",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a proposed price revision",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "tariffs:approve"
        ]
      }
    },
    "$BUSINESS_API/properties": {
      "get": {
        "description": "Returns a cursor-paginated page of the tenant's properties (premises), each with its owning customer, address and cadastral details. Besides the filters below you can pass q for a text search, service_area_id, cadastral_code, limit (default 20, maximum 100) and after (the next_cursor of the previous page). Requires the business:properties:read permission.",
        "operationId": "listProperties",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "description": "Returns only properties owned by this customer ID; omit it to list properties of every customer in the tenant.",
            "in": "query",
            "name": "customer_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only properties in this status, either active or closed; omit it to include both.",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PropertyPage"
                }
              }
            },
            "description": "Utility properties"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List tenant-scoped properties",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:properties:read"
        ]
      },
      "post": {
        "description": "Registers a new property for an existing customer of the tenant and returns it with status active and a generated ID. customer_id and address_line are required, latitude and longitude must be sent together and within valid ranges, premise_type must be one of residential, commercial, industrial, institutional, government, mixed or other, and service_area_id must name one of the tenant's own service areas; any of these failures returns 400, and an unknown customer returns 404. The initial ownership is recorded as a property transfer event to the customer.",
        "operationId": "createProperty",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateProperty"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Property"
                }
              }
            },
            "description": "Property registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a property for an existing utility customer",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:properties:create"
        ]
      }
    },
    "$BUSINESS_API/properties/{id}": {
      "get": {
        "description": "Returns one of the tenant's properties by ID, including its owning customer, address, coordinates, cadastral details and status. A property that does not exist or belongs to another tenant returns 404. Requires the business:properties:read permission.",
        "operationId": "getBusinessProperty",
        "parameters": [
          {
            "description": "Property identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Property"
                }
              }
            },
            "description": "Property"
          },
          "404": {
            "description": "Unknown property"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one property",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:properties:read"
        ]
      },
      "patch": {
        "description": "Completes or corrects a property's cadastral attributes (cadastral code, service area, second address line, neighbourhood, city, postal code, premise type and coordinates) and returns the updated property. The body replaces these attributes as a set: an attribute you omit is cleared, except latitude and longitude, which are only changed when both are sent. The owner, the main address line and the status are not changed here. Invalid lengths, an unknown premise_type or a service area outside the tenant return 400, and an unknown property returns 404.",
        "operationId": "updatePropertyDetails",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PropertyDetails"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated property"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a premise's cadastral attributes",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:properties:write"
        ]
      }
    },
    "$BUSINESS_API/properties/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata attached to a property, as a map of string keys to string values together with the resource type and ID. The property must exist in the caller's tenant, otherwise the call returns 404. Requires the business:metadata:read permission.",
        "operationId": "getBusinessPropertyMetadata",
        "parameters": [
          {
            "description": "ID of the property whose metadata to read; at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a property",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the metadata object in the body into the property's existing metadata and returns the full resulting map. A key with a non-empty value is created or overwritten, a key sent with an empty string is deleted, and keys you do not send are left as they are. Keys must be non-blank, at most 40 characters and free of square brackets and control characters, values at most 500 characters, and a resource may hold at most 50 keys after the merge; violations return 400 with the offending keys. The property must exist in the caller's tenant (404 otherwise) and the caller needs business:metadata:write.",
        "operationId": "putBusinessPropertyMetadata",
        "parameters": [
          {
            "description": "ID of the property whose metadata to change; at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/properties/{id}/transfer": {
      "post": {
        "description": "Only the property moves. Existing accounts keep their holder, because their open balances and consumer access belong to that customer; affected_accounts names the open accounts needing follow-up.",
        "operationId": "transferBusinessProperty",
        "parameters": [
          {
            "description": "Property identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "customer_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "customer_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/Property"
                    },
                    {
                      "properties": {
                        "affected_accounts": {
                          "items": {
                            "properties": {
                              "account_number": {
                                "type": "string"
                              },
                              "customer_id": {
                                "type": "string"
                              },
                              "id": {
                                "type": "string"
                              },
                              "status": {
                                "type": "string"
                              }
                            },
                            "type": "object"
                          },
                          "type": "array"
                        },
                        "previous_customer_id": {
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "The transferred property and the accounts left on the previous holder"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Move a property to another customer",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:properties:write"
        ]
      }
    },
    "$BUSINESS_API/reading-assignments": {
      "get": {
        "description": "Returns a cursor-paginated page of reading assignments, each giving the reader, the round and the meters that reader must read. Use limit (default 20, maximum 100) and after to page. Requires the business:reading-assignments:read permission.",
        "operationId": "listReadingAssignments",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only assignments that belong to this reading round ID.",
            "in": "query",
            "name": "round_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only assignments given to this reader (the user ID of the meter reader).",
            "in": "query",
            "name": "reader_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only assignments in this status: assigned, in_progress, completed or cancelled; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "assigned",
                "in_progress",
                "completed",
                "cancelled"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered reader assignments with meter stops"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List field-reader assignments",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-assignments:read"
        ]
      },
      "post": {
        "description": "If meter_ids is omitted, all route meters not already assigned in this round are assigned.",
        "operationId": "createReadingAssignment",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReadingAssignment"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingAssignment"
                }
              }
            },
            "description": "Reading assignment created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Assign route meters in a round to a utility reader",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-assignments:create"
        ]
      }
    },
    "$BUSINESS_API/reading-assignments/{id}": {
      "get": {
        "description": "Returns one reading assignment with its reader, round, meter IDs, due date and the timestamps of each status change. An assignment that does not exist in the tenant returns 404. Requires the business:reading-assignments:read permission.",
        "operationId": "getReadingAssignment",
        "parameters": [
          {
            "description": "ID of the reading assignment to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingAssignment"
                }
              }
            },
            "description": "Assignment with its assigned meter stops"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a field-reader assignment",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-assignments:read"
        ]
      }
    },
    "$BUSINESS_API/reading-assignments/{id}/status": {
      "patch": {
        "description": "Moves a reading assignment to a new status and returns 204 with no body. Allowed moves are assigned to in_progress or cancelled, and in_progress to completed or cancelled; starting work requires the round to be open or in_progress, and completing requires the round to be in_progress. Any other move returns 409, an unknown status value returns 400, and sending the current status again is a no-op. Requires business:reading-assignments:manage.",
        "operationId": "setReadingAssignmentStatus",
        "parameters": [
          {
            "description": "ID of the reading assignment whose status to change.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "status": {
                    "enum": [
                      "assigned",
                      "in_progress",
                      "completed",
                      "cancelled"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Assignment status changed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start, complete, or cancel an assignment",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-assignments:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-cycles": {
      "get": {
        "description": "Returns a cursor-paginated page of the tenant's reading cycles, each with its code, billing frequency and the day of the month readings are scheduled. You can also pass q for a text search, limit (default 20, maximum 100) and after. Requires the business:reading-cycles:read permission.",
        "operationId": "listReadingCycles",
        "parameters": [
          {
            "description": "Boolean filter (true/false, also 1/0): true returns only active cycles, false only inactive ones; omit it to return both, and a value that is not a boolean returns 400.",
            "in": "query",
            "name": "active",
            "schema": {
              "type": "boolean"
            }
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Reading cycles"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List reading cycles",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-cycles:read"
        ]
      },
      "post": {
        "description": "Creates a reading cycle that groups routes and readings into a billing period and returns it as active. code is required (at most 60 characters), name is optional (at most 255), billing_frequency must be monthly, bimonthly, quarterly, semiannual or annual, and schedule_day_of_month must be between 1 and 28; other values return 400. A code already used in the tenant returns 409. Requires business:reading-cycles:manage.",
        "operationId": "createReadingCycle",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingCycle"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Cycle created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a reading cycle",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-cycles:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-cycles/{id}": {
      "get": {
        "description": "Returns one reading cycle with its code, name, billing frequency, schedule day and whether it is active. A cycle that does not exist in the tenant returns 404. Requires the business:reading-cycles:read permission.",
        "operationId": "getReadingCycle",
        "parameters": [
          {
            "description": "ID of the reading cycle to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Cycle"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a reading cycle",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-cycles:read"
        ]
      },
      "patch": {
        "description": "Changes only the fields present in the body (name, billing_frequency, schedule_day_of_month, active) and returns the updated cycle; the code cannot be changed. billing_frequency must be monthly, bimonthly, quarterly, semiannual or annual and schedule_day_of_month between 1 and 28, otherwise the call returns 400. Setting active to false deactivates the cycle without deleting it. Requires business:reading-cycles:manage.",
        "operationId": "updateReadingCycle",
        "parameters": [
          {
            "description": "ID of the reading cycle to update.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "active": {
                    "type": "boolean"
                  },
                  "billing_frequency": {
                    "enum": [
                      "monthly",
                      "bimonthly",
                      "quarterly",
                      "semiannual",
                      "annual"
                    ],
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "schedule_day_of_month": {
                    "maximum": 28,
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated cycle"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a reading cycle",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-cycles:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-disputes": {
      "get": {
        "description": "Returns a cursor-paginated page of the disputes customers have raised against meter readings, with the account, reading, reason, who filed it and any resolution. Use limit (default 20, maximum 100) and after to page. Requires the business:reading-disputes:read permission.",
        "operationId": "listReadingDisputes",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only disputes raised on this account ID.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only disputes raised against this meter reading ID.",
            "in": "query",
            "name": "reading_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only disputes in this status: open, in_review, resolved or rejected; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "open",
                "in_review",
                "resolved",
                "rejected"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Tenant-scoped consumer reading disputes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List consumer disputes in the utility tenant",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-disputes:read"
        ]
      }
    },
    "$BUSINESS_API/reading-disputes/{id}/status": {
      "patch": {
        "description": "Moves a reading dispute forward and returns 204 with no body. An open dispute can go to in_review, and an open or in_review dispute can be closed as resolved or rejected; closing requires a non-empty resolution text, which is stored with the reviewer and the time. Any other move, including reopening a closed dispute, returns 409, and an unknown status returns 400. Requires business:reading-disputes:manage.",
        "operationId": "updateReadingDispute",
        "parameters": [
          {
            "description": "ID of the reading dispute to update.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "resolution": {
                    "maxLength": 500,
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "in_review",
                      "resolved",
                      "rejected"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Dispute state updated"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Review, resolve, or reject a consumer reading dispute",
        "x-roles": [
          "admin",
          "customer_service",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-disputes:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-estimates": {
      "post": {
        "description": "Estimates remain marked as estimates and require the same validation and acceptance process as observations.",
        "operationId": "submitEstimatedReading",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Estimated reading submitted for validation or review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an estimated meter reading for explicit review",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:readings:estimate"
        ]
      }
    },
    "$BUSINESS_API/reading-imports": {
      "post": {
        "description": "Each source-file row is independently idempotent and follows the canonical Meter validation and review lifecycle.",
        "operationId": "importMeterReadings",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingImportRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Per-row import outcomes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Import a retry-safe batch of normalized utility readings",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:readings:import"
        ]
      }
    },
    "$BUSINESS_API/reading-requests": {
      "get": {
        "description": "Returns a cursor-paginated page of on-demand reading requests sent to remote reading integrations, with their status, due time, attempt count, failure reason and the reading they produced. Requests created by reading schedules carry the schedule_id. Use limit (default 20, maximum 100) and after to page. Requires business:reading-requests:read.",
        "operationId": "listReadingRequests",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only requests for this meter ID.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only requests addressed to this integration ID (the remote reading source).",
            "in": "query",
            "name": "source_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only requests in this status: requested, assigned, acquired, failed or expired; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "requested",
                "assigned",
                "acquired",
                "failed",
                "expired"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Remote reading requests in the authenticated utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List on-demand and scheduled remote reading requests",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-requests:read"
        ]
      },
      "post": {
        "description": "Asks an active remote reading integration to fetch a reading from an active meter; the integration later leases the request and reports the reading or a failure. meter_id, source_id and idempotency_key (at most 160 characters) are required, and due_at defaults to 10 minutes from now and must fall within the next 30 days. Repeating a call with the same source_id and idempotency_key returns the existing request, but reusing the key for a different meter or due time returns 409, as does a meter that is not active. An integration that is not active returns 403.",
        "operationId": "createReadingRequest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingRequestInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingRequest"
                }
              }
            },
            "description": "Reading request queued"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request an on-demand reading from an active utility integration",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-requests:create"
        ]
      }
    },
    "$BUSINESS_API/reading-rounds": {
      "get": {
        "description": "Returns a cursor-paginated page of reading rounds, each being one scheduled pass over a route for a cycle, with its status and the times it was opened, completed or cancelled. Use limit (default 20, maximum 100) and after to page. Requires business:reading-rounds:read.",
        "operationId": "listReadingRounds",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only rounds that walk this reading route ID.",
            "in": "query",
            "name": "route_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only rounds that belong to this reading cycle ID.",
            "in": "query",
            "name": "cycle_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only rounds in this status: planned, open, in_progress, completed or cancelled; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "planned",
                "open",
                "in_progress",
                "completed",
                "cancelled"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Filtered reading rounds"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List route reading rounds",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-rounds:read"
        ]
      },
      "post": {
        "description": "Plans a round of readings over a route for a cycle and returns it with status planned. route_id, cycle_id and scheduled_at are required (400 otherwise); the route must exist (404) and be active, or the call returns 409. Readers are then given meters through reading assignments while the round is planned or open.",
        "operationId": "createReadingRound",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReadingRound"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingRound"
                }
              }
            },
            "description": "Reading round created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule a reading round for a route and cycle",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-rounds:create"
        ]
      }
    },
    "$BUSINESS_API/reading-rounds/{id}": {
      "get": {
        "description": "Returns one reading round with its route, cycle, scheduled time, status and the opened, completed and cancelled timestamps. A round that does not exist in the tenant returns 404. Requires business:reading-rounds:read.",
        "operationId": "getReadingRound",
        "parameters": [
          {
            "description": "ID of the reading round to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingRound"
                }
              }
            },
            "description": "Reading round details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a reading round",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-rounds:read"
        ]
      }
    },
    "$BUSINESS_API/reading-rounds/{id}/status": {
      "patch": {
        "description": "Moves a reading round to a new status and returns 204 with no body. Allowed moves are planned to open or cancelled, open to in_progress or cancelled, and in_progress to completed or cancelled; starting requires at least one assignment, and completing requires every assignment to be completed or cancelled. Any other move returns 409, an unknown status returns 400, and sending the current status again is a no-op. Requires business:reading-rounds:manage.",
        "operationId": "setReadingRoundStatus",
        "parameters": [
          {
            "description": "ID of the reading round whose status to change.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "status": {
                    "enum": [
                      "planned",
                      "open",
                      "in_progress",
                      "completed",
                      "cancelled"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Reading round status changed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Advance or cancel a reading round",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-rounds:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-routes": {
      "get": {
        "description": "Returns a cursor-paginated page of the tenant's reading routes, each with its ordered meter stops, assigned reader and cycle. You can also filter by assigned_reader_id and cycle_id, search with q, and page with limit (default 20, maximum 100) and after. Requires business:reading-routes:read.",
        "operationId": "listReadingRoutes",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only routes in this service area ID.",
            "in": "query",
            "name": "service_area_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only routes in this status, active or disabled; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "active",
                "disabled"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/Search"
          }
        ],
        "responses": {
          "200": {
            "description": "Service-area routes and ordered meter stops"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List meter routes in the authenticated utility tenant",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-routes:read"
        ]
      },
      "post": {
        "description": "Creates an active reading route in an active service area, listing the meters a reader visits in walk order. Send either meter_ids (sequenced in the order given) or points with explicit sequence_order and optional walking_notes (at most 500 characters); up to 500 distinct meters, all of which must be active. name (at most 255 characters) and service_area_id are required; assigned_reader_id and cycle_id are optional, and an unknown cycle or service area returns 404.",
        "operationId": "createReadingRoute",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateReadingRoute"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingRoute"
                }
              }
            },
            "description": "Reading route created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a service-area route containing active utility meters",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-routes:create",
          "business:service-areas:read"
        ]
      }
    },
    "$BUSINESS_API/reading-routes/{id}": {
      "get": {
        "description": "Returns one reading route with its service area, status, meter IDs, ordered points with walking notes, assigned reader and cycle. A route that does not exist in the tenant returns 404. Requires business:reading-routes:read.",
        "operationId": "getReadingRoute",
        "parameters": [
          {
            "description": "ID of the reading route to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingRoute"
                }
              }
            },
            "description": "Reading route details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a route and its ordered meter stops",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-routes:read"
        ]
      }
    },
    "$BUSINESS_API/reading-routes/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata attached to a reading route, as a map of string keys to string values together with the resource type and ID. The route must exist in the caller's tenant, otherwise the call returns 404. Requires the business:metadata:read permission.",
        "operationId": "getBusinessReadingRouteMetadata",
        "parameters": [
          {
            "description": "ID of the reading route whose metadata to read; at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a reading route",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the metadata object in the body into the route's existing metadata and returns the full resulting map. A key with a non-empty value is created or overwritten, a key sent with an empty string is deleted, and keys you do not send are kept. Keys must be non-blank, at most 40 characters and free of square brackets and control characters, values at most 500 characters, and a resource may hold at most 50 keys after the merge; violations return 400. The route must exist in the caller's tenant (404 otherwise) and the caller needs business:metadata:write.",
        "operationId": "putBusinessReadingRouteMetadata",
        "parameters": [
          {
            "description": "ID of the reading route whose metadata to change; at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/reading-routes/{id}/plan": {
      "patch": {
        "description": "Changes a route's plan and returns the updated route: the assigned reader, the cycle and the walk order. Only the fields present are changed; an empty string clears the reader or the cycle, and a cycle that does not exist returns 404. points resequences the route and must list exactly the route's current meters with unique sequence_order values of 1 or more, so the meter set itself cannot change here (400 otherwise). Requires business:reading-routes:manage.",
        "operationId": "updateReadingRoutePlan",
        "parameters": [
          {
            "description": "ID of the reading route whose plan to change.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "assigned_reader_id": {
                    "type": "string"
                  },
                  "cycle_id": {
                    "type": "string"
                  },
                  "points": {
                    "items": {
                      "properties": {
                        "meter_id": {
                          "type": "string"
                        },
                        "sequence_order": {
                          "minimum": 1,
                          "type": "integer"
                        },
                        "walking_notes": {
                          "type": "string"
                        }
                      },
                      "required": [
                        "meter_id",
                        "sequence_order"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Route with its plan"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Assign a reader and cycle and resequence the walk order",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-routes:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-routes/{id}/status": {
      "patch": {
        "description": "Enables or disables a reading route and returns 204 with no body. The status must be active or disabled (400 otherwise), and an unknown route returns 404. A disabled route cannot get new reading rounds until it is made active again. Requires business:reading-routes:manage.",
        "operationId": "setReadingRouteStatus",
        "parameters": [
          {
            "description": "ID of the reading route whose status to change.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "disabled"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Reading route status changed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Enable or disable a reading route",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-routes:manage"
        ]
      }
    },
    "$BUSINESS_API/reading-schedules": {
      "get": {
        "description": "Returns a cursor-paginated page of recurring remote reading schedules, each with its meter, integration, interval, next run time and last request time. Use limit (default 20, maximum 100) and after to page. Requires business:reading-schedules:read.",
        "operationId": "listReadingSchedules",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only schedules for this meter ID.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only schedules that use this integration ID as the remote reading source.",
            "in": "query",
            "name": "source_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only schedules in this status, active or paused; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "active",
                "paused"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Utility reading schedules"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List remote meter acquisition schedules",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-schedules:read"
        ]
      },
      "post": {
        "description": "Creates an active schedule that turns into a remote reading request for the meter every interval_seconds (between 60 and 31,536,000). meter_id and source_id are required; next_run_at defaults to now plus one interval and must fall within the next 365 days. The meter must be active (409 otherwise) and the integration must exist and be active (404 or 403). Schedules only produce requests when they are materialized.",
        "operationId": "createReadingSchedule",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingScheduleInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingSchedule"
                }
              }
            },
            "description": "Reading schedule created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Schedule recurring remote readings",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-schedules:create"
        ]
      }
    },
    "$BUSINESS_API/reading-schedules/materialize": {
      "post": {
        "description": "Turns every active schedule whose next run time has passed into a reading request due in 10 minutes, advances each schedule by one interval, and returns 201 with the requests in data. The body's limit (1 to 100, required) caps how many due schedules are processed, oldest first. Schedules whose integration is no longer active are skipped, and each schedule run has a fixed idempotency key, so calling again does not duplicate a request already created. Requires business:reading-schedules:run.",
        "operationId": "materializeDueReadingSchedules",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "limit": {
                    "maximum": 100,
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "required": [
                  "limit"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Due scheduled requests created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Turn due schedules into idempotent reading requests",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-schedules:run"
        ]
      }
    },
    "$BUSINESS_API/reading-schedules/{id}/status": {
      "patch": {
        "description": "Pauses or resumes a reading schedule and returns 204 with no body. The status must be active or paused (400 otherwise), and an unknown schedule returns 404. A paused schedule is ignored when due schedules are materialized. Requires business:reading-schedules:manage.",
        "operationId": "setReadingScheduleStatus",
        "parameters": [
          {
            "description": "ID of the reading schedule to pause or resume.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "status": {
                    "enum": [
                      "active",
                      "paused"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Schedule status changed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Pause or resume a remote reading schedule",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reading-schedules:manage"
        ]
      }
    },
    "$BUSINESS_API/readings": {
      "get": {
        "description": "Returns a cursor-paginated page of meter readings in the tenant, with value, unit, method, status, plausibility result and the route, cycle and assignment they came from. Filters combine, and limit (default 20, maximum 100) and after page the results. Requires business:readings:read.",
        "operationId": "listReadings",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only readings taken on this meter ID.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only readings recorded for this account ID.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only readings taken while working this reading route ID.",
            "in": "query",
            "name": "route_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only readings that belong to this reading cycle ID.",
            "in": "query",
            "name": "cycle_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only readings in this status: submitted, validating, accepted, review_required, rejected or superseded; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "submitted",
                "validating",
                "accepted",
                "review_required",
                "rejected",
                "superseded"
              ],
              "type": "string"
            }
          },
          {
            "description": "Returns only readings captured this way: manual, consumer, remote, imported or estimated; any other value returns 400.",
            "in": "query",
            "name": "method",
            "schema": {
              "enum": [
                "manual",
                "consumer",
                "remote",
                "imported",
                "estimated"
              ],
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp; returns only readings measured at or after this instant, and it must not be later than measured_to (400 otherwise).",
            "in": "query",
            "name": "measured_from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp; returns only readings measured at or before this instant.",
            "in": "query",
            "name": "measured_to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Readings in the authenticated utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility readings with filters",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:readings:read"
        ]
      },
      "post": {
        "description": "Records a reading taken by staff and returns 202 with the reading, whose status is submitted or review_required depending on the plausibility check; a manual reading also logs a field visit. meter_id, client_reading_id, idempotency_key, measured_at, value and the meter's unit are required, the meter must be active, and measured_at cannot be before installation or more than 5 minutes in the future. Retrying with the same idempotency_key and identical data returns the original reading, while different data returns 409. Sending a readings array instead records up to 500 readings and returns 207 with a per-item result.",
        "operationId": "submitManualMeterReading",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Reading recorded for validation or review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit a manual field reading for review",
        "x-roles": [
          "admin",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:readings:create"
        ]
      }
    },
    "$BUSINESS_API/readings/plausibility-review": {
      "get": {
        "description": "Returns the review queue: readings in review_required status that the plausibility check flagged as high, negative or zero consumption, a page at a time (limit default 20, maximum 100, and after). Each item adds up to 12 accepted readings of the same meter from the previous three months, their average consumption and the high-consumption threshold derived from it. Requires business:readings:read.",
        "operationId": "listPlausibilityReview",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Flagged readings with average, threshold and recent accepted readings"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Readings awaiting plausibility review with three-month context",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:readings:read"
        ]
      }
    },
    "$BUSINESS_API/readings/{id}": {
      "get": {
        "description": "Returns one meter reading with its value, unit, method, status, plausibility result, evidence and review details. A reading that does not exist in the tenant returns 404. Requires business:readings:read.",
        "operationId": "getReading",
        "parameters": [
          {
            "description": "ID of the meter reading to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Reading details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a tenant-owned reading",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:readings:read"
        ]
      }
    },
    "$BUSINESS_API/readings/{id}/accept": {
      "post": {
        "description": "Accepts a reading so it can be used for consumption and billing, records the reviewer and the status change, and returns the updated reading. Only readings in submitted or review_required status can be accepted; any other status returns 409. Requires business:readings:review.",
        "operationId": "acceptMeterReading",
        "parameters": [
          {
            "description": "ID of the meter reading to accept.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Accepted reading"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept a submitted or review-required reading",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:readings:review"
        ]
      }
    },
    "$BUSINESS_API/readings/{id}/corrections": {
      "post": {
        "description": "The accepted source observation remains preserved as a superseded record; the correction requires a reason and idempotency key.",
        "operationId": "correctAcceptedMeterReading",
        "parameters": [
          {
            "description": "ID of the accepted meter reading to correct; the correction is created as a new reading that supersedes it.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReadingCorrectionInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Corrected reading created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an immutable correction that supersedes an accepted reading",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:readings:correct"
        ]
      }
    },
    "$BUSINESS_API/readings/{id}/reject": {
      "post": {
        "description": "Rejects a reading so it is not used for consumption or billing, records the reviewer, the reason and the status change, and returns the updated reading. A reason of 1 to 500 characters is required (400 otherwise). Only readings in submitted or review_required status can be rejected; any other status returns 409. Requires business:readings:review.",
        "operationId": "rejectMeterReading",
        "parameters": [
          {
            "description": "ID of the meter reading to reject.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "maxLength": 500,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Rejected reading"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a submitted or review-required reading with a reason",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:readings:review"
        ]
      }
    },
    "$BUSINESS_API/receipts": {
      "get": {
        "description": "Returns a cursor-paginated page of payment receipts issued in the tenant, each with its receipt number, payment, invoice, customer, account, amount in cents and issue time. You can narrow it with account_id or invoice_id and page with limit and after. Requires the payments:read permission.",
        "operationId": "listReceipts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Receipts in the authenticated utility tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List receipts issued for recorded payments",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/receipts/{number}": {
      "get": {
        "description": "Returns the receipt issued for a recorded payment: receipt number, the payment and invoice it covers, customer and account (with the holder's display name), amount in minor units, currency and issue time. Use GET $BUSINESS_API/receipts/{number}/pdf for the printable document. Requires payments:read; a number that does not exist in the caller's tenant returns 404.",
        "operationId": "getReceipt",
        "parameters": [
          {
            "description": "Receipt number as printed on the receipt, unique within the tenant.",
            "in": "path",
            "name": "number",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentReceipt"
                }
              }
            },
            "description": "Receipt"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing payments:read scope"
          },
          "404": {
            "description": "Receipt not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a payment receipt by its number",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/receipts/{number}/pdf": {
      "get": {
        "description": "Renders the receipt with this number as a PDF and returns it inline with Content-Type application/pdf. The document shows the tenant as issuer, the customer and account, the amount, the payment method and reference, and the paid invoice number when there is one. A receipt that does not exist in the tenant returns 404.",
        "operationId": "getReceiptPDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Receipt number",
            "in": "path",
            "name": "number",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a payment receipt as a PDF recibo",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "payments:read"
        ]
      }
    },
    "$BUSINESS_API/receivables": {
      "get": {
        "description": "Returns the tenant's open receivables, one row per invoice that is open or partially paid and still has a balance, a page at a time (limit and after). Each row has the balance and total in cents, due date, the whole days overdue as of now and an ageing bucket: current, 1_30, 31_60, 61_90 or over_90. Requires the invoices:read permission.",
        "operationId": "listReceivables",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaginatedReceivables"
                }
              }
            },
            "description": "Receivables in the authenticated utility tenant"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Missing invoices:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility receivables",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "invoices:read"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-contracts": {
      "get": {
        "description": "Returns a cursor-paginated page of operator commission contracts, each binding a meter (and optionally an account or connection) to an operator or agent for a term with a commission rate. Filter with status, meter_id or account_id and page with limit and after. An active contract whose end date has passed is shown as expired. Requires business:reconciliations:read.",
        "operationId": "listReconciliationContracts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List operator and agent commission agreements",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      },
      "post": {
        "description": "Creates an operator or agent commission contract for a meter and returns it in draft status. meter_id and operator_name are required, end_date must be after start_date, and commission_bp must be between 0 and 10000 basis points; the meter must exist in the tenant. The contract does not take effect until its status is set to active. Requires business:reconciliations:write.",
        "operationId": "createReconciliationContract",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "meter_id",
                  "operator_name",
                  "start_date",
                  "end_date",
                  "commission_bp"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create an operator or agent commission agreement on a meter",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reconciliations:write"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-contracts/{id}": {
      "get": {
        "description": "Returns one operator commission contract with its meter, operator details, term, commission rate and status. An active contract whose end date has passed is reported as expired. A contract that does not exist in the tenant returns 404. Requires business:reconciliations:read.",
        "operationId": "getReconciliationContract",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a commission agreement",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-contracts/{id}/status": {
      "post": {
        "description": "Moves a contract to a new status and returns the updated contract. Allowed moves are draft to active or terminated, active to suspended, terminated or expired, and suspended to active or terminated; any other move returns 409. Activating also returns 409 when the meter already has another active contract. Requires business:reconciliations:write.",
        "operationId": "setReconciliationContractStatus",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate, suspend or terminate a commission agreement",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:reconciliations:write"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-settlements": {
      "get": {
        "description": "Returns a cursor-paginated page of settlements, the statements issued to operators when a confirmed reconciliation is settled. Each shows the expected amount, commission, amount remitted and the balance still owed, in cents. Filter with status, meter_id or account_id and page with limit and after. Requires business:reconciliations:read.",
        "operationId": "listReconciliationSettlements",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List reconciliation settlement statements",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-settlements/{id}": {
      "get": {
        "description": "Returns one settlement with its number, reconciliation, contract, meter, expected, commission, remitted and balance amounts in cents, currency and issue details. A settlement that does not exist in the tenant returns 404. Requires business:reconciliations:read.",
        "operationId": "getReconciliationSettlement",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a reconciliation settlement statement",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-settlements/{id}/statement.pdf": {
      "get": {
        "description": "Renders a settlement statement as a PDF download (Content-Disposition attachment) showing the operator, the meter serial, the reconciled period and the expected, commission, remitted and balance amounts. The settlement, its contract and its reconciliation are read with the caller's own access. An unknown settlement returns 404 and missing read access returns 403.",
        "operationId": "getReconciliationSettlementPdf",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the reconciliation settlement statement PDF",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      }
    },
    "$BUSINESS_API/reconciliation-tariffs": {
      "get": {
        "description": "Returns a cursor-paginated page of reconciliation tariffs, which set the retail price per unit volume, the utility's price per cubic metre and the variance tolerance used when reconciling metered resale. Filter with status and page with limit and after. Requires business:reconciliations:read.",
        "operationId": "listReconciliationTariffs",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List unit-volume reconciliation pricing rules",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:reconciliations:read"
        ]
      },
      "post": {
        "description": "Creates an active reconciliation tariff from effective_from onwards; settlements use the latest active tariff in effect at the reconciled period's end. name, currency, effective_from and a positive retail_cents_per_unit are required, unit_litres defaults to 1000, and tolerance_bp must be between 0 and 10000; invalid values return 400. When utility_cents_per_m3 is omitted, wholesale_cents_per_m3 is used in its place. Requires business:reconciliations:settle.",
        "operationId": "createReconciliationTariff",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "name",
                  "retail_cents_per_unit",
                  "utility_cents_per_m3",
                  "tolerance_bp",
                  "currency",
                  "effective_from"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "currency": {
                      "type": "string"
                    },
                    "effective_from": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "id": {
                      "pattern": "^rtf_",
                      "type": "string"
                    },
                    "name": {
                      "type": "string"
                    },
                    "retail_cents_per_unit": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "status": {
                      "type": "string"
                    },
                    "tenant_id": {
                      "type": "string"
                    },
                    "tolerance_bp": {
                      "type": "integer"
                    },
                    "unit_litres": {
                      "format": "int64",
                      "type": "integer"
                    },
                    "utility_cents_per_m3": {
                      "format": "int64",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "id",
                    "tenant_id",
                    "name",
                    "unit_litres",
                    "retail_cents_per_unit",
                    "utility_cents_per_m3",
                    "tolerance_bp",
                    "currency",
                    "effective_from",
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Reconciliation pricing tariff created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a unit-volume reconciliation pricing rule",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:reconciliations:settle"
        ]
      }
    },
    "$BUSINESS_API/sandbox/advance": {
      "post": {
        "description": "Available only in sandbox tenants. Moves pending simulated payment sessions of the caller's tenant to an outcome, as a real connector would report it: confirmed (the default) records the payment against its invoice and emits the same events as a live confirmation; failed and expired close the session. Without payment_id every pending simulated session of the tenant is advanced. With readings set to true the call also generates one new cycle of meter readings for the tenant's meters, recorded as the caller, so the caller also needs the meter and reading scopes the meter service checks (business:meters:read, business:readings:read and business:readings:create). Requires the payments:write scope, and business:readings:create as well when readings is true. A live tenant or a missing scope returns 403, an unknown outcome or malformed body returns 400.",
        "operationId": "advanceSandbox",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "outcome": {
                    "default": "confirmed",
                    "description": "Outcome to apply to the selected sessions.",
                    "enum": [
                      "confirmed",
                      "failed",
                      "expired"
                    ],
                    "type": "string"
                  },
                  "payment_id": {
                    "description": "Reference of one pending simulated payment session to advance; when omitted, all pending sessions of the tenant are advanced.",
                    "type": "string"
                  },
                  "readings": {
                    "default": false,
                    "description": "Also generate one new cycle of meter readings.",
                    "type": "boolean"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SandboxAdvanceResult"
                }
              }
            },
            "description": "Sessions advanced and readings generated"
          },
          "400": {
            "description": "Malformed body or unknown outcome (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The tenant is not a sandbox tenant, or a required scope is missing"
          },
          "404": {
            "description": "The caller's tenant could not be found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Settle pending simulated payments and optionally generate readings",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/scim/tokens": {
      "get": {
        "description": "Returns every SCIM directory token of the caller's tenant, newest first, as a plain array (not paged). Token secrets are never included: they are shown only once, when a token is created. Requires business:team:read.",
        "operationId": "getScimTokens",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/EnterpriseScimToken"
                  },
                  "type": "array"
                }
              }
            },
            "description": "SCIM tokens"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Show the tenant's SCIM directory tokens",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      },
      "post": {
        "description": "Issues a bearer token that an identity provider uses to provision the caller's tenant through the SCIM API. The secret is returned only in this response; only its SHA-256 digest is stored, so a lost token must be revoked and replaced. name defaults to \"Default SCIM Directory Sync\"; expires_in_days 0 or omitted means it never expires. Requires business:team:manage. The issue is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "createScimToken",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseScimTokenCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseScimTokenCreated"
                }
              }
            },
            "description": "Token issued; the secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a SCIM directory token; the secret appears once in the response",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/scim/tokens/{id}": {
      "delete": {
        "description": "Revokes the SCIM token with this id in the caller's tenant; SCIM requests that present it are refused from then on. The call is idempotent and returns 204 for an unknown id. Requires business:team:manage. The revocation is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "deleteScimToken",
        "parameters": [
          {
            "description": "Identifier of the SCIM token to revoke (sct_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Token revoked"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a SCIM directory token",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/search": {
      "get": {
        "description": "Searches across the resources of the authenticated tenant. The tenant always comes from the token. Lookups run concurrently with a per-request timeout. Sources the caller's scopes exclude are omitted; a source that fails for any other reason is omitted and `partial` becomes true. Meters match by serial number, by the number of the account they are installed on (only for callers who may read accounts) and by exact meter ID; an exact serial ranks first.",
        "operationId": "searchBusiness",
        "parameters": [
          {
            "$ref": "#/components/parameters/SearchQuery"
          },
          {
            "description": "Comma-separated subset of [customer, account, property, meter, connection, invoice, payment, ticket, work_order, incident, reading_route]. Defaults to all of them; an unknown type is rejected.",
            "in": "query",
            "name": "types",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/SearchLimit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "description": "Matching resources, grouped by type in a stable order"
          },
          "400": {
            "description": "Invalid q, types or limit"
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Search the authenticated utility tenant",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:accounts:read",
          "business:customers:read",
          "business:metadata:read",
          "business:meters:read",
          "business:properties:read",
          "business:reading-routes:read",
          "connections:read",
          "invoices:read",
          "operations:read",
          "payments:read",
          "support:read"
        ]
      }
    },
    "$BUSINESS_API/security-policy": {
      "get": {
        "description": "Returns the tenant's sign-in security policy: whether two-factor authentication is required, whether a step-up is required when switching context, the idle session timeout, the allowed IP ranges and whether the IP list also applies to platform staff. The response also includes client_ip, the address the server sees for this request, so you can check an allowlist before saving it. Requires the business security read permission.",
        "operationId": "getSecurityPolicy",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecurityPolicy"
                }
              }
            },
            "description": "Get the tenant security policy"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the tenant security policy",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:security:read"
        ]
      },
      "put": {
        "description": "Replaces the tenant's whole security policy and returns it; omitted fields take their zero value. idle_timeout_minutes must be 0 (no idle timeout) or between 5 and 10080, and allowed_ip_ranges takes up to 200 CIDR ranges or bare addresses, which are stored as single-host ranges. If the ranges would exclude the caller's current address the call returns 409 unless confirm_lockout is true. Each save is written to the audit trail. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "putSecurityPolicy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/SecurityPolicyUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SecurityPolicy"
                }
              }
            },
            "description": "Replace the tenant security policy"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "409": {
            "description": "The policy would lock out the requester (IP_LOCKOUT_CONFIRMATION_REQUIRED)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace the tenant security policy",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:security:manage"
        ]
      }
    },
    "$BUSINESS_API/sensors": {
      "get": {
        "description": "Returns a cursor-paginated page of the tenant's telemetry sensors, each with its code, device ID, metric, unit, location in the supply chain and linked asset or DMA. Page with limit and after. Requires the monitoring read permission.",
        "operationId": "listSensors",
        "parameters": [
          {
            "description": "Returns only sensors of this kind: flow, pressure, level or quality.",
            "in": "query",
            "name": "kind",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SensorList"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List telemetry sensors",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      },
      "post": {
        "description": "Registers an active telemetry sensor whose samples can then be ingested and checked against alarm rules. code, name, device_id, metric and unit are required, and kind must be flow, pressure, level or quality. location must be abstraction_point, treatment_plant, reservoir or distribution and defaults to distribution; asset_id and dma_id are optional. Invalid values return 400 and a conflicting sensor returns 409.",
        "operationId": "createSensor",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateSensorRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sensor"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a telemetry sensor",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:monitoring:write"
        ]
      }
    },
    "$BUSINESS_API/sensors/{id}": {
      "get": {
        "description": "Returns one telemetry sensor with its code, device ID, kind, metric, unit, location, linked asset or DMA and whether it is active. A sensor that does not exist in the tenant returns 404.",
        "operationId": "getSensor",
        "parameters": [
          {
            "description": "ID of the sensor to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Sensor"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a sensor",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/service-areas": {
      "get": {
        "description": "Returns a cursor-paginated page of the tenant's service areas, the geographic zones used to group properties and reading routes. You can also pass q to match part of the name (case-insensitive), and limit and after to page. Requires business:service-areas:read.",
        "operationId": "listServiceAreas",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "$ref": "#/components/parameters/ServiceAreaStatus"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceAreaPage"
                }
              }
            },
            "description": "Service areas in the authenticated utility tenant"
          },
          "400": {
            "description": "Invalid pagination parameters"
          },
          "403": {
            "description": "Missing business:service-areas:read or invalid tenant context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility service areas",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:service-areas:read"
        ]
      },
      "post": {
        "description": "Creates a service area in the caller's tenant with the given name and returns it with status active. The name is trimmed and must not be empty (400 otherwise). Properties and reading routes can then reference the area by its ID. Requires business:service-areas:create.",
        "operationId": "createServiceArea",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateServiceArea"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceArea"
                }
              }
            },
            "description": "Service area created"
          },
          "400": {
            "description": "Invalid service area"
          },
          "403": {
            "description": "Missing business:service-areas:create or invalid tenant context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a utility service area",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:service-areas:create"
        ]
      }
    },
    "$BUSINESS_API/service-indicators": {
      "get": {
        "description": "Computes the tenant's service performance indicators for a year or one quarter: continuity of service, collection efficiency, billing efficiency, water quality compliance and staff per 1,000 active connections. Each indicator carries its formula, numerator, denominator and coverage, or the reason it could not be computed. A period still running is cut at the current time, and a period that has not started returns 400. Requires reports:read.",
        "operationId": "getServiceIndicators",
        "parameters": [
          {
            "description": "Required calendar year to report on, from 2000 to 2100.",
            "in": "query",
            "name": "year",
            "required": true,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Optional quarter of the year, 1 to 4; when omitted the whole year is reported.",
            "in": "query",
            "name": "quarter",
            "required": false,
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Optional staff headcount for the period, a whole number of 0 or more, used only for the staff per 1,000 active connections indicator; without it that indicator is reported as missing.",
            "in": "query",
            "name": "staff_headcount",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceIndicatorReport"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Utility service indicators for operational, commercial, and water-quality performance over a year or quarter, with formulas and data coverage",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      }
    },
    "$BUSINESS_API/service-request-decline-reasons": {
      "get": {
        "description": "Returns the reasons staff can choose when declining a new connection service request, each with a code, label, active flag and position. While the tenant has not saved its own list, the built-in template is returned and customized is false. Requires the connections:read permission.",
        "operationId": "getServiceRequestDeclineReasons",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeclineReasonList"
                }
              }
            },
            "description": "Decline reasons"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the tenant's decline reasons, or the template it starts from",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      },
      "put": {
        "description": "1 to 30 reasons with unique codes and labels; at least one active. Deactivate a reason to retire it.",
        "operationId": "updateServiceRequestDeclineReasons",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reasons": {
                    "items": {
                      "$ref": "#/components/schemas/DeclineReason"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "reasons"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeclineReasonList"
                }
              }
            },
            "description": "Saved reasons"
          },
          "400": {
            "description": "Invalid list"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace the tenant's decline reasons",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/service-requests": {
      "get": {
        "description": "Returns the service requests submitted to the caller's tenant, newest-first pages of at most 100 items (20 by default) driven by limit and the after cursor. Before each item is returned its quote state is brought up to date, so a quote whose validity has passed shows as expired and a paid quote moves the request forward. Requires the connections:read permission.",
        "operationId": "listServiceRequests",
        "parameters": [
          {
            "description": "Returns only requests in this exact status (submitted, accepted, declined, withdrawn, visit_scheduled, quoted, payment_pending, scheduled or completed); omit it to list requests in every status.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "submitted",
                "accepted",
                "declined",
                "withdrawn"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequestPage"
                }
              }
            },
            "description": "Service requests of the authenticated utility tenant"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the utility's service request queue",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}": {
      "get": {
        "description": "Returns one request from the tenant's queue together with its current quote, its site visit and, once accepted, the connection created for it. The quote state is refreshed on read, so an overdue quote is marked expired and a settled one advances the request. Returns 404 when the ID does not belong to the caller's tenant; requires connections:read.",
        "operationId": "getServiceRequest",
        "parameters": [
          {
            "description": "ID of the service request in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "Service request"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a service request of the utility's queue",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}/accept": {
      "post": {
        "description": "Creates the customer and premise from the request under the caller's own permissions (business:customers:create, business:properties:create) and files a connection application (connections:write). A retry reuses a customer already created.",
        "operationId": "acceptServiceRequest",
        "parameters": [
          {
            "description": "ID of the open service request in the caller's tenant to accept.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AcceptServiceRequestInput"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "Accepted request with customer_id, property_id and connection_id"
          },
          "400": {
            "description": "The request is no longer open or the input is invalid"
          },
          "403": {
            "description": "The utility principal lacks the permissions above"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept a service request",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}/decline": {
      "post": {
        "description": "The reason and note are shown to the requester only, never on the public status lookup.",
        "operationId": "declineServiceRequest",
        "parameters": [
          {
            "description": "ID of the open service request in the caller's tenant to decline.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclineServiceRequestInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "Declined request"
          },
          "400": {
            "description": "Reason not active in the tenant's list",
            "note too long": null,
            "or the request is no longer open": null
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Decline a service request with a reason from the list",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}/quote-prices": {
      "get": {
        "description": "Fixed components of the active tariff for the request's category whose accounting role is connection_fee, connection_material or connection_labour (RFC 0104 §7.1). Empty when the tenant has priced none; staff can still write free lines with a reason.",
        "operationId": "getServiceRequestQuotePrices",
        "parameters": [
          {
            "description": "ID of the service request whose category selects the tariff prices.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QuotePriceList"
                }
              }
            },
            "description": "Price catalogue"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the tariff prices a request's quote can use",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}/quotes": {
      "get": {
        "description": "Returns every quote issued on the request, including superseded, expired and cancelled versions, in a data array without pagination. The request's quote state is refreshed first, so an overdue quote appears as expired. Returns 404 when the request is not in the caller's tenant; requires connections:read.",
        "operationId": "getServiceRequestQuotes",
        "parameters": [
          {
            "description": "ID of the service request whose quote versions are listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceQuoteList"
                }
              }
            },
            "description": "Quote versions, newest first"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List every version of a request's quote",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      },
      "post": {
        "description": "Lines come from the tariff catalogue (price key) or are free lines with their own price. A catalogue price changed, or a free line, needs adjustment_reason. The open version is superseded and stays visible; the request becomes quoted.",
        "operationId": "issueServiceRequestQuote",
        "parameters": [
          {
            "description": "ID of the service request to quote; it must be in a status that still accepts a quote.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IssueQuoteInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceQuote"
                }
              }
            },
            "description": "Issued quote"
          },
          "400": {
            "description": "Invalid lines or validity",
            "or the request can no longer be quoted": null
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a quote, or a revised version, on a request",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}/site-visits": {
      "post": {
        "description": "A visit still to happen is cancelled and an unanswered quote superseded; the request becomes visit_scheduled.",
        "operationId": "bookServiceRequestSiteVisit",
        "parameters": [
          {
            "description": "ID of the service request the site visit is booked for.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookSiteVisitInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteVisit"
                }
              }
            },
            "description": "Booked visit"
          },
          "400": {
            "description": "Day not offered",
            "or the request needs no visit": null
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Book, or move, a site visit for a request still being priced",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/service-requests/{id}/visit-slots": {
      "get": {
        "description": "The next working days from tomorrow in the tenant calendar; weekends and holidays are skipped.",
        "operationId": "getServiceRequestVisitSlots",
        "parameters": [
          {
            "description": "ID of the service request a visit slot is being chosen for.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitSlots"
                }
              }
            },
            "description": "Offered days"
          },
          "403": {
            "description": "The utility principal lacks connections:read"
          },
          "404": {
            "description": "Request not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the working days a site visit can be booked on",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "connections:read"
        ]
      }
    },
    "$BUSINESS_API/siem": {
      "get": {
        "description": "Returns every destination that receives the caller's tenant audit events in real time, wrapped in a destinations array (not paged). Credentials are never returned; the has_auth_header, has_secret and has_aws_secret flags report which are stored. Requires audit:read.",
        "operationId": "getSiemDestinations",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditSiemDestinationList"
                }
              }
            },
            "description": "Audit event destinations"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Show the tenant's audit event destinations",
        "x-roles": [
          "admin",
          "analyst",
          "owner"
        ],
        "x-scopes": [
          "audit:read"
        ]
      },
      "post": {
        "description": "Creates a destination that receives each new audit event of the caller's tenant. provider defaults to webhook and format to cloudevents (cef is the alternative). name is required and endpoint_url must be a public https address; cloudwatch also needs region, log_group, log_stream and both access keys (endpoint_url then defaults to the regional logs endpoint), and elastic needs index. auth_header, secret and aws_secret_access_key are write-only: they are encrypted at rest and never returned. Unknown fields or a failed validation return 400. Requires audit:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "createSiemDestination",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AuditSiemDestinationCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditSiemDestination"
                }
              }
            },
            "description": "Destination created, without credentials"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a destination for real-time audit events",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "audit:manage"
        ]
      }
    },
    "$BUSINESS_API/siem/{id}": {
      "delete": {
        "description": "Deletes the destination with this id from the caller's tenant; events are no longer delivered to it. The call is idempotent and returns 204 for an unknown id. Requires audit:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "deleteSiemDestination",
        "parameters": [
          {
            "description": "Identifier of the destination to remove (sie_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Destination removed"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove an audit event destination",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "audit:manage"
        ]
      },
      "get": {
        "description": "Returns one destination of the caller's tenant, without credentials. Requires audit:read; an unknown id returns 404.",
        "operationId": "getSiemDestination",
        "parameters": [
          {
            "description": "Identifier of the destination (sie_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditSiemDestination"
                }
              }
            },
            "description": "The destination"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Destination not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one audit event destination",
        "x-roles": [
          "admin",
          "analyst",
          "owner"
        ],
        "x-scopes": [
          "audit:read"
        ]
      }
    },
    "$BUSINESS_API/siem/{id}/test": {
      "post": {
        "description": "Delivers a synthetic siem.connection.test event to the destination with its stored credentials and format and waits for the receiver to accept it. A refused or failed delivery returns 400. Takes no request body. Requires audit:manage; an unknown id returns 404. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "testSiemDestination",
        "parameters": [
          {
            "description": "Identifier of the destination to test (sie_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditSiemTestResult"
                }
              }
            },
            "description": "The destination accepted the test event"
          },
          "400": {
            "description": "The destination did not accept the test event (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Destination not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send a test event to an audit event destination",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "audit:manage"
        ]
      }
    },
    "$BUSINESS_API/site-visits/{id}/cancel": {
      "post": {
        "description": "Marks a scheduled site visit as cancelled and records when. If the request was waiting on this visit (status visit_scheduled), it returns to accepted when a connection already exists, or to submitted otherwise. A visit that is already completed or cancelled is rejected with 400, and a concurrent change to the visit returns 409; requires connections:write.",
        "operationId": "cancelSiteVisit",
        "parameters": [
          {
            "description": "ID of the scheduled site visit in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteVisit"
                }
              }
            },
            "description": "Cancelled visit"
          },
          "400": {
            "description": "The visit is no longer scheduled"
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Visit not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Cancel a site visit still to happen",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/site-visits/{id}/complete": {
      "post": {
        "description": "With quote lines, the revised quote is issued from the outcome at once; otherwise the request awaits a quote.",
        "operationId": "completeSiteVisit",
        "parameters": [
          {
            "description": "ID of the scheduled site visit in the caller's tenant to record as completed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteSiteVisitInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteVisit"
                }
              }
            },
            "description": "Completed visit, with quote_id when a quote was issued"
          },
          "400": {
            "description": "Missing outcome",
            "invalid quote lines": null,
            "or the visit is no longer scheduled": null
          },
          "403": {
            "description": "The utility principal lacks connections:write"
          },
          "404": {
            "description": "Visit not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record what a site visit found",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "connections:write"
        ]
      }
    },
    "$BUSINESS_API/sso": {
      "get": {
        "description": "Returns the caller's tenant SAML or OpenID Connect connection, or a JSON null body with 200 when none is configured. The OIDC client secret and the service provider private key are never returned; has_client_secret reports whether a secret is stored, and domain_verification_token is the value to publish in DNS before verifying the domain. Requires business:team:read (owner and admin roles hold it).",
        "operationId": "getSsoConnection",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/EnterpriseSsoConnection"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            },
            "description": "The connection, or null when none is configured"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the tenant's single sign-on connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      },
      "put": {
        "description": "Saves the caller's tenant single sign-on settings, creating the connection on first use; a tenant has one connection. provider_type is saml or oidc and domain must be a valid hostname. For oidc, discovery_url and client_id are required, plus client_secret unless one is already stored; for saml, idp_entity_id, idp_sso_url and a valid X.509 idp_certificate are required, and a service provider key pair is generated on first save. URLs must be public https addresses. Roles must be tenant roles and the owner role cannot be granted through federation. Changing the domain clears its verification. client_secret is write-only and is never echoed. Requires business:team:manage; invalid input returns 400 and a domain already claimed by another connection returns 409. The change is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "saveSsoConnection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseSsoConnectionInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSsoConnection"
                }
              }
            },
            "description": "The saved connection, without secrets"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "409": {
            "description": "The domain is already claimed by another connection"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create or replace the tenant's single sign-on connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/sso/saml/metadata": {
      "post": {
        "description": "Parses a SAML identity provider metadata document and returns the entity ID, single sign-on URL, optional single logout URL and signing certificate, ready to send in a save request. Nothing is stored. A document that is empty, larger than 1 MiB, not well-formed or without an IDPSSODescriptor returns 400. Requires business:team:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "parseSsoSamlMetadata",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseSamlMetadataRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSamlIdpSettings"
                }
              }
            },
            "description": "Settings found in the metadata"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Extract SAML settings from identity provider metadata",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/sso/test": {
      "post": {
        "description": "Runs live checks against the caller's tenant identity provider (OIDC discovery, or the SAML endpoints and certificate) and reports each check, starting with whether the domain is verified; valid is true only when all pass. Failed checks are reported in the body with status 200. Takes no request body. Returns 404 when no connection is configured. Requires business:team:manage. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "testSsoConnection",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSsoTestResult"
                }
              }
            },
            "description": "Check results"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No single sign-on connection is configured"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Probe the configured identity provider",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/sso/verify-domain": {
      "post": {
        "description": "Looks up the DNS TXT record for the connection's domain and, when it contains the connection's domain_verification_token, marks the domain verified and claims it for the tenant. Until verified, the domain cannot be enforced or used to route sign-ins or SCIM provisioning. A missing or wrong record returns 400 with a detail naming the record and value to publish; a domain already verified by another tenant returns 409; no connection returns 404. Takes no request body. Requires business:team:manage. The verification is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "verifySsoDomain",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSsoConnection"
                }
              }
            },
            "description": "The connection with domain_verified_at set"
          },
          "400": {
            "description": "The DNS record was not found or does not match (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No single sign-on connection is configured"
          },
          "409": {
            "description": "The domain is already claimed by another connection"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Verify control of the connection's domain",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/sso/{id}": {
      "delete": {
        "description": "Deletes the single sign-on connection with this id from the caller's tenant. The call is idempotent: an id that does not match the tenant's connection still returns 204. Requires business:team:manage. The deletion is recorded in the audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "deleteSsoConnection",
        "parameters": [
          {
            "description": "Identifier of the tenant's single sign-on connection (sso_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Connection removed"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove the tenant's single sign-on connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/subscription": {
      "get": {
        "description": "Returns the tenant's platform subscription: its plan ID, status (for example trialing, active, past_due, suspended or cancelled), current billing period, trial end, and whether it is set to cancel at the period end. Plan limits are not embedded; read them from the plan the plan_id points to. Returns 404 when the tenant has no subscription; requires business:subscription:read.",
        "operationId": "getUtilitySubscription",
        "responses": {
          "200": {
            "description": "Active subscription and entitlement limits"
          },
          "403": {
            "description": "Missing business:subscription:read scope"
          },
          "404": {
            "description": "Utility subscription not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get utility's active platform SaaS subscription and entitlements",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/cancel": {
      "post": {
        "description": "With at_period_end set to true the subscription keeps running and is only flagged to cancel when the current period ends; with it false or omitted the subscription is cancelled at once. The body is optional and returns the updated subscription. The call does not check the current status, so repeating it is harmless; requires business:subscription:cancel.",
        "operationId": "cancelUtilitySubscription",
        "responses": {
          "200": {
            "description": "Cancellation recorded"
          },
          "403": {
            "description": "Missing business:subscription:cancel scope"
          },
          "404": {
            "description": "Utility subscription not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request cancellation of utility platform SaaS subscription",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:subscription:cancel"
        ]
      }
    },
    "$BUSINESS_API/subscription/change-plan": {
      "post": {
        "description": "Moves the tenant to plan_id immediately and, when the plans differ in price, adds a proration line for the unused part of the current period to the next platform invoice (a credit when moving to a cheaper plan). Trialing subscriptions, or calls after the period has ended, get no proration. Returns 409 when the subscription is cancelled or already on that plan, and 400 when plan_id is missing or the plans use different currencies; requires business:subscription:change.",
        "operationId": "changeSubscriptionPlan",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePlanResult"
                }
              }
            },
            "description": "Result with proration_cents (positive charges, negative credits)"
          },
          "400": {
            "description": "Invalid plan request"
          },
          "403": {
            "description": "Missing business:subscription:change scope"
          },
          "404": {
            "description": "Subscription or plan not found"
          },
          "409": {
            "description": "Plan change conflicts with the current subscription"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change plan now, prorating the difference onto the next invoice",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:subscription:change"
        ]
      }
    },
    "$BUSINESS_API/subscription/change-plan/preview": {
      "post": {
        "description": "Runs the same checks and proration calculation as a plan change and returns the from and to plan IDs, the proration amount in cents, the currency and the current period end, without changing the subscription or adding any invoice line. It fails the same way as the real change: 409 for a cancelled subscription or the current plan, 400 for a missing plan_id or a currency mismatch. Requires business:subscription:change.",
        "operationId": "previewSubscriptionPlanChange",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePlanPreview"
                }
              }
            },
            "description": "Preview with proration_cents (positive charges, negative credits)"
          },
          "400": {
            "description": "Invalid plan request"
          },
          "403": {
            "description": "Missing business:subscription:change scope"
          },
          "404": {
            "description": "Subscription or plan not found"
          },
          "409": {
            "description": "Plan change conflicts with the current subscription"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Compute the proration of a plan change without making it",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:subscription:change"
        ]
      }
    },
    "$BUSINESS_API/subscription/credits": {
      "get": {
        "description": "Returns every platform credit grant the tenant has received, together with balances in minor units. Only active, unexpired grants with something left count toward the balances, which are split into cash-funded and granted (promotional) credit plus their total. Requires business:billing:read.",
        "operationId": "getSubscriptionCredits",
        "responses": {
          "200": {
            "description": "Platform credit summary"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get utility platform credit balance and grants",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:billing:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/credits/redeem": {
      "post": {
        "description": "Looks up the campaign behind the code and creates a promotional credit grant for the tenant for the campaign's amount, expiring after the campaign's grant period when it sets one. The new credit is applied right away to the tenant's open platform invoices, and the grant is returned with 201. Returns 404 for an unknown code, 409 when the campaign is not active, its budget or redemption cap is used up, or the tenant has reached its per-tenant limit, and 400 when code is empty; requires business:billing:write.",
        "operationId": "redeemSubscriptionPromo",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Platform credit granted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Redeem a platform promotional code",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "business:billing:write"
        ]
      }
    },
    "$BUSINESS_API/subscription/invoices": {
      "get": {
        "description": "Returns the invoices the platform has issued to the caller's tenant for its subscription, in cursor pages (limit up to 100, 20 by default, with after for the next page). Requires business:subscription:read.",
        "operationId": "listSubscriptionInvoices",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only invoices in this status: open, paid or void; omit it for all invoices.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "open",
                "paid",
                "void"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformInvoicePage"
                }
              }
            },
            "description": "Invoices"
          },
          "403": {
            "description": "Missing business:subscription:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the utility's platform invoices",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/invoices/{id}": {
      "get": {
        "description": "Returns one platform invoice with its lines, totals and status. An invoice that belongs to another tenant answers 404 just like a missing one; requires business:subscription:read.",
        "operationId": "getSubscriptionInvoice",
        "parameters": [
          {
            "description": "ID of the platform invoice issued to the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformInvoice"
                }
              }
            },
            "description": "Invoice"
          },
          "403": {
            "description": "Missing business:subscription:read scope"
          },
          "404": {
            "description": "Invoice not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one platform invoice of the utility",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/invoices/{id}/payment-proofs": {
      "post": {
        "description": "Accepts a multipart form with the payment details and a file (PDF, JPEG or PNG) and stores a pending proof for the platform's billing staff to review. The invoice must belong to the tenant and be open (409 otherwise); amount_cents must be positive, method must be one of the payment methods enabled on the installation, reference is required (up to 128 characters), paid_on is a YYYY-MM-DD date not in the future, and note is limited to 500 characters. A second open proof with the same method and reference is rejected with 409; callers need business:subscription:change or payments:write.",
        "operationId": "submitSubscriptionPaymentProof",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "amount_cents": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "file": {
                    "format": "binary",
                    "type": "string"
                  },
                  "method": {
                    "description": "A method code from the invoice's payment_methods: the platform's configured payment methods.",
                    "type": "string"
                  },
                  "note": {
                    "maxLength": 500,
                    "type": "string"
                  },
                  "paid_on": {
                    "format": "date",
                    "type": "string"
                  },
                  "reference": {
                    "maxLength": 128,
                    "type": "string"
                  }
                },
                "required": [
                  "amount_cents",
                  "method",
                  "reference",
                  "paid_on",
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created; the proof waits for platform review"
          },
          "409": {
            "description": "The invoice is not open, or the reference was already sent"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send a proof of paying a platform subscription invoice (multipart: amount_cents, method, reference, paid_on, note, file)",
        "x-roles": [
          "admin",
          "billing_clerk",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "payments:write"
        ]
      }
    },
    "$BUSINESS_API/subscription/payment-instructions": {
      "get": {
        "description": "Returns, in a data array, the payment instructions configured by the platform operator (for example account numbers or payment codes) that a tenant uses to pay its platform invoices. The list is empty when none are configured. Requires business:subscription:read.",
        "operationId": "getSubscriptionPaymentInstructions",
        "responses": {
          "200": {
            "description": "OK"
          },
          "403": {
            "description": "Missing business:subscription:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "How to pay platform subscription invoices: bank accounts and mobile-money codes",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/payment-proofs": {
      "get": {
        "description": "Returns the proofs of payment the caller's tenant has sent for its platform invoices, with their review status, in cursor pages (limit up to 100, 20 by default, after for the next page). Requires business:subscription:read.",
        "operationId": "listSubscriptionPaymentProofs",
        "parameters": [
          {
            "description": "Returns only proofs sent for this platform invoice ID.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only proofs in this review status: pending, approved or rejected.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "approved",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the utility's proofs of payment to the platform",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/payment-proofs/{id}/file": {
      "get": {
        "description": "Streams the file attached to a proof with its stored content type and an inline Content-Disposition carrying the original file name. Returns 404 when the proof belongs to another tenant or its file is no longer in storage; requires business:subscription:read.",
        "operationId": "getSubscriptionPaymentProofFile",
        "responses": {
          "200": {
            "description": "The stored PDF, JPEG or PNG"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download one of the utility's proofs",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/subscription/usage": {
      "get": {
        "description": "Returns the tenant's plan code, its active connections and users, and the plan's limits on both. Active connections are those in status active, the same count billing and the connection limit use; a limit of 0 means none. Returns 404 when the tenant has no subscription. Requires business:subscription:read.",
        "operationId": "getSubscriptionUsage",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SubscriptionUsage"
                }
              }
            },
            "description": "Usage against the plan"
          },
          "404": {
            "description": "The tenant has no subscription"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get utility usage against the plan's limits",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:subscription:read"
        ]
      }
    },
    "$BUSINESS_API/tariff-templates": {
      "get": {
        "description": "The tariffs of the seed dataset for the utility's country, at the dataset's latest prices, as starting points, so a tariff never starts from a blank form and no tariff values live in clients. available is false with reason no_template_for_country or country_unset when there is none. Requires tariffs:read.",
        "operationId": "getTariffTemplates",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TariffTemplateCatalogue"
                }
              }
            },
            "description": "The templates"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Tariff templates for the utility's country"
      }
    },
    "$BUSINESS_API/tariff-templates/{templateID}/apply": {
      "post": {
        "description": "Creates the template's tariff through the billing service, optionally with another code or name and an effective date (default now), and activates it when activate is true. A template applied and activated in the real account completes the utility_real tariffs step. Returns the created tariff. Requires tariffs:write.",
        "operationId": "applyTariffTemplate",
        "parameters": [
          {
            "description": "Template ID from the list",
            "in": "path",
            "name": "templateID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TariffTemplateApply"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityTariff"
                }
              }
            },
            "description": "The created tariff"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid code, name or tariff"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No such template for the utility's country"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "A tariff with this code exists, or it cannot be activated now"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a tariff from a template"
      }
    },
    "$BUSINESS_API/tariffs": {
      "get": {
        "description": "Returns the tenant's tariff schedules in cursor pages (limit up to 100, 20 by default, after for the next page), including drafts and superseded versions unless filtered. A free-text q parameter narrows the list further. Requires tariffs:read.",
        "operationId": "listTariffs",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only tariffs for this customer category: residential, commercial, industrial, institutional or government.",
            "in": "query",
            "name": "category",
            "schema": {
              "enum": [
                "residential",
                "commercial",
                "industrial",
                "institutional",
                "government"
              ],
              "type": "string"
            }
          },
          {
            "description": "Returns only tariffs in this status: draft, active or superseded.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "draft",
                "active",
                "superseded"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/UtilityTariff"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data",
                    "has_more"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Tariffs in the utility tenant"
          },
          "403": {
            "description": "Missing tariffs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility billing tariffs",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "tariffs:read"
        ]
      },
      "post": {
        "description": "Creates the schedule in draft status; it has no effect on billing until it is activated. code and name are required, category defaults to residential, currency defaults to the tenant's currency, and effective_from defaults to now. Tiers, fixed charges and charge components are validated (contiguous tier volumes, positive amounts, no duplicate fixed charge per code and diameter) and a violation returns 400; requires tariffs:write.",
        "operationId": "createTariff",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateUtilityTariffRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityTariff"
                }
              }
            },
            "description": "Tariff schedule created"
          },
          "400": {
            "description": "Invalid tariff schedule"
          },
          "403": {
            "description": "Missing tariffs:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a new tariff schedule",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "tariffs:write"
        ]
      }
    },
    "$BUSINESS_API/tariffs/{id}": {
      "get": {
        "description": "Returns one tariff schedule with its tiers, fixed charges, charge components, taxes and effective dates. Returns 404 when the tariff is not in the caller's tenant; requires tariffs:read.",
        "operationId": "getUtilityTariff",
        "parameters": [
          {
            "description": "ID of the tariff in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityTariff"
                }
              }
            },
            "description": "Tariff in the authenticated tenant"
          },
          "403": {
            "description": "Missing tariffs:read scope"
          },
          "404": {
            "description": "Tariff not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a utility tariff schedule",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "finance",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "tariffs:read"
        ]
      }
    },
    "$BUSINESS_API/tariffs/{id}/activate": {
      "post": {
        "description": "Sets the tariff to active and bounds the tariff currently in force for the same category: if the new tariff is already effective, the old one is superseded now; if it is future-dated, the old one stays active until the new effective_from. A tariff.activated event is emitted, which also records the tariff's validity in the point-in-time history. The current status is not checked, so activating again re-applies the same changes; requires tariffs:write.",
        "operationId": "activateUtilityTariff",
        "parameters": [
          {
            "description": "ID of the tariff in the caller's tenant to activate.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityTariff"
                }
              }
            },
            "description": "Activated tariff in the authenticated tenant"
          },
          "403": {
            "description": "Missing tariffs:write scope"
          },
          "404": {
            "description": "Tariff not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate a tariff schedule",
        "x-roles": [
          "admin",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "tariffs:write"
        ]
      }
    },
    "$BUSINESS_API/tariffs/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata the tenant has stored on the tariff, as an entry with resource_type, resource_id and a metadata map. The tariff must exist in the caller's tenant (404 otherwise); requires business:metadata:read.",
        "operationId": "getBusinessTariffMetadata",
        "parameters": [
          {
            "description": "ID of the tariff in the caller's tenant, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a tariff",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the keys in the metadata object into what the tariff already has; keys not sent are kept, and a key sent with an empty string is removed. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and a resource holds at most 50 keys; violations return 400 with one entry per invalid key. Returns the full metadata after the merge; requires business:metadata:write.",
        "operationId": "putBusinessTariffMetadata",
        "parameters": [
          {
            "description": "ID of the tariff in the caller's tenant, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/team/invitations": {
      "get": {
        "description": "Returns invitations of the caller's current team (the utility tenant, or the organization when signed in as organization staff) in cursor pages using limit and after. Only pending invitations are returned unless a status query parameter asks for another; pending invitations past their expiry are reported as expired. Requires the team read permission of that context.",
        "operationId": "listUtilityTeamInvitations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamInvitationPage"
                }
              }
            },
            "description": "Invitations scoped to the authenticated utility or organization"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List invitations for the active utility or organization team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      },
      "post": {
        "description": "Sends a one-time invitation token by e-mail, or by text message when only phone is given, offering the listed roles in the caller's current team; the invitation expires after 7 days and replaces any earlier pending invitation for the same recipient. Only an owner can grant the owner role (403), an unknown role or missing e-mail and phone returns 400, someone who is already an active member returns 409, and 503 means the message could not be delivered, in which case the invitation is revoked. Requires the team manage permission and is recorded in the audit trail.",
        "operationId": "createUtilityTeamInvitation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTeamInvitation"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamInvitation"
                }
              }
            },
            "description": "Invitation for the authenticated utility or organization team"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "503": {
            "description": "The invitation could not be sent: no provider for the target, the public web URL is not configured, or the provider failed."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Invite a member to the active utility or organization team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/team/invitations/{id}": {
      "delete": {
        "description": "Marks a pending invitation of the caller's team as revoked so its token can no longer be used, and answers 204. Returns 404 when the invitation is not in this team and 409 when it is no longer pending; requires the team manage permission and is recorded in the audit trail.",
        "operationId": "revokeUtilityTeamInvitation",
        "responses": {
          "204": {
            "description": "Revoke a pending invitation scoped to the authenticated context"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a pending invitation from the active utility or organization team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/team/members": {
      "get": {
        "description": "Returns the active members of the caller's current team (the utility tenant or the organization) with their user details, roles, status and join date, in cursor pages using limit and after. Requires the team read permission of that context.",
        "operationId": "listUtilityTeamMembers",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamMemberPage"
                }
              }
            },
            "description": "Members scoped to the authenticated utility or organization"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List members of the active utility or organization team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      }
    },
    "$BUSINESS_API/team/members/{id}": {
      "delete": {
        "description": "Ends the member's membership in the caller's team, signs out every session tied to it, and answers 204. Only an owner may remove another owner (403), removing the last owner returns 409, and an unknown or inactive member returns 404. Requires the team manage permission and is recorded in the audit trail.",
        "operationId": "removeUtilityTeamMember",
        "responses": {
          "204": {
            "description": "Remove a member scoped to the authenticated context"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a member from the active utility or organization team (the last owner cannot be removed)",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/team/members/{id}/roles": {
      "patch": {
        "description": "Replaces the member's roles with the roles array and returns the updated member. The member's existing sessions are revoked so the new permissions take effect at the next sign-in. Only an owner may grant the owner role or demote an owner (403), demoting the last owner returns 409, and an unknown role returns 400; requires the team manage permission.",
        "operationId": "updateUtilityTeamMemberRoles",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTeamMemberRoles"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamMember"
                }
              }
            },
            "description": "Replace member roles scoped to the authenticated context; the last owner cannot be demoted"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace a member's roles in the active utility or organization team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      }
    },
    "$BUSINESS_API/team/members/{id}/sessions": {
      "delete": {
        "description": "Ends every device session the member holds in the caller's team, forcing a new sign-in, and returns the number ended as revoked. Only an owner may end an owner's sessions (403); an unknown member returns 404. Requires the team manage permission and is recorded in the audit trail.",
        "operationId": "revokeBusinessMemberSessions",
        "parameters": [
          {
            "description": "Membership ID of the team member whose sessions are ended.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RevokedCount"
                }
              }
            },
            "description": "End every session of a team member"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "End every session of a team member",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:manage"
        ]
      },
      "get": {
        "description": "Returns, in a data array, the live sessions the member holds in the caller's team, with device name, user agent, IP address, last activity, creation and expiry times. is_current marks the caller's own session. Returns 404 when the member is not active in this team; requires the team read permission.",
        "operationId": "getBusinessMemberSessions",
        "parameters": [
          {
            "description": "Membership ID of the team member, as returned by the members list.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionList"
                }
              }
            },
            "description": "List a team member sessions"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List a team member sessions",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      }
    },
    "$BUSINESS_API/team/roles": {
      "get": {
        "description": "Returns, in a data array, the role definitions that can be assigned in the caller's current team context, the same list used to validate invitations and role changes. Requires the team read permission.",
        "operationId": "getUtilityTeamRoles",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoleCatalog"
                }
              }
            },
            "description": "List the built-in roles of the utility context"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the built-in roles of the utility context",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:team:read"
        ]
      }
    },
    "$BUSINESS_API/temporal/meter-binding": {
      "get": {
        "description": "Answers which meter was bound to a connection at as_of_valid_time, as the system recorded it at as_of_system_time; both are RFC 3339 timestamps and default to now. Querying an earlier system time reproduces the answer given before a later correction. Returns 404 when no binding is valid at that moment and 400 for a missing connection_id or a malformed time; requires temporal:read.",
        "operationId": "getMeterBindingAsOf",
        "parameters": [
          {
            "description": "ID of the connection whose meter binding is looked up; required.",
            "in": "query",
            "name": "connection_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Defaults to now",
            "in": "query",
            "name": "as_of_valid_time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Defaults to now",
            "in": "query",
            "name": "as_of_system_time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemporalFact"
                }
              }
            },
            "description": "Binding"
          },
          "400": {
            "description": "Invalid subject or RFC 3339 timestamp"
          },
          "403": {
            "description": "Missing temporal:read scope"
          },
          "404": {
            "description": "No binding is valid at that time"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The meter bound to a connection at a valid and system time",
        "x-roles": [
          "admin",
          "analyst",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "temporal:read"
        ]
      }
    },
    "$BUSINESS_API/temporal/meter-bindings": {
      "get": {
        "description": "Returns every recorded binding row for the connection, including rows superseded by later corrections, each with its valid interval and system interval. Results are paged with limit (up to 100, 20 by default) and after. Returns 400 when connection_id is missing; requires temporal:read.",
        "operationId": "listMeterBindingHistory",
        "parameters": [
          {
            "description": "ID of the connection whose binding history is listed; required.",
            "in": "query",
            "name": "connection_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/TemporalFact"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "data",
                    "has_more"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Binding rows, newest system version first"
          },
          "400": {
            "description": "Invalid pagination cursor"
          },
          "403": {
            "description": "Missing temporal:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Full binding history including superseded corrections",
        "x-roles": [
          "admin",
          "analyst",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "temporal:read"
        ]
      },
      "post": {
        "description": "Records that meter_id was bound to connection_id from valid_from until valid_to (open-ended when omitted); an empty meter_id states the connection had no meter in that interval. Rows that overlap are superseded rather than deleted and their non-overlapping parts re-created, and repeating an assertion that is already true changes nothing. connection_id, valid_from and reason are required (400 otherwise); the created rows are returned in data with 201, and temporal:write is required.",
        "operationId": "correctMeterBinding",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "connection_id": {
                    "type": "string"
                  },
                  "meter_id": {
                    "type": "string"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "valid_from": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "valid_to": {
                    "format": "date-time",
                    "nullable": true,
                    "type": "string"
                  }
                },
                "required": [
                  "connection_id",
                  "meter_id",
                  "valid_from",
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created facts"
          },
          "400": {
            "description": "Invalid temporal assertion"
          },
          "403": {
            "description": "Missing temporal:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "State a binding over a valid interval, superseding what it overlaps",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "temporal:write"
        ]
      }
    },
    "$BUSINESS_API/temporal/property-ownership": {
      "get": {
        "description": "Answers which customer owned a property at a given valid time, as the system recorded it at a given system time. Ownership rows are written from property transfer events, so a later correction never hides the earlier answer when you query an earlier system time. Returns 404 when no owner is recorded for that moment and 400 for a missing property_id or a malformed time; requires temporal:read.",
        "operationId": "getPropertyOwnershipAsOf",
        "parameters": [
          {
            "description": "ID of the property whose owner is looked up; required.",
            "in": "query",
            "name": "property_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp of the real-world moment to ask about; defaults to now.",
            "in": "query",
            "name": "as_of_valid_time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp of what the system believed at that moment, used to reproduce past answers; defaults to now.",
            "in": "query",
            "name": "as_of_system_time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemporalFact"
                }
              }
            },
            "description": "Ownership fact"
          },
          "400": {
            "description": "Invalid subject or RFC 3339 timestamp"
          },
          "403": {
            "description": "Missing temporal:read scope"
          },
          "404": {
            "description": "No fact is valid at that time"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The owner of a property at a point in time",
        "x-roles": [
          "admin",
          "analyst",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "temporal:read"
        ]
      }
    },
    "$BUSINESS_API/temporal/tariff-validity": {
      "get": {
        "description": "Answers which tariff was in force for a customer category at a given valid time, as the system recorded it at a given system time. Validity rows are written when tariffs are activated, so this shows the tariff a bill period should have used. Returns 404 when no tariff was in force at that moment and 400 for a missing category or a malformed time; requires temporal:read.",
        "operationId": "getTariffValidityAsOf",
        "parameters": [
          {
            "description": "Customer category to look up, such as residential, commercial, industrial, institutional or government; required.",
            "in": "query",
            "name": "category",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp of the moment the tariff should be in force; defaults to now.",
            "in": "query",
            "name": "as_of_valid_time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 timestamp of what the system believed at that moment, used to reproduce past answers; defaults to now.",
            "in": "query",
            "name": "as_of_system_time",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TemporalFact"
                }
              }
            },
            "description": "Tariff validity fact"
          },
          "400": {
            "description": "Invalid subject or RFC 3339 timestamp"
          },
          "403": {
            "description": "Missing temporal:read scope"
          },
          "404": {
            "description": "No fact is valid at that time"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The tariff in force for a category at a point in time",
        "x-roles": [
          "admin",
          "analyst",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "temporal:read"
        ]
      }
    },
    "$BUSINESS_API/tenant": {
      "get": {
        "description": "Returns the caller's tenant record: ID, slug, name, status, kind, workspace state, country, locale, currency and timezone, the owning organization, and any template or closure dates. Requires business:organization:read.",
        "operationId": "getBusinessTenant",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tenant"
                }
              }
            },
            "description": "Tenant configuration"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get tenant configuration for the authenticated utility",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/tenant/organization-links/pending": {
      "get": {
        "description": "Returns the requests from organizations to link this tenant that are still waiting for a decision, so an owner can approve or reject them. Only a utility staff member holding the owner role can call it; anyone else receives 403.",
        "operationId": "getPendingOrganizationLinkConsents",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/OrganizationTenantLink"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Pending organization link requests for the authenticated tenant"
          },
          "403": {
            "description": "Authenticated tenant owner required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List organization link requests awaiting this tenant owner's consent",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/tenant/organization-template-adoptions": {
      "get": {
        "description": "Returns every template adoption recorded for the caller's tenant, with its state (pending_acceptance, active or detached), version and organization. Only utility staff with business:organization:read can call it.",
        "operationId": "listTenantOrganizationTemplateAdoptions",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/OrganizationTemplateAdoption"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Pending and active organization template adoptions for the authenticated tenant"
          },
          "403": {
            "description": "Business organization read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List template adoptions requested for this account",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/tenant/organization-templates": {
      "get": {
        "description": "Returns the published templates of the organization that administers this tenant, taken from the active organization link or else the owning organization. The list is empty when the tenant has neither. Only utility staff with business:organization:read can call it.",
        "operationId": "listAvailableOrganizationTemplates",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/OrganizationTemplate"
                  },
                  "type": "array"
                }
              }
            },
            "description": "Published templates available for explicit adoption"
          },
          "403": {
            "description": "Business organization read scope required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List published templates from the account's administrative organization",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/tenant/organization-templates/{templateID}": {
      "delete": {
        "description": "Moves an active adoption to detached and records the time, so later versions of the template are no longer tied to this tenant. Only a tenant owner can call it (403 otherwise); 404 when the tenant has no adoption of that template and 409 when the adoption is not active. The action is written to the organization's audit trail.",
        "operationId": "detachOrganizationTemplateAdoption",
        "parameters": [
          {
            "description": "ID of the organization template whose adoption is detached.",
            "in": "path",
            "name": "templateID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTemplateAdoption"
                }
              }
            },
            "description": "Adoption detached; copied account settings are retained"
          },
          "403": {
            "description": "Account owner required"
          },
          "404": {
            "description": "Active adoption not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Detach the account from a shared template while keeping copied settings",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/tenant/organization-templates/{templateID}/accept": {
      "post": {
        "description": "Applies the template's settings to the caller's tenant and marks the adoption active. Accepting an adoption that is already active returns it unchanged; one that is detached returns 409, and 404 is returned when the template has been changed or unpublished since the adoption was requested. Only a tenant owner can call it, and the acceptance is written to the organization's audit trail.",
        "operationId": "acceptOrganizationTemplateAdoption",
        "parameters": [
          {
            "description": "ID of the organization template whose pending adoption is accepted.",
            "in": "path",
            "name": "templateID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationTemplateAdoption"
                }
              }
            },
            "description": "Template copied and adoption recorded"
          },
          "403": {
            "description": "Account owner required"
          },
          "404": {
            "description": "Pending adoption not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept and apply a pending organization template as the account owner",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/tickets": {
      "get": {
        "description": "Returns the tenant's support tickets in cursor pages (limit up to 100, 20 by default, after for the next page). Query parameters customer_id, account_id, category, status and assigned_to filter exactly, and q searches ticket text and matching account holders. Requires support:read.",
        "operationId": "listSupportTickets",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SupportTicketPage"
                }
              }
            },
            "description": "Support tickets"
          },
          "403": {
            "description": "Missing support:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List support tickets and service requests",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "support:read"
        ]
      },
      "post": {
        "description": "Requires support:write. customer_id and account_id must be records of this utility; a ticket naming an account is visible to consumers linked to that account.",
        "operationId": "createSupportTicket",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "account_id": {
                    "type": "string"
                  },
                  "category": {
                    "type": "string"
                  },
                  "customer_id": {
                    "type": "string"
                  },
                  "description": {
                    "type": "string"
                  },
                  "priority": {
                    "type": "string"
                  },
                  "subject": {
                    "type": "string"
                  }
                },
                "required": [
                  "subject",
                  "description"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Support ticket created"
          },
          "400": {
            "description": "Missing fields, or a customer or account that is not this utility's"
          },
          "403": {
            "description": "Missing support:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Open a support ticket, optionally on behalf of a customer",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "support:write"
        ]
      }
    },
    "$BUSINESS_API/tickets/{id}": {
      "get": {
        "description": "Returns one ticket with its subject, description, category, priority, status, assignee and resolution. Returns 404 when the ticket is not in the caller's tenant; requires support:read.",
        "operationId": "getSupportTicket",
        "parameters": [
          {
            "description": "ID of the support ticket in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Support ticket details"
          },
          "403": {
            "description": "Missing support:read"
          },
          "404": {
            "description": "Ticket not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get support ticket details",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "support:read"
        ]
      }
    },
    "$BUSINESS_API/tickets/{id}/assign": {
      "post": {
        "description": "Sets assigned_to on the ticket to the given staff user ID and, if the ticket was open, moves it to in_progress. The assignee is not validated, and an empty value clears the assignment. Returns 404 for an unknown ticket; requires support:write.",
        "operationId": "assignSupportTicket",
        "parameters": [
          {
            "description": "ID of the support ticket in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Support ticket assigned"
          },
          "403": {
            "description": "Missing support:write"
          },
          "404": {
            "description": "Ticket not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Assign support ticket to agent",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "support:write"
        ]
      }
    },
    "$BUSINESS_API/tickets/{id}/close": {
      "post": {
        "description": "Sets the ticket status to closed and returns it. The current status is not checked, so any ticket, resolved or not, can be closed and the call can be repeated. Returns 404 for an unknown ticket; requires support:write.",
        "operationId": "closeSupportTicket",
        "parameters": [
          {
            "description": "ID of the support ticket in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Support ticket closed"
          },
          "403": {
            "description": "Missing support:write"
          },
          "404": {
            "description": "Ticket not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Close support ticket",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "support:write"
        ]
      }
    },
    "$BUSINESS_API/tickets/{id}/comments": {
      "get": {
        "description": "Returns the comments on the ticket, from staff and from the customer, each marked with its author type, in cursor pages using limit (up to 100, 20 by default) and after. Returns 404 when the ticket is not in the caller's tenant; requires support:read.",
        "operationId": "listSupportTicketComments",
        "parameters": [
          {
            "description": "ID of the support ticket whose comments are listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Comments"
          },
          "403": {
            "description": "Missing support:read"
          },
          "404": {
            "description": "Ticket not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List comments on support ticket",
        "x-roles": [
          "admin",
          "analyst",
          "customer_service",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "support:read"
        ]
      },
      "post": {
        "description": "Adds a staff comment with the given content to the ticket and updates the ticket's last-changed time; the ticket status is not changed. content is required (400 when empty) and the ticket must be in the caller's tenant (404 otherwise). Requires support:read and support:write.",
        "operationId": "addSupportTicketComment",
        "parameters": [
          {
            "description": "ID of the support ticket being commented on.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Comment added"
          },
          "403": {
            "description": "Missing support:write"
          },
          "404": {
            "description": "Ticket not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add comment to support ticket",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "support:write"
        ]
      }
    },
    "$BUSINESS_API/tickets/{id}/metadata": {
      "get": {
        "description": "Returns the free-form key-value metadata the tenant has stored on the ticket, as an entry with resource_type, resource_id and a metadata map. The ticket must exist in the caller's tenant (404 otherwise); requires business:metadata:read.",
        "operationId": "getBusinessTicketMetadata",
        "parameters": [
          {
            "description": "ID of the support ticket in the caller's tenant, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a ticket",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the keys in the metadata object into what the ticket already has; keys not sent are kept, and a key sent with an empty string is removed. Keys must be non-blank, at most 40 characters, without square brackets or control characters, values at most 500 characters, and a resource holds at most 50 keys; violations return 400 with one entry per invalid key. Returns the full metadata after the merge; requires business:metadata:write.",
        "operationId": "putBusinessTicketMetadata",
        "parameters": [
          {
            "description": "ID of the support ticket in the caller's tenant, at most 120 characters.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/tickets/{id}/resolve": {
      "post": {
        "description": "Sets the ticket to resolved, stores the resolution text from the body and records the resolution time. The current status is not checked, so a closed ticket can be resolved again and the resolution overwritten. Returns 404 for an unknown ticket; requires support:write.",
        "operationId": "resolveSupportTicket",
        "parameters": [
          {
            "description": "ID of the support ticket in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Support ticket resolved"
          },
          "403": {
            "description": "Missing support:write"
          },
          "404": {
            "description": "Ticket not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Resolve support ticket",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "support:write"
        ]
      }
    },
    "$BUSINESS_API/topology/balance/dma/{id}": {
      "get": {
        "description": "Read-only. Inflow comes from the DMA's inflow device, outflow is authorised consumption (billed plus unbilled metered) plus metered export. Check status before trusting the loss figure.",
        "operationId": "getDMABalance",
        "parameters": [
          {
            "description": "ID of the district metered area (DMA) to balance; it must belong to the caller's tenant, and the window comes from the required from and to parameters (RFC 3339 instants or YYYY-MM-DD dates read as midnight UTC, at most 366 days apart).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 instant or date",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC 3339 instant or date; at most 366 days after from",
            "in": "query",
            "name": "to",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DMABalance"
                }
              }
            },
            "description": "Balance"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Compute a DMA water balance over [from, to)",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/topology/balance/dma/{id}/ledger": {
      "post": {
        "description": "A changed result is appended as a new revision; an unchanged retry returns the existing row.",
        "operationId": "recordDMABalance",
        "parameters": [
          {
            "description": "ID of the district metered area (DMA) whose balance is computed and written to the ledger; the DMA must have a dma_inlet node to book the entry against, otherwise the request fails with 409.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "from": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "to": {
                    "format": "date-time",
                    "type": "string"
                  }
                },
                "required": [
                  "from",
                  "to"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MassBalanceEntry"
                }
              }
            },
            "description": "Ledger row"
          },
          "409": {
            "description": "The balance is not complete or the DMA has no inlet node"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a closed period's balance in the immutable ledger",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/topology/balance/ledger": {
      "get": {
        "description": "Returns the immutable mass balance ledger entries recorded for the tenant, newest first, with cursor pagination (limit defaults to 20, maximum 100; pass next_cursor as after). A restated period appears as a new entry with a higher revision, because entries are never changed. Requires network read access.",
        "operationId": "listMassBalanceLedger",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only entries booked against this topology node ID, normally a DMA's dma_inlet node; an exact match, omitted for all nodes.",
            "in": "query",
            "name": "node_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only entries recorded for this district metered area ID; an exact match, omitted for all DMAs.",
            "in": "query",
            "name": "dma_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/MassBalanceEntry"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Ledger rows"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List mass balance ledger rows, newest first",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/topology/links": {
      "get": {
        "description": "Lists the directed links (pipes, mains and valves) of the tenant's network topology, newest first, with cursor pagination (limit defaults to 20, maximum 100). Filters combine with AND, and an unknown filter value returns an empty page rather than an error. Requires network read access.",
        "operationId": "listTopologyLinks",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Matches either endpoint",
            "in": "query",
            "name": "node_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only links of this type: gravity_main, pumping_main, distribution_pipe or control_valve.",
            "in": "query",
            "name": "link_type",
            "schema": {
              "$ref": "#/components/schemas/LinkType"
            }
          },
          {
            "description": "Returns only links in this operating state: open, closed or throttled.",
            "in": "query",
            "name": "status",
            "schema": {
              "$ref": "#/components/schemas/LinkStatus"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/TopologyLink"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Links"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List network graph links",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "post": {
        "description": "Adds a directed flow link from from_node_id to to_node_id; both must be existing topology nodes of the tenant (404 otherwise). link_code, from_node_id, to_node_id and a valid link_type are required; status defaults to open, roughness_coefficient defaults to the standard value, and lengths, diameters and roughness must not be negative. The topology must stay acyclic, so a self-loop or a link that would close a cycle is refused with 409, as is a duplicate link code; asset_id, when given, must reference an existing network asset. Requires network write access and returns 201 with the link.",
        "operationId": "createTopologyLink",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateLinkRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopologyLink"
                }
              }
            },
            "description": "Link"
          },
          "404": {
            "description": "An endpoint node does not exist in this tenant"
          },
          "409": {
            "description": "The link would create a cycle, or its code is taken"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a directed link; a link closing a loop is refused",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/topology/links/{id}": {
      "delete": {
        "description": "Permanently removes a link from the tenant's topology and returns 204 with no body. Traces and valve isolation results stop using the link immediately; nodes at either end are kept. Responds 404 when the link does not exist and requires network write access.",
        "operationId": "deleteTopologyLink",
        "parameters": [
          {
            "description": "ID of the topology link to delete (lnk_ prefix).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a link",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      },
      "get": {
        "description": "Returns one topology link of the caller's tenant with its endpoints, type, hydraulic attributes, status and linked asset. Responds 404 when the link does not exist in the tenant. Requires network read access.",
        "operationId": "getTopologyLink",
        "parameters": [
          {
            "description": "ID of the topology link (lnk_ prefix) in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopologyLink"
                }
              }
            },
            "description": "Link"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a link",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "put": {
        "description": "A link's endpoints are permanent.",
        "operationId": "updateTopologyLink",
        "parameters": [
          {
            "description": "ID of the topology link to update (lnk_ prefix); only the fields present in the body change, and the endpoints cannot be changed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateLinkRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopologyLink"
                }
              }
            },
            "description": "Updated link"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a link",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/topology/nodes": {
      "get": {
        "description": "Lists the network assets that are topology nodes in the tenant, newest first, with cursor pagination (limit defaults to 20, maximum 100). Assets that are not part of the topology are left out. Filters combine with AND and requires network read access.",
        "operationId": "listTopologyNodes",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only nodes of this type: source_river, source_borehole, treatment_plant, reservoir, dma_inlet, junction or customer_tap.",
            "in": "query",
            "name": "node_type",
            "schema": {
              "$ref": "#/components/schemas/NodeType"
            }
          },
          {
            "description": "Returns only nodes assigned to this service area ID; an exact match.",
            "in": "query",
            "name": "service_area_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only nodes that belong to this district metered area ID; an exact match.",
            "in": "query",
            "name": "dma_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Free-text search matched as a substring against the node's name or code.",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/TopologyNode"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Nodes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List network graph nodes",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "post": {
        "description": "Creates a topology node, either as a new network asset (node_code required, name defaults to the code) or by promoting an existing asset given in asset_id, whose asset type must match the node type. A dma_inlet node needs a dma_id, and each DMA may have only one inlet, so a second one is refused with 409, as is promoting an asset that is already a node. The node starts operational unless active is false, and storage_capacity_m3 must not be negative. Requires network write access and returns 201.",
        "operationId": "createTopologyNode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateNodeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopologyNode"
                }
              }
            },
            "description": "Node"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a graph node, or give an existing asset a graph role with asset_id",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/topology/nodes/{id}": {
      "delete": {
        "description": "Deletes a topology node and its underlying network asset, returning 204 with no body. The node must have no links in either direction and no mass balance ledger history; otherwise the request fails with 409, so remove its links first. Responds 404 when the ID is not a topology node in the tenant and requires network write access.",
        "operationId": "deleteTopologyNode",
        "parameters": [
          {
            "description": "ID of the topology node to delete, which is its network asset ID (ast_ prefix).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          },
          "409": {
            "description": "The node still has links or ledger history"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Delete a node with no links and no ledger history",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      },
      "get": {
        "description": "Returns one topology node with its type, location, elevation, storage capacity, DMA, linked meter and device, and active flag. An asset that exists but is not a topology node responds 404, like a missing one. Requires network read access.",
        "operationId": "getTopologyNode",
        "parameters": [
          {
            "description": "ID of the topology node, which is the ID of its network asset (ast_ prefix).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopologyNode"
                }
              }
            },
            "description": "Node"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a graph node",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      },
      "put": {
        "description": "node_code and node_type are permanent.",
        "operationId": "updateTopologyNode",
        "parameters": [
          {
            "description": "ID of the topology node to update, which is its network asset ID (ast_ prefix); the node type cannot be changed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateNodeRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TopologyNode"
                }
              }
            },
            "description": "Updated node"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a graph node",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "network:write"
        ]
      }
    },
    "$BUSINESS_API/topology/trace/downstream": {
      "get": {
        "description": "Follows the flow direction from a start node and returns every node it reaches with its depth in links from the start, plus the links traversed; the start node itself is not listed. By default closed links and inactive nodes stop the trace. Responds 400 when node_id is missing and 404 when it is not a topology node; requires network read access.",
        "operationId": "traceDownstream",
        "parameters": [
          {
            "description": "Required ID of the topology node to start the trace from.",
            "in": "query",
            "name": "node_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Boolean (true or false, default false); when true the trace also passes through closed links and continues past inactive nodes, showing what the network reaches once valves are opened.",
            "in": "query",
            "name": "include_closed",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TraceResult"
                }
              }
            },
            "description": "Trace"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Nodes and links fed by a node",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/topology/trace/upstream": {
      "get": {
        "description": "Walks against the flow direction from a start node to find what feeds it, returning each reached node with its depth in links and the links traversed; the start node itself is not listed. By default closed links and inactive nodes stop the trace. Responds 400 when node_id is missing and 404 when it is not a topology node; requires network read access.",
        "operationId": "traceUpstream",
        "parameters": [
          {
            "description": "Required ID of the topology node to trace back from.",
            "in": "query",
            "name": "node_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Boolean (true or false, default false); when true the trace also passes through closed links and continues past inactive nodes.",
            "in": "query",
            "name": "include_closed",
            "schema": {
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TraceResult"
                }
              }
            },
            "description": "Trace"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Nodes and links feeding a node",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/topology/trace/valve-isolation": {
      "get": {
        "description": "Compares network-wide supply before and after, so a node fed by another path is not reported isolated.",
        "operationId": "traceValveIsolation",
        "parameters": [
          {
            "description": "Required ID of the topology link to take out of service; the response lists the valves to close (the link itself when it is a valve), the nodes that lose supply and those still fed by another path.",
            "in": "query",
            "name": "link_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IsolationResult"
                }
              }
            },
            "description": "Isolation analysis"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Which valves take a link out of service and what loses supply",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/utility-relationships": {
      "get": {
        "description": "Pages the relationships people hold with the caller's utility that do not need an account, such as requester, follower or assisted helper, newest first. Each row has the kind, the subject it is about (for example a service request), the status and its start, expiry and end times. The person's global identity key is never returned to business callers, although identity_id can still be used as a filter. Requires business:customers:read. An invalid limit or cursor returns 400.",
        "operationId": "listUtilityRelationships",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only relationships of this identity.",
            "in": "query",
            "name": "identity_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only relationships of this kind.",
            "in": "query",
            "name": "kind",
            "schema": {
              "enum": [
                "requester",
                "follower",
                "assisted_helper"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only relationships in this status.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "active",
                "ended",
                "invited",
                "pending_review",
                "suspended",
                "declined",
                "expired"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BusinessUtilityRelationshipPage"
                }
              }
            },
            "description": "Relationships in the authenticated utility tenant"
          },
          "400": {
            "description": "Invalid limit or cursor (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Missing business:customers:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List people's relationships with the utility",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:customers:read"
        ]
      }
    },
    "$BUSINESS_API/water-balance": {
      "get": {
        "description": "Computes the IWA water balance for the whole network over a window by balancing every DMA and adding up those with enough data; the response includes the per-DMA detail, system input, billed and unbilled authorised consumption, water losses and non-revenue water. DMAs with insufficient data are excluded from the totals with a warning, and the status is computed, partial_data or insufficient_data accordingly. Water losses are split into apparent and real only when apparent_loss_bp is given. Read-only; requires network read access.",
        "operationId": "getSystemWaterBalance",
        "parameters": [
          {
            "description": "Required start of the window as an RFC 3339 timestamp; the window must end after it and span at most 366 days.",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required end of the window as an RFC 3339 timestamp, later than from.",
            "in": "query",
            "name": "to",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Optional assumed apparent losses as basis points of authorised consumption, an integer from 0 to 10000 (100 = 1%); when omitted, losses are not split into apparent and real.",
            "in": "query",
            "name": "apparent_loss_bp",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IWAWaterBalance"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "IWA water balance for the whole system with per-DMA detail",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "network:read"
        ]
      }
    },
    "$BUSINESS_API/water-quality/results": {
      "get": {
        "description": "Lists laboratory results recorded across the tenant's water quality samples, with cursor pagination (limit defaults to 20, maximum 100). Each result carries the limits that applied when it was recorded and its compliance verdict. Filters combine with AND and require monitoring read access.",
        "operationId": "listWaterResults",
        "parameters": [
          {
            "description": "Returns only results for this sample ID (smp_ prefix).",
            "in": "query",
            "name": "sample_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only results for this quality parameter: residual_chlorine, ph, turbidity, e_coli or coliforms.",
            "in": "path",
            "name": "parameter",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only results with this verdict: compliant, non_compliant or not_evaluated (no standard was configured for the parameter when the result was recorded).",
            "in": "query",
            "name": "compliance",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterResultList"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List laboratory results",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/water-quality/samples": {
      "get": {
        "description": "Lists the tenant's water quality samples with cursor pagination (limit defaults to 20, maximum 100). Filters combine with AND and an unknown value returns an empty page. Requires monitoring read access.",
        "operationId": "listWaterSamples",
        "parameters": [
          {
            "description": "Returns only samples taken at this kind of location: reservoir or zone.",
            "in": "query",
            "name": "location_type",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only samples taken at this network asset ID, as used for reservoir samples.",
            "in": "query",
            "name": "asset_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only samples taken in this district metered area ID, as used for zone samples.",
            "in": "query",
            "name": "dma_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only samples in this state: collected (no results yet) or analyzed (at least one result recorded).",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterSampleList"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List water samples",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      },
      "post": {
        "description": "Records a water sample collected in the field, with status collected, and returns 201. code and sampled_at are required; location_type must be reservoir (asset_id required) or zone (dma_id required). Results are added afterwards through the sample's results endpoint. Requires monitoring write access.",
        "operationId": "createWaterSample",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWaterSampleRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterSample"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a sample at a reservoir or distribution zone",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:monitoring:write"
        ]
      }
    },
    "$BUSINESS_API/water-quality/samples/{id}": {
      "get": {
        "description": "Returns one water quality sample with its location, collection time, collector, laboratory, notes and status (collected or analyzed). Responds 404 when the sample is not in the caller's tenant. Requires monitoring read access.",
        "operationId": "getWaterSample",
        "parameters": [
          {
            "description": "ID of the water quality sample (smp_ prefix).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterSample"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a sample",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/water-quality/samples/{id}/results": {
      "post": {
        "description": "Records one laboratory measurement for a sample and returns 201 with the result. The value is checked against the tenant's configured standard for the parameter, storing the applied limits and a compliant or non_compliant verdict (not_evaluated when no standard exists). The sample moves to analyzed, and active water quality alarm rules for the parameter are evaluated, which can open, update or auto-resolve alarms. parameter must be a known parameter, unit is required, value must be finite and analyzed_at defaults to now; responds 404 when the sample does not exist.",
        "operationId": "createWaterResult",
        "parameters": [
          {
            "description": "ID of the sample the measurement belongs to (smp_ prefix).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWaterResultRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WaterResult"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an analysed parameter; grades it against the limit and evaluates quality alarm rules",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:monitoring:write"
        ]
      }
    },
    "$BUSINESS_API/water-quality/standards": {
      "get": {
        "description": "Returns the water quality limits the tenant has configured, one per parameter, in a data array ordered by parameter name. These limits decide the compliance verdict of new results, and parameters without a standard are reported as not_evaluated. Requires monitoring read access.",
        "operationId": "getQualityStandards",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QualityStandardList"
                }
              }
            },
            "description": "Success"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the connector scope is missing or caller is not a connector"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List configured quality limits",
        "x-roles": [
          "admin",
          "analyst",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:monitoring:read"
        ]
      }
    },
    "$BUSINESS_API/water-quality/standards/{parameter}": {
      "put": {
        "description": "Creates or replaces the tenant's limit for one quality parameter and returns the stored standard. unit is required, at least one of min_value and max_value must be set, and min_value must not exceed max_value; source is free text naming where the limit comes from. Only results recorded afterwards use the new limits, since existing results keep the limits that applied at the time. Requires monitoring write access.",
        "operationId": "putQualityStandard",
        "parameters": [
          {
            "description": "Quality parameter the limit applies to: residual_chlorine, ph, turbidity, e_coli or coliforms; any other value is rejected with 400.",
            "in": "path",
            "name": "parameter",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PutQualityStandardRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/QualityStandard"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Set the limit for residual_chlorine, ph, turbidity, e_coli or coliforms",
        "x-roles": [
          "admin",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "business:monitoring:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders": {
      "get": {
        "description": "Lists the tenant's work orders with cursor pagination (limit defaults to 20, maximum 100; pass next_cursor as after). Filters for order type, priority, status, service area, crew, account and connection combine with AND, and q searches the order text and also matches orders of accounts whose holder matches the search. Requires operations read access.",
        "operationId": "listWorkOrders",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only orders raised for this account",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only orders raised for this connection",
            "in": "query",
            "name": "connection_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderPage"
                }
              }
            },
            "description": "Work orders"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List field operations work orders",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      },
      "post": {
        "description": "Materials are planned when the order is created (RFC 0071 section 5.3). `kit_id` fills the lines from a kit (`default` picks the kit set for the order type); `materials` add catalogue items or free-text parts, or adjust a kit line (quantity 0 removes it). Meters are required lines by default on installation and replacement orders. Lines are reserved at the natural source (the crew's van, the service area's warehouse, the main warehouse); a shortage is a warning in the response, never a refusal. Without materials, `proposed_kit_id` offers the order type's default kit.",
        "operationId": "createWorkOrder",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateWorkOrderRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderWithMaterials"
                }
              }
            },
            "description": "Work order created, with each material line's availability and reservation"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request: unknown or inactive item or kit, quantity not in the item's units"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:write scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a field work order, with its material lines from a kit or one by one",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}": {
      "get": {
        "description": "Returns one work order with its status, crew, schedule, execution details and its material lines. Responds 404 when the order is not in the caller's tenant. Requires operations read access.",
        "operationId": "getWorkOrder",
        "parameters": [
          {
            "description": "ID of the work order in the caller's tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderWithMaterials"
                }
              }
            },
            "description": "Work order details; material_lines and material_cost_minor appear when the order has materials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get work order details, with material lines and material cost",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/assign": {
      "post": {
        "description": "Assigns a crew to a general work order, moves it to assigned and records the status change in its history; when the crew changes, reserved materials move to the new crew. Reassigning an already assigned order only changes the crew. Connection field orders (disconnection, reconnection, new installation, meter exchange) must use dispatch instead and get 409, as does any status that cannot move to assigned. Requires operations write access.",
        "operationId": "assignWorkOrder",
        "parameters": [
          {
            "description": "ID of the work order to assign; it must not be a connection field order.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Work order assigned"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Assign work order to crew",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/cancel": {
      "post": {
        "description": "Cancelling publishes the status change; inventory releases the order's reservations and takes back anything issued to it. Cancelling a cancelled order changes nothing.",
        "operationId": "cancelWorkOrder",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "maxLength": 500,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Work order cancelled"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:write scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "A completed work order cannot be cancelled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Cancel a work order that is not completed",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/complete": {
      "post": {
        "description": "Marks a general work order completed, stores the optional notes as its resolution notes, sets completed_at and records the status change in its history. Connection field orders must use execute instead and get 409, and so does an order whose current status cannot move to completed. Requires operations write access.",
        "operationId": "completeWorkOrder",
        "parameters": [
          {
            "description": "ID of the work order to complete; it must not be a connection field order.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Work order completed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Complete work order",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/dispatch": {
      "post": {
        "description": "Sends a connection field order to a crew and moves it to dispatched, optionally with a scheduled_for time; give crew_id or set auto_assign to pick the best crew with the required skill. The order must be a field order (400 otherwise), and a crew lacking the required skill, a status that cannot be dispatched, or missing materials for required lines returns 409. A work_order.dispatched event is emitted and the change is recorded in the status history. Requires operations write access.",
        "operationId": "dispatchWorkOrder",
        "parameters": [
          {
            "description": "ID of the connection field order to dispatch.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "auto_assign": {
                    "type": "boolean"
                  },
                  "crew_id": {
                    "type": "string"
                  },
                  "scheduled_for": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Dispatch a connection field order to a skilled crew",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/execute": {
      "post": {
        "description": "Records the field outcome of a connection field order: result completed or failed_access_denied, with optional executed_at (defaults to now), final reading and notes. Completing a disconnection requires applied_seal_serial and evidence_photo, and a failed_access_denied result requires notes. A work_order.executed event is emitted for downstream processing such as connection status changes; a status that cannot take the result returns 409, and a non-field order returns 400. Requires operations write access.",
        "operationId": "executeWorkOrder",
        "parameters": [
          {
            "description": "ID of the connection field order whose outcome is recorded.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "applied_seal_serial": {
                    "type": "string"
                  },
                  "evidence_photo": {
                    "type": "string"
                  },
                  "executed_at": {
                    "type": "string"
                  },
                  "final_reading": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "result": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a field order outcome: completed or failed_access_denied",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/material-lines": {
      "get": {
        "description": "Catalogue lines carry the inventory picture; free-text lines are flagged needs_mapping and touch no stock. Free-text materials recorded before material lines are listed read-only with legacy true.",
        "operationId": "getWorkOrderMaterialLines",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLineList"
                }
              }
            },
            "description": "Material lines"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:read scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "A work order's material lines with availability, reservations, issues, returns and cost",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      },
      "post": {
        "description": "Adds planned material lines to a work order from a kit (kit_id, or default for the order type's default kit) or from an explicit materials list, and returns 201 with the new lines in a data array. Items already on the order are skipped, and if nothing new remains the request fails with 409; a completed or cancelled order also returns 409. Catalogue items are reserved in inventory when inventory is available. Requires operations write access.",
        "operationId": "addWorkOrderMaterialLines",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/AddWorkOrderMaterialLinesRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLineList"
                }
              }
            },
            "description": "Lines added and reserved where the stock is"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:write scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The order is completed or cancelled, or already has a line for the item"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add material lines from a kit or one by one, until the order ends",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/material-lines/{line}": {
      "delete": {
        "description": "Removes a planned material line from a work order and returns 204; inventory reservations are resynced for catalogue items. A line with material already issued, or an order that is completed or cancelled, returns 409. Requires operations write access.",
        "operationId": "deleteWorkOrderMaterialLine",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Material line ID (wml_)",
            "in": "path",
            "name": "line",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Line removed"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:write scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Material was already issued to the line, or the order has ended"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a line until its material is issued; its reservations are released",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      },
      "patch": {
        "description": "Changes a material line that has not been issued yet: planned quantity (must be positive), required flag, source location, description (up to 255 characters), or item_id to map a free-text line to a catalogue item. Returns the updated line with its stock picture and syncs inventory reservations. A completed or cancelled order, a line with issued material, remapping a line that already has an item, or an item already on the order returns 409. Requires operations write access.",
        "operationId": "updateWorkOrderMaterialLine",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Material line ID (wml_)",
            "in": "path",
            "name": "line",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateWorkOrderMaterialLineRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLine"
                }
              }
            },
            "description": "Line changed and its reservation adjusted"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:write scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Material was already issued to the line, or the order has ended"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a line until its material is issued; an item_id maps a free-text line to the catalogue",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/material-lines/{line}/issue": {
      "post": {
        "description": "A held reservation at the location is consumed, so reserved and issued never count the same units. The location defaults to the line's reservation, then its source. Meters are issued when installed through the meter actions. Replaying the Idempotency-Key records once.",
        "operationId": "issueWorkOrderMaterialLine",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Material line ID (wml_)",
            "in": "path",
            "name": "line",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkOrderLineStockRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLine"
                }
              }
            },
            "description": "Replayed Idempotency-Key; nothing recorded twice"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLine"
                }
              }
            },
            "description": "Issue recorded; the line with its new figures"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:read, or inventory:write (inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record material issued to a line, for crews working out of order or offline",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/material-lines/{line}/return": {
      "post": {
        "description": "Returns issued material from a work order line to stock (quantity, optional location_id, serials, reason and occurred_at) and responds 201 with the updated line. Send an Idempotency-Key header (1 to 255 visible ASCII characters) to make retries safe: a replay returns 200 with Idempotent-Replayed: true. Free-text lines, unavailable inventory, or returning below a quantity already recorded as used on a completed order return 409.",
        "operationId": "returnWorkOrderMaterialLine",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Material line ID (wml_)",
            "in": "path",
            "name": "line",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/StockIdempotencyKey"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/WorkOrderLineStockRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLine"
                }
              }
            },
            "description": "Replayed Idempotency-Key; nothing recorded twice"
          },
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLine"
                }
              }
            },
            "description": "Return recorded; the line with its new figures"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:read, or inventory:write (inventory:van:write at the caller's own van)"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Conflict: insufficient_stock, serial_mismatch, idempotency_conflict or a state that no longer allows the change"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record unused material brought back from a line",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/material-lines/{line}/use": {
      "post": {
        "description": "Setting the same quantity again changes nothing, so an offline phone can replay it. On a completed order inventory settles the difference: unused issued stock returns to the van or warehouse, and extra use is issued from the van.",
        "operationId": "recordWorkOrderMaterialUse",
        "parameters": [
          {
            "description": "Work order ID (wko_)",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Material line ID (wml_)",
            "in": "path",
            "name": "line",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "occurred_at": {
                    "format": "date-time",
                    "type": "string"
                  },
                  "used": {
                    "$ref": "#/components/schemas/InventoryQuantity"
                  }
                },
                "required": [
                  "used"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/WorkOrderMaterialLine"
                }
              }
            },
            "description": "Use recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request (RFC 7807 problem)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Authenticated utility context required"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing operations:write, or inventory:write, or inventory:van:write as a member of the crew's van"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not found in the authenticated tenant"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The order is cancelled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record the quantity a line actually used, which may differ from planned",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/materials": {
      "get": {
        "description": "Lists the simple material records (part code, description, quantity, unit) logged against a work order, oldest first, with cursor pagination (limit defaults to 20, maximum 100) and a total_count. These are separate from inventory-backed material lines. Responds 404 when the work order does not exist and requires operations read access.",
        "operationId": "listWorkOrderMaterials",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "ID of the work order whose material records are listed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List a field order bill of materials",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      },
      "post": {
        "description": "Logs a material used on a work order as a simple record and returns 201; part_code and a positive quantity are required, description and unit are optional. The record does not touch inventory stock, unlike material lines. Responds 404 when the work order does not exist and requires operations write access.",
        "operationId": "addWorkOrderMaterial",
        "parameters": [
          {
            "description": "ID of the work order the material is logged against.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "description": {
                    "type": "string"
                  },
                  "part_code": {
                    "type": "string"
                  },
                  "quantity": {
                    "type": "integer"
                  },
                  "unit": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Success"
          },
          "201": {
            "description": "Created"
          },
          "400": {
            "description": "Invalid input"
          },
          "403": {
            "description": "Forbidden"
          },
          "404": {
            "description": "Not found"
          },
          "409": {
            "description": "Conflict with current state"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a part to the bill of materials",
        "x-roles": [
          "admin",
          "field_supervisor",
          "operations",
          "owner"
        ],
        "x-scopes": [
          "operations:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/metadata": {
      "get": {
        "description": "Returns the custom key-value metadata attached to a work order, as resource_type work_order, the resource ID and a metadata map of strings. The work order must exist in the caller's tenant, otherwise 404. Requires business metadata read access.",
        "operationId": "getBusinessWorkOrderMetadata",
        "parameters": [
          {
            "description": "ID of the work order whose metadata is read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a work order",
        "x-roles": [
          "admin",
          "customer_service",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the given keys into the work order's metadata and returns the full resulting map; keys not mentioned are kept, and a key sent with an empty string value is deleted. Keys are at most 40 characters without square brackets or control characters, values at most 500 characters, and a resource may hold at most 50 keys; violations return 400 with per-key details. The work order must exist in the tenant (404 otherwise). Requires business metadata write access.",
        "operationId": "putBusinessWorkOrderMetadata",
        "parameters": [
          {
            "description": "ID of the work order whose metadata is merged.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:metadata:write"
        ]
      }
    },
    "$BUSINESS_API/work-orders/{id}/status-history": {
      "get": {
        "description": "Requires operations:read.",
        "operationId": "listWorkOrderStatusHistory",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Work order identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/WorkOrderStatusChange"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Status changes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "A work order's status log, newest first",
        "x-roles": [
          "admin",
          "analyst",
          "field_reader",
          "field_supervisor",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "operations:read"
        ]
      }
    },
    "$BUSINESS_API/workspace/close": {
      "post": {
        "description": "Owner only. Name another active owner as successor. Writes stop immediately. The response includes the existing compliance export endpoint and the configured deletion due date; this request does not delete tenant data.",
        "operationId": "requestWorkspaceClose",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "successor_member_id": {
                    "description": "Active tenant owner membership that will retain ownership after closure",
                    "type": "string"
                  }
                },
                "required": [
                  "successor_member_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "deletion_due_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "export_path": {
                      "example": "$BUSINESS_API/export/compliance",
                      "type": "string"
                    },
                    "tenant": {
                      "$ref": "#/components/schemas/Tenant"
                    }
                  },
                  "required": [
                    "tenant",
                    "export_path",
                    "deletion_due_at"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Workspace closed for use; data remains available for export during the grace period"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Caller is not the active workspace owner"
          },
          "409": {
            "description": "Successor is missing or is not another active tenant owner"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Close the active workspace and begin its configured recovery period",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:organization:read",
          "business:team:read"
        ]
      }
    },
    "$BUSINESS_API/workspace/close/reverse": {
      "post": {
        "description": "Owner only. Restores the lifecycle and verification state that existed before closure. The operation is refused after the deletion due date.",
        "operationId": "reverseWorkspaceClose",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "tenant": {
                      "$ref": "#/components/schemas/Tenant"
                    }
                  },
                  "required": [
                    "tenant"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Workspace reopened"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Caller is not the active workspace owner"
          },
          "409": {
            "description": "Recovery period has ended or workspace is not eligible for reopening"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reopen the active workspace during its configured recovery period",
        "x-roles": [
          "admin",
          "analyst",
          "billing_clerk",
          "customer_service",
          "field_reader",
          "field_supervisor",
          "finance",
          "operations",
          "owner",
          "viewer"
        ],
        "x-scopes": [
          "business:organization:read"
        ]
      }
    },
    "$BUSINESS_API/workspace/verification/requirements": {
      "get": {
        "description": "Returns the verification picture of the caller's workspace: the onboarding status, the verification requirement codes that apply to it under its policy, the catalogue definitions of those requirements, the requirement states (currently due, eventually due, past due, pending verification, errors) and the capabilities enabled so far with the reasons blocking the rest. An onboarding application is created on first read if the workspace has none. Requires business onboarding read access.",
        "operationId": "getWorkspaceVerificationRequirements",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "capabilities": {
                      "$ref": "#/components/schemas/OnboardingCapabilities"
                    },
                    "catalog": {
                      "items": {
                        "$ref": "#/components/schemas/VerificationRequirementDefinition"
                      },
                      "type": "array"
                    },
                    "requirements": {
                      "$ref": "#/components/schemas/OnboardingRequirements"
                    },
                    "status": {
                      "type": "string"
                    },
                    "verification_requirements": {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "status",
                    "verification_requirements",
                    "catalog",
                    "requirements",
                    "capabilities"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Requirement progress and capability states for the active workspace"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the active workspace verification requirements and capability states",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "business:onboarding:read"
        ]
      }
    },
    "$CONNECTOR_API/communications/jobs/request": {
      "post": {
        "description": "Leases the next pending message delivery job for the authenticated connector, optionally narrowed to some of its registered channels and granted tenants (400 if the narrowing leaves nothing). With wait_timeout_seconds the call long-polls up to 50 seconds; it returns 204 when no job became available. A leased job is held for one minute and must be renewed with heartbeat, completed or released. Requires the connector session token as a Bearer token.",
        "operationId": "requestCommunicationJob",
        "responses": {
          "200": {
            "description": "A leased job"
          },
          "204": {
            "description": "No job arrived during the wait"
          },
          "401": {
            "description": "RFC 7807 problem when the session token is invalid"
          }
        },
        "security": [
          {
            "connectorSession": []
          }
        ],
        "summary": "Long-poll for the next message to deliver"
      }
    },
    "$CONNECTOR_API/communications/jobs/{id}/complete": {
      "post": {
        "description": "Reports the delivery outcome of a leased job with status sent, delivered or failed, plus an optional provider reference, status code and failure reason, and returns 204. A failed job with failure_class transient (the default) is requeued with a backoff while attempts and the delivery window remain; permanent failures and successes are final, and the message content is erased. Returns 409 when the connector no longer holds the lease.",
        "operationId": "completeCommunicationJob",
        "parameters": [
          {
            "description": "ID of the communication job leased by this connector.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Outcome recorded"
          },
          "409": {
            "description": "RFC 7807 problem when the lease is no longer held"
          }
        },
        "security": [
          {
            "connectorSession": []
          }
        ],
        "summary": "Report a delivery outcome; the message content is then erased"
      }
    },
    "$CONNECTOR_API/communications/jobs/{id}/heartbeat": {
      "post": {
        "description": "Extends the connector's lease on a job by one minute from now and records the connector as alive, returning 204. Call it while a delivery takes longer than the lease; if the lease already expired or the job is held by another connector, the call returns 409 and the job must not be completed.",
        "operationId": "heartbeatCommunicationJob",
        "parameters": [
          {
            "description": "ID of the communication job whose lease is renewed.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Lease renewed"
          },
          "409": {
            "description": "RFC 7807 problem when the lease is no longer held"
          }
        },
        "security": [
          {
            "connectorSession": []
          }
        ],
        "summary": "Renew a job lease"
      }
    },
    "$CONNECTOR_API/communications/jobs/{id}/release": {
      "post": {
        "description": "Gives a leased job back to the queue without a delivery attempt, returning 204; the job becomes pending again and the attempt is not counted against its retry limit. Use it when the connector cannot deliver now, for example during shutdown. Returns 409 when the connector no longer holds the lease.",
        "operationId": "releaseCommunicationJob",
        "parameters": [
          {
            "description": "ID of the communication job to release.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Job returned to the queue without consuming an attempt"
          },
          "409": {
            "description": "RFC 7807 problem when the lease is no longer held"
          }
        },
        "security": [
          {
            "connectorSession": []
          }
        ],
        "summary": "Return a job this connector holds no credentials for to the queue"
      }
    },
    "$CONNECTOR_API/communications/registrations": {
      "post": {
        "description": "Exchanges a platform-issued enrollment token for a connector identity and returns 201 with connector_id, a session token (used as a Bearer token on the job endpoints) and the tenant IDs the connector may serve. name (up to 120 characters) and at least one channel (email or push) are required. Each registration uses one of the enrollment token's allowed uses, and an expired, exhausted or unknown token returns 401. No other authentication is required.",
        "operationId": "registerCommunicationConnector",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "agent_version": {
                    "type": "string"
                  },
                  "channels": {
                    "items": {
                      "type": "string"
                    },
                    "minItems": 1,
                    "type": "array"
                  },
                  "hostname": {
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 120,
                    "type": "string"
                  },
                  "token": {
                    "description": "One-time communication connector enrollment token",
                    "type": "string"
                  }
                },
                "required": [
                  "token",
                  "name",
                  "channels"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Connector registered"
          },
          "401": {
            "description": "RFC 7807 problem when the token is invalid, expired or used up"
          }
        },
        "security": [],
        "summary": "Exchange an enrollment token for a connector session token"
      }
    },
    "$CONNECTOR_API/payments/events": {
      "post": {
        "description": "Records a settled payment that a payment connector observed on its own, such as a customer paying at an agent or from a phone menu, without a prior payment job. The connector authenticates with its connector token (Authorization Bearer or Token, or X-Connector-Token); provider_transaction_id and a positive amount_minor are required, and the payment is matched to the tenant's account by account_number, with settled_at defaulting to now. Confirmation is idempotent on the provider transaction and event_id, so a repeated event does not post the payment twice. Returns 401 for an unknown token and 403 when the tenant is suspended or closed.",
        "operationId": "ingestPaymentEvent",
        "responses": {
          "200": {
            "description": "Event ingested"
          },
          "400": {
            "description": "RFC 7807 problem when the event is malformed"
          }
        },
        "security": [
          {
            "connectorSession": []
          },
          {
            "connectorTokenHeader": []
          }
        ],
        "summary": "Report an unprompted customer payment"
      }
    },
    "$CONNECTOR_API/payments/jobs/request": {
      "post": {
        "description": "Leases the next pending payment job (a collection or a refund) for the calling connector, filtered by the methods and currency in the body or, when omitted, the ones the connector registered. Set wait_timeout_seconds (capped at 50) to long-poll: the call waits for a new job and returns 204 No Content when none arrives in time. A leased job is held for 60 seconds and must be kept alive with the heartbeat call; the body can also declare which registered methods are currently operational, which controls what consumers are offered at checkout.",
        "operationId": "requestPaymentJob",
        "responses": {
          "200": {
            "description": "A leased job for the connector's tenant"
          },
          "204": {
            "description": "No job arrived during the wait"
          },
          "401": {
            "description": "RFC 7807 problem when the session token is invalid"
          }
        },
        "security": [
          {
            "connectorSession": []
          },
          {
            "connectorTokenHeader": []
          }
        ],
        "summary": "Long-poll for the next payment job and refresh the operational_methods declaration"
      }
    },
    "$CONNECTOR_API/payments/jobs/{id}/complete": {
      "post": {
        "description": "Reports the outcome of a job the calling connector holds; status must be succeeded or failed. For a collection, success confirms the payment against its payment session (recording the payment, receipt and invoice allocation) and failure marks a still-pending session as failed; a refund's outcome is only stored on the job. Settlement runs before the job closes and every step is idempotent, so retrying after an error is safe. Returns 404 for an unknown job, 401 when another connector holds it, and 409 when the job is no longer leased.",
        "operationId": "completePaymentJob",
        "parameters": [
          {
            "description": "Identifier of the leased payment job (prefixed pjb_) returned by the job request call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Outcome recorded"
          },
          "409": {
            "description": "RFC 7807 problem when the job is no longer leased"
          }
        },
        "security": [
          {
            "connectorSession": []
          },
          {
            "connectorTokenHeader": []
          }
        ],
        "summary": "Report a payment job outcome"
      }
    },
    "$CONNECTOR_API/payments/jobs/{id}/heartbeat": {
      "post": {
        "description": "Extends the lease on a job the calling connector holds by another 60 seconds and marks the connector busy. Call it while a payment is still in progress so the job is not handed to another connector. Returns 404 when the job does not exist, is not leased by this connector or has already been completed.",
        "operationId": "heartbeatPaymentJob",
        "parameters": [
          {
            "description": "Identifier of the leased payment job (prefixed pjb_) whose lease should be extended.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Lease renewed"
          },
          "404": {
            "description": "RFC 7807 problem when the lease is no longer held"
          }
        },
        "security": [
          {
            "connectorSession": []
          },
          {
            "connectorTokenHeader": []
          }
        ],
        "summary": "Renew a job lease"
      }
    },
    "$CONNECTOR_API/payments/registrations": {
      "post": {
        "description": "The token binds the session to one tenant. A request may assert tenant_id, and is refused when it differs from the token's tenant. operational_methods lists the supported methods the connector can actually complete; a skeleton provider declares none.",
        "operationId": "registerPaymentConnector",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": false,
                "properties": {
                  "agent_version": {
                    "type": "string"
                  },
                  "currency": {
                    "type": "string"
                  },
                  "hostname": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "operational_methods": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "supported_methods": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "tenant_id": {
                    "type": "string"
                  },
                  "token": {
                    "description": "One-time payment connector enrollment token",
                    "type": "string"
                  }
                },
                "required": [
                  "token"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Connector registered"
          },
          "400": {
            "description": "RFC 7807 problem when the token is invalid, expired, used up, or issued for another tenant"
          }
        },
        "security": [],
        "summary": "Exchange a payment enrollment token for a connector session token"
      }
    },
    "$CONNECTOR_API/payments/request": {
      "post": {
        "deprecated": true,
        "description": "Older path for the payment job request; it runs the same handler as $CONNECTOR_API/payments/jobs/request and behaves identically, so new connectors should call that path instead. Leases the next pending payment job for the calling connector, filtered by the methods and currency in the body or, when omitted, the ones the connector registered, and can refresh the connector's operational methods. Set wait_timeout_seconds (capped at 50) to long-poll; 204 means no job arrived in time. The connector session token is accepted as Authorization Bearer or Token, or in the X-Connector-Token header.",
        "operationId": "requestPaymentJobAlias",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentJobRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "A leased job for the connector's tenant"
          },
          "204": {
            "description": "No job arrived during the wait"
          },
          "401": {
            "description": "RFC 7807 problem when the session token is invalid or missing"
          },
          "403": {
            "description": "The workspace is suspended or closed"
          }
        },
        "security": [
          {
            "connectorSession": []
          },
          {
            "connectorTokenHeader": []
          }
        ],
        "summary": "Long-poll for the next payment job (older path)"
      }
    },
    "$CONSUMER_API/account-links": {
      "get": {
        "description": "Returns every link the signed-in person has, as one list in data: active account memberships (kind membership, with permissions and any expiry) and link requests still pending or rejected by the utility (kind request, with the rejection reason). Approved or cancelled requests are omitted. The list is not paginated.",
        "operationId": "getAccountLinks",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLinkList"
                }
              }
            },
            "description": "Links"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List linked accounts and pending requests"
      },
      "post": {
        "description": "Links a utility account to the signed-in person, either by redeeming an invitation code or by proving ownership with tenant_id, an account, contract or meter number, and the phone on file or a bill claim code. A proven match creates the membership at once and returns 201; otherwise the call returns 202 with a pending link request for the utility to review, and the response looks the same whether or not the details matched an account. Failed attempts are limited to 5 per 15 minutes per person and per IP address (429 after that), an invalid or expired invitation code returns 400, and an already linked account returns 409.",
        "operationId": "createAccountLink",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateAccountLink"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLinkResult"
                }
              }
            },
            "description": "Linked immediately"
          },
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountLinkResult"
                }
              }
            },
            "description": "Pending utility review, whether or not the details match"
          },
          "400": {
            "description": "Invalid code"
          },
          "429": {
            "description": "Too many attempts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Link an account by invitation code, or account number and contract phone. Wrong number and wrong phone return the same 202 pending; attempts are throttled per identity"
      }
    },
    "$CONSUMER_API/account-links/{id}": {
      "delete": {
        "description": "Removes one of the caller's links: an id starting with alr_ cancels a pending link request, and a membership id ends the caller's own access to that account. Cancelling a request that is no longer pending returns 409, and an id that is not one of the caller's links returns 404. Returns 204 on success.",
        "operationId": "leaveAccountLink",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Leave an account or cancel a pending request"
      }
    },
    "$CONSUMER_API/accounts": {
      "get": {
        "description": "Pages the utility accounts the signed-in person can access through an active membership, across all tenants. Results can be narrowed with the status, customer_id, property_id and q (search) query parameters and use cursor pagination with limit and after.",
        "operationId": "listConsumerAccounts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountPage"
                }
              }
            },
            "description": "Accounts authorized for this consumer identity"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List accounts explicitly linked to the authenticated consumer"
      }
    },
    "$CONSUMER_API/accounts/{id}": {
      "get": {
        "description": "Returns one account the caller holds an active membership on with the account read permission. The tenant is taken from the X-Tenant-ID header or tenant_id query parameter, or worked out from the caller's memberships; 403 is returned when the caller has no access to the account.",
        "operationId": "getConsumerAccount",
        "parameters": [
          {
            "description": "Identifier of the account to return; it must be an account the caller is a member of.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Tenant selector only; the service verifies active account membership.",
            "in": "query",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Account"
                }
              }
            },
            "description": "Account authorized for the authenticated consumer"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an explicitly linked account in a selected utility tenant"
      }
    },
    "$CONSUMER_API/accounts/{id}/delegates": {
      "get": {
        "description": "Each active delegate also carries display_name, masked_phone and masked_email when known.",
        "operationId": "getAccountDelegates",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Tenant of the account",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DelegateList"
                }
              }
            },
            "description": "Delegates"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List delegates and pending invitations (holder only)"
      },
      "post": {
        "description": "Lets an account holder invite another person by exactly one of phone (at least 9 digits) or email, returning an invitation with a one-time code the invitee redeems through the account-link call. The caller needs the member invite permission on the account; permissions default to account read and invoice read, can only be ones the caller holds, can never include member invite, and always include account read. The invitation expires after expires_in_hours (1 to 720, default 168).",
        "operationId": "createAccountDelegate",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Tenant of the account",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/InvitationInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AccountInvitation"
                }
              }
            },
            "description": "Invitation with code"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Invite a delegate with limited permissions (holder only)"
      }
    },
    "$CONSUMER_API/accounts/{id}/delegates/{delegate_id}": {
      "delete": {
        "description": "Lets an account holder with the member invite permission remove a delegate: an invitation id (ivt_) revokes the pending invitation, and a membership id ends that person's access to the account. The holder cannot revoke their own membership through this call, and an id that belongs to another account returns 404. Returns 204 on success.",
        "operationId": "revokeAccountDelegate",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "delegate_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Tenant of the account",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a delegate membership or pending invitation"
      }
    },
    "$CONSUMER_API/accounts/{id}/membership": {
      "delete": {
        "description": "Ends the caller's own membership on an account, recorded as left by the person; the caller loses access to the account's invoices, payments and readings immediately. The tenant comes from X-Tenant-ID, the tenant_id query parameter or the caller's memberships, and 403 is returned when none can be resolved. Returns 204 on success.",
        "operationId": "revokeOwnConsumerAccountMembership",
        "parameters": [
          {
            "description": "Identifier of the account the caller wants to leave.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Tenant selector for locating the explicitly linked account.",
            "in": "query",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Consumer membership revoked"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke the authenticated consumer's access to an account"
      }
    },
    "$CONSUMER_API/accounts/{id}/statement.pdf": {
      "get": {
        "description": "Renders a PDF account statement for an account linked to the caller, covering from and to (YYYY-MM-DD); to defaults to today and from to one year before to. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Returns 400 for a malformed date or from after to, and 403 or 404 when the account is not in the caller's scope.",
        "operationId": "getConsumerStatementPDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Account id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Start of the statement (YYYY-MM-DD); defaults to one year before to",
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date",
              "type": "string"
            }
          },
          {
            "description": "End of the statement (YYYY-MM-DD); defaults to today",
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download a statement of one of the caller's accounts as PDF"
      }
    },
    "$CONSUMER_API/cases": {
      "get": {
        "description": "Pages the collection (debt) cases on accounts linked to the caller, across tenants unless X-Tenant-ID selects one. Filter with account_id (which must be one of the caller's accounts) and status; pagination uses limit and after.",
        "operationId": "listConsumerCases",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Collection cases"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List collection cases for consumer"
      }
    },
    "$CONSUMER_API/cases/{id}": {
      "get": {
        "description": "Returns one collection (debt) case, with its debt, aging bucket, status, dunning state and notes, when it belongs to an account on which the caller holds the invoice.read account permission. The lookup searches every tenant where the caller holds such an account, unless X-Tenant-ID narrows it to one of them. A case on any other account, in any other tenant, or that does not exist returns 404, so existence never leaks. No staff scope is involved for a consumer caller; the access check is the account membership.",
        "operationId": "getConsumerCase",
        "parameters": [
          {
            "description": "Id of the collection case (prefix `col`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Narrow the lookup to one of the caller's tenants; a tenant the caller has no account in finds nothing.",
            "in": "header",
            "name": "X-Tenant-ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CollectionCase"
                }
              }
            },
            "description": "Collection case on one of the caller's accounts"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is neither a consumer identity nor staff holding collections:read"
          },
          "404": {
            "description": "Case not found among the caller's accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a collection case on one of the caller's accounts"
      }
    },
    "$CONSUMER_API/connection-applications": {
      "post": {
        "description": "Alias of POST $CONSUMER_API/connections. Authorization and applicant resolution are identical.",
        "operationId": "createConsumerConnectionApplication",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "address": {
                    "type": "string"
                  },
                  "category": {
                    "enum": [
                      "residential",
                      "commercial",
                      "industrial",
                      "institutional",
                      "government"
                    ],
                    "type": "string"
                  },
                  "customer_id": {
                    "description": "Ignored for consumer requests; customer is resolved from the caller's account membership.",
                    "type": "string"
                  },
                  "diameter_mm": {
                    "minimum": 1,
                    "type": "integer"
                  },
                  "gps_coordinates": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "pipe_diameter_mm": {
                    "type": "integer"
                  },
                  "pipe_material": {
                    "type": "string"
                  },
                  "pressure_zone_id": {
                    "type": "string"
                  },
                  "property_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "property_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Connection application submitted"
          },
          "403": {
            "description": "Consumer context or connection.manage permission is required"
          },
          "404": {
            "description": "Property is outside the consumer's account scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit a consumer connection application through the compatibility path"
      }
    },
    "$CONSUMER_API/connections": {
      "get": {
        "description": "Each connection carries meter_id and meter_serial, the installed meter's serial number.",
        "operationId": "listConsumerConnections",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Connections for the consumer"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List consumer water service connections"
      },
      "post": {
        "description": "The authenticated consumer must hold connection.manage for an account in the selected tenant. The service resolves the customer from that membership and property; a submitted customer_id does not grant or select access.",
        "operationId": "applyConsumerConnection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "address": {
                    "type": "string"
                  },
                  "category": {
                    "enum": [
                      "residential",
                      "commercial",
                      "industrial",
                      "institutional",
                      "government"
                    ],
                    "type": "string"
                  },
                  "customer_id": {
                    "description": "Ignored for consumer requests; customer is resolved from the caller's account membership.",
                    "type": "string"
                  },
                  "diameter_mm": {
                    "minimum": 1,
                    "type": "integer"
                  },
                  "gps_coordinates": {
                    "type": "string"
                  },
                  "notes": {
                    "type": "string"
                  },
                  "pipe_diameter_mm": {
                    "type": "integer"
                  },
                  "pipe_material": {
                    "type": "string"
                  },
                  "pressure_zone_id": {
                    "type": "string"
                  },
                  "property_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "property_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Connection application submitted"
          },
          "400": {
            "description": "Invalid request or property identifier"
          },
          "403": {
            "description": "Consumer context or connection.manage permission is required"
          },
          "404": {
            "description": "Property is outside the consumer's account scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Apply for a new water service connection"
      }
    },
    "$CONSUMER_API/connections/{id}": {
      "get": {
        "description": "Returns one service connection, such as a new water connection application, when it belongs to an account in the caller's linked account scope. The tenant is taken from X-Tenant-ID or the token when set, otherwise all of the caller's tenants are searched; anything outside the scope returns 404.",
        "operationId": "getConsumerConnection",
        "parameters": [
          {
            "description": "Identifier of the connection to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Connection visible to the authenticated consumer"
          },
          "404": {
            "description": "Connection is missing or outside the consumer's account scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get connection details within the consumer's linked account scope"
      }
    },
    "$CONSUMER_API/consumption": {
      "get": {
        "description": "Pages the computed consumption records of one account linked to the caller, such as usage per billing cycle. account_id is required (400 without it) and the caller needs read access to that account, otherwise 403. Pagination uses limit and after.",
        "operationId": "listConsumerConsumption",
        "parameters": [
          {
            "description": "Tenant (utility workspace) that owns the account; when omitted it is worked out from the caller's account memberships.",
            "in": "query",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required identifier of the linked account whose consumption is listed.",
            "in": "query",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only consumption measured by this meter of the account.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only consumption for this billing cycle.",
            "in": "query",
            "name": "cycle_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account consumption after membership authorization"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List immutable consumption for an explicitly linked account"
      }
    },
    "$CONSUMER_API/credits": {
      "get": {
        "description": "Returns the credit balance of an account linked to the caller, with its credit grants such as promotional credit. Returns 403 when the given account is not one the caller can access and 404 when the caller has no linked account.",
        "operationId": "getConsumerCredits",
        "parameters": [
          {
            "description": "Account whose credit balance is returned; when omitted, the first account in the caller's scope is used.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Account credit balance summary"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get consumer account credit balance and active grants"
      }
    },
    "$CONSUMER_API/credits/redeem": {
      "post": {
        "description": "Redeems a promotion code for an account linked to the caller, creating a credit grant from the campaign's amount, charge kinds and expiry and applying it to the account's open invoices. account_id and code are required. Returns 409 when the campaign is not active, has not started or has ended, or after 5 attempts per minute for the same account; returns 403 when the account is outside the caller's scope.",
        "operationId": "redeemPromoCode",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Promotional credit granted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Redeem a promotional credit code"
      }
    },
    "$CONSUMER_API/developer/api-keys": {
      "get": {
        "description": "Returns the personal API keys the caller owns, one cursor page at a time. Keys belong to the person, not to an account or utility. Each key is identified by prefix and last four characters with its computed status (active, expired or revoked); the secret is never returned again. Only a consumer identity may call it, and the call may be made with a personal API key; any other principal type receives 403.",
        "operationId": "listConsumerDeveloperApiKeys",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKeyPage"
                }
              }
            },
            "description": "Personal API keys"
          },
          "400": {
            "description": "Invalid cursor (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The caller is not a consumer identity"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the caller's personal API keys"
      },
      "post": {
        "description": "Issues a personal API key that acts as the caller on the consumer API and returns its full secret only in this response. Scopes are account permissions, not staff scopes: a secret key (no scopes given) carries every account permission the caller holds now, and a restricted key needs at least one scope, each of which the caller must hold on at least one linked account (see the scopes call). Personal keys are live only: mode test returns 400. Every time the key is used, the server checks that its owner still holds every scope on it and refuses the key otherwise. Each consumer operation needs one scope from a key (reads of accounts, readings and requests need account.read; bills, payments and debt need invoice.read; paying needs payment.create; submitting readings needs reading.create; tickets, invoice disputes and leak allowance applications need ticket.create; connection and service work needs connection.manage; delegates need member.invite), and a key without it gets 403. Changes to the person's relationships, account links, account memberships, profile, inbox and keys refuse every key with 403 and code api_key_not_allowed. The request must come from the person, not from an API key (403 with code api_key_not_allowed). A missing or over-long name (128 characters), a past expires_at, an invalid allowed_ips entry, scopes on a secret key or a restricted key without scopes return 400; a scope the caller does not hold returns 403. The creation is written to the audit trail.",
        "operationId": "createConsumerDeveloperApiKey",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeveloperApiKey"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKey"
                }
              }
            },
            "description": "Key created; secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a consumer identity, called with an API key, or scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a personal API key; the full key appears once in the response"
      }
    },
    "$CONSUMER_API/developer/api-keys/{id}": {
      "delete": {
        "description": "Ends one of the caller's personal keys at once, so requests made with it fail from now on, and writes an audit record. Revoking a key that is already revoked succeeds. The request must come from the person, not from an API key. An unknown key returns 404.",
        "operationId": "revokeConsumerDeveloperApiKey",
        "parameters": [
          {
            "description": "Identifier of the caller's personal API key to revoke.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a consumer identity, or called with an API key"
          },
          "404": {
            "description": "Key not found among the caller's personal keys"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a personal API key immediately"
      }
    },
    "$CONSUMER_API/developer/api-keys/{id}/roll": {
      "post": {
        "description": "Issues a replacement for one of the caller's personal keys with the same name, kind, mode, scopes, allowed IPs and expiry, returns its secret once, and keeps the old key valid for overlap_seconds (default 24 hours, maximum 7 days, never past the old key's own expiry). Only an active key that has not already been rolled can be rolled; otherwise the response is 409. Unlike staff keys, rolling does not re-check the key's scopes against what the caller holds now; the check made each time a key is used still applies. The request must come from the person, not from an API key. An unknown key returns 404. The roll is written to the audit trail.",
        "operationId": "rollConsumerDeveloperApiKey",
        "parameters": [
          {
            "description": "Identifier of the caller's active personal API key to replace.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeveloperRoll"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKey"
                }
              }
            },
            "description": "Replacement key; secret is shown only here"
          },
          "400": {
            "description": "Invalid JSON body or overlap_seconds out of range (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a consumer identity, or called with an API key"
          },
          "404": {
            "description": "Key not found among the caller's personal keys"
          },
          "409": {
            "description": "Key is not active or was already rolled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace a personal API key, keeping the old one valid for the overlap"
      }
    },
    "$CONSUMER_API/developer/scopes": {
      "get": {
        "description": "Returns, sorted and without duplicates, the account permissions the caller holds across the active memberships of every account linked to them (for example invoice.read or payment.create). These are the only scopes a personal API key may carry, and a secret key created now would carry exactly this list. An account holder whose membership lists no explicit permissions counts as holding account.read, invoice.read, payment.create, reading.create, ticket.create, connection.manage and member.invite. Only a signed-in consumer identity may call it; any other principal type receives 403.",
        "operationId": "getConsumerDeveloperScopes",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperScopes"
                }
              }
            },
            "description": "Scopes a personal API key may carry"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "The caller is not a consumer identity"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Account permissions the caller can put on a personal API key"
      }
    },
    "$CONSUMER_API/first-run/abandon": {
      "post": {
        "description": "Records that the user explicitly exited or cancelled the journey at the given step. It is sent only after an explicit exit; closing a tab, losing the network or inactivity are never recorded. The body carries only the opaque run token and the stable step ID: no reason text or identity. Repeats are idempotent. Requires an authenticated resident and a run token issued to them or the anonymous resident entry token.",
        "operationId": "abandonConsumerFirstRun",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunAbandonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Exit recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid or expired run token, or unknown step"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the token was issued to someone else"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The step is already done"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an explicit exit from a first-use journey"
      }
    },
    "$CONSUMER_API/first-run/progress": {
      "get": {
        "description": "Returns the durable progress of the signed-in resident for one journey (resident_link, resident_connection): every step by stable ID in server order, its state (todo, done, skipped or blocked with a reason), whether and why it can be skipped, who changed it and when, and the qualifying action that completed it. A journey with no record returns its steps as todo. The response also carries an opaque run token the client sends back in the X-First-Run-Token header so funnel events join without storing who ran them. Requires an authenticated resident.",
        "operationId": "getConsumerFirstRunProgress",
        "parameters": [
          {
            "description": "Journey ID",
            "in": "query",
            "name": "journey",
            "required": true,
            "schema": {
              "enum": [
                "resident_link",
                "resident_connection"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirstRunProgress"
                }
              }
            },
            "description": "Journey progress"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or entitlement"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Journey not available to this audience"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read first-use progress for one journey"
      }
    },
    "$CONSUMER_API/first-run/progress/{journey}/{step}": {
      "patch": {
        "description": "Records an explicit skip (state skipped with a reason_code from the step's allowed_skip_reasons) or resumes a skipped step (state todo). A client can never write done or blocked: domain actions complete steps and prerequisites block them. A done step cannot be reopened (409). Security, identity and legal steps and the moment-of-value steps have no skip reasons. Requires an authenticated resident.",
        "operationId": "updateConsumerFirstRunStep",
        "parameters": [
          {
            "description": "Journey ID",
            "in": "path",
            "name": "journey",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Step ID",
            "in": "path",
            "name": "step",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunStepUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirstRunProgress"
                }
              }
            },
            "description": "Updated journey progress"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not skippable, unknown reason or a state the client cannot write"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unknown journey or step"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The step is done"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Skip or resume one first-use step"
      }
    },
    "$CONSUMER_API/inbox": {
      "get": {
        "description": "Returns the in-app messages addressed to the signed-in person across every utility, newest first, one cursor page at a time. Only messages with both a title and a body are listed, and archived messages are hidden unless include_archived is true. The caller must be a consumer identity that is not bound to a tenant; a staff or tenant-bound token receives 403. No account permission is needed, since the inbox belongs to the person.",
        "operationId": "listConsumerNotificationInbox",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "When true, return only messages that have not been marked read; accepts Go boolean strings (true, false, 1, 0, t, f) and returns 400 for anything else.",
            "in": "query",
            "name": "unread_only",
            "schema": {
              "default": false,
              "type": "boolean"
            }
          },
          {
            "description": "When true, also return archived messages, which are hidden by default; accepts Go boolean strings and returns 400 for anything else.",
            "in": "query",
            "name": "include_archived",
            "schema": {
              "default": false,
              "type": "boolean"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerInboxPage"
                }
              }
            },
            "description": "The caller's inbox messages"
          },
          "400": {
            "description": "Invalid limit, boolean filter or cursor"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity, or the token is bound to a tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List in-app messages addressed to the caller"
      }
    },
    "$CONSUMER_API/inbox/{id}/archive": {
      "post": {
        "description": "Sets the archive time on a message in the caller's own inbox and returns the updated message; archived messages are hidden from the inbox list unless include_archived is set. Archiving does not mark the message read, and repeating the call keeps the original archive time. A message addressed to anyone else, or that does not exist, returns 404. The caller must be a consumer identity that is not bound to a tenant.",
        "operationId": "archiveConsumerNotification",
        "parameters": [
          {
            "description": "Identifier of a message in the caller's inbox.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationInboxItem"
                }
              }
            },
            "description": "Updated inbox message"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity, or the token is bound to a tenant"
          },
          "404": {
            "description": "Message not found in the caller's inbox"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Archive one of the caller's inbox messages"
      }
    },
    "$CONSUMER_API/inbox/{id}/read": {
      "post": {
        "description": "Sets the read time on a message in the caller's own inbox and returns the updated message. The call is idempotent: a message already read keeps its original read time. A message addressed to anyone else, or that does not exist, returns 404. The caller must be a consumer identity that is not bound to a tenant.",
        "operationId": "markConsumerNotificationRead",
        "parameters": [
          {
            "description": "Identifier of a message in the caller's inbox.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationInboxItem"
                }
              }
            },
            "description": "Updated inbox message"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity, or the token is bound to a tenant"
          },
          "404": {
            "description": "Message not found in the caller's inbox"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark one of the caller's inbox messages as read"
      }
    },
    "$CONSUMER_API/interruptions": {
      "get": {
        "description": "An account's areas are derived from the reading routes covering its meters and from service areas named like the property's locality or district. Finished interruptions are omitted.",
        "operationId": "listConsumerInterruptions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Narrow to one of the caller's tenants",
            "in": "header",
            "name": "X-Tenant-ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/SupplyInterruption"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Interruptions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Planned or active interruptions affecting the service areas of the caller's accounts"
      }
    },
    "$CONSUMER_API/invoices": {
      "get": {
        "description": "Pages the invoices of accounts linked to the caller, across tenants unless X-Tenant-ID selects one. Filter with account_id (which must be one of the caller's accounts) and status; pagination uses limit and after.",
        "operationId": "listConsumerInvoices",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Restrict results to one linked consumer account.",
            "in": "query",
            "name": "account_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoices authorized for this consumer identity"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List invoices for explicitly linked consumer accounts"
      }
    },
    "$CONSUMER_API/invoices/{id}": {
      "get": {
        "description": "Returns one invoice, including its lines and balance, when it belongs to an account linked to the caller. Invoices outside the caller's account scope return 404.",
        "operationId": "getConsumerInvoice",
        "parameters": [
          {
            "description": "Identifier of the invoice to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Invoice in an account linked to the authenticated consumer"
          },
          "404": {
            "description": "Invoice is missing or not visible to the authenticated consumer"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an invoice authorized for the authenticated consumer"
      }
    },
    "$CONSUMER_API/invoices/{id}/dispute": {
      "post": {
        "description": "Records a required reason, and optionally the line item or charge code being contested, and returns the invoice with its dispute details. While the dispute is open the account is left out of cutoff and late-penalty runs until the utility resolves it. Disputing again replaces the earlier dispute details. The invoice must be on an account where the caller holds the invoice.read account permission, found across the caller's tenants unless X-Tenant-ID narrows the search; any other invoice returns 404. Disputing also needs the ticket.create permission on the invoice's account (a personal API key needs the ticket.create scope); without it the call returns 403. A blank reason, a void invoice, a line_item_id that is not on the invoice or an unknown body field returns 400.",
        "operationId": "disputeConsumerInvoice",
        "parameters": [
          {
            "description": "ID of the invoice to dispute; it must be on one of the caller's accounts.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Narrow the invoice lookup to one of the caller's tenants.",
            "in": "header",
            "name": "X-Tenant-ID",
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumerInvoiceDispute"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/BillingInvoice"
                }
              }
            },
            "description": "Invoice marked as disputed"
          },
          "400": {
            "description": "Reason missing, invalid line item, unknown field, or the invoice is void"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity"
          },
          "404": {
            "description": "Invoice not found among the caller's accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Dispute an invoice on one of the caller's accounts"
      }
    },
    "$CONSUMER_API/invoices/{id}/notes": {
      "get": {
        "description": "Notes the server wrote carry `reason_code` and `reason_params` so clients word them in the reader's language; `reason` is the stored fallback.",
        "operationId": "listConsumerInvoiceNotes",
        "parameters": [
          {
            "description": "Identifier of the invoice whose debit and credit notes are listed; it must belong to an account linked to the caller.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Notes of an invoice in an account linked to the authenticated consumer, oldest first"
          },
          "404": {
            "description": "Invoice is missing or not visible to the authenticated consumer"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the debit and credit notes of an invoice authorized for the authenticated consumer"
      }
    },
    "$CONSUMER_API/invoices/{id}/pdf": {
      "get": {
        "description": "Renders the invoice as a PDF, with the tenant's payment instructions, when it belongs to an account linked to the caller. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Returns 404 when the invoice is missing or outside the caller's scope.",
        "operationId": "getConsumerInvoicePDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Invoice id",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download one of the caller's invoices as PDF"
      }
    },
    "$CONSUMER_API/leak-allowances": {
      "get": {
        "description": "Pages the leak allowance applications on accounts linked to the caller, across tenants unless X-Tenant-ID selects one. An empty page is returned when the caller has no eligible account. Pagination uses limit and after.",
        "operationId": "consumerListLeakAllowances",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the consumer's leak allowance applications"
      },
      "post": {
        "description": "Applies for a leak allowance (a credit for excess consumption caused by a leak) on an invoice of a linked account, sent as multipart/form-data with invoice_id, an optional description and an optional proof file (PDF, JPEG or PNG). The invoice is assessed against the tenant's policy first; an ineligible invoice returns 400 LEAK_ALLOWANCE_INELIGIBLE, a missing proof when the policy requires one returns 400, and an invoice that already has an open application returns 409. On success the application is created in submitted status with the proposed credit for staff review.",
        "operationId": "consumerApplyLeakAllowance",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "description": {
                    "type": "string"
                  },
                  "invoice_id": {
                    "type": "string"
                  },
                  "proof": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "invoice_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Apply with proof of repair (multipart: invoice_id, description, proof)"
      }
    },
    "$CONSUMER_API/leak-allowances/assess": {
      "post": {
        "description": "Checks whether an invoice of a linked account qualifies for a leak allowance without saving anything. The result says whether it is eligible, why not (for example the policy is disabled, the invoice is closed, the repair window or cooldown applies, or there is not enough history), and the historic average, excess consumption and proposed credit. invoice_id is required; an invoice outside the caller's scope returns 404.",
        "operationId": "consumerAssessLeakAllowance",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "required": [
                  "invoice_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LeakAllowanceAssessment"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid request or invoice is ineligible (`LEAK_ALLOWANCE_INELIGIBLE`)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check an invoice against the leak allowance policy"
      }
    },
    "$CONSUMER_API/leak-allowances/{id}": {
      "get": {
        "description": "Returns one leak allowance application, with its status, assessment figures and decision, when it belongs to an account linked to the caller. Applications outside the caller's scope return 404.",
        "operationId": "consumerGetLeakAllowance",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an application"
      }
    },
    "$CONSUMER_API/meter-inspection-requests": {
      "get": {
        "description": "Pages the meter inspection requests that consumers raised on one linked account. account_id is required (400 without it) and the caller needs read access to the account, otherwise 403. Pagination uses limit and after.",
        "operationId": "listConsumerMeterInspectionRequests",
        "parameters": [
          {
            "description": "Tenant (utility workspace) that owns the account; when omitted it is worked out from the caller's account memberships.",
            "in": "query",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required identifier of the linked account whose inspection requests are listed.",
            "in": "query",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterInspectionRequestPage"
                }
              }
            },
            "description": "Consumer inspection requests in the selected linked account"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List inspection requests for a linked account"
      },
      "post": {
        "description": "Asks the utility to inspect a meter on a linked account, for example when the caller suspects it is faulty. account_id, meter_id, a reason of up to 500 characters and an idempotency_key of up to 160 characters are required; the caller needs the ticket create permission and the meter must belong to the account (403 otherwise). Resending the same key with the same content returns the existing request, while the same key with different content returns 409; the request is created open and the call answers 202.",
        "operationId": "submitConsumerMeterInspectionRequest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumerInspectionRequestSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MeterInspectionRequest"
                }
              }
            },
            "description": "Inspection request submitted"
          },
          "400": {
            "description": "Invalid reason or idempotency key"
          },
          "403": {
            "description": "Consumer lacks ticket.create permission for the linked account"
          },
          "404": {
            "description": "Meter not found in the selected tenant"
          },
          "409": {
            "description": "Idempotency key conflicts with an existing inspection request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request a meter inspection for an explicitly authorized account"
      }
    },
    "$CONSUMER_API/next-steps": {
      "get": {
        "description": "Returns the next one to three actionable steps for the signed-in resident, chosen and ordered by the server from progress, review state, capabilities, counts and connectors; an empty list when nothing is waiting. Each step has a stable ID, localized title and line (saved language, then Accept-Language, then the platform default), the role that acts, a portable action ID the client maps to its own screen, and a help article ID from the shared help registry. Clients keep no step list or order of their own. GET is safe to retry and completes nothing. A linked resident with an open or partly paid invoice still due gets the single step pay_balance (journey resident_link, action resident.pay); a linked resident with nothing due never gets find_utility or verify_account. Requires an authenticated resident.",
        "operationId": "getConsumerNextSteps",
        "parameters": [
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NextSteps"
                }
              }
            },
            "description": "Next steps"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or entitlement"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The next one to three first-use steps"
      }
    },
    "$CONSUMER_API/notification-preferences": {
      "get": {
        "description": "Pages the caller's notification preferences: consent status, preferred locale, per-event and per-channel switches, and quiet hours. Without a tenant (X-Tenant-ID or the utility_id query parameter) it lists the caller's preferences across all tenants; with one, it lists that tenant's preferences when the caller has an account or relationship there, and returns 403 otherwise.",
        "operationId": "listConsumerNotificationPreferences",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Preferences for consumer accounts the principal may manage"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List communication preferences and consent"
      },
      "patch": {
        "description": "Creates or updates the caller's notification preference for one tenant (from utility_id in the body or X-Tenant-ID) or, without a tenant, the caller's general preference. consent_status is required (granted, withdrawn or required_notice_only); preferred_locale must be pt-MZ or en-US; quiet_hours_start and quiet_hours_end must be HH:MM and set together, and timezone needs quiet hours. Events and channels are merged into the stored settings, and an ambiguous or inaccessible tenant returns 400 or 403.",
        "operationId": "updateConsumerNotificationPreferences",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "channels": {
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "description": "Per-channel delivery choices for email, push, and in_app",
                    "type": "object"
                  },
                  "consent_status": {
                    "enum": [
                      "granted",
                      "withdrawn",
                      "required_notice_only"
                    ],
                    "type": "string"
                  },
                  "events": {
                    "additionalProperties": {
                      "type": "boolean"
                    },
                    "description": "Per-event delivery choices",
                    "type": "object"
                  },
                  "preferred_locale": {
                    "enum": [
                      "pt-MZ",
                      "en-US"
                    ],
                    "type": "string"
                  },
                  "quiet_hours_end": {
                    "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                    "type": "string"
                  },
                  "quiet_hours_start": {
                    "pattern": "^([01][0-9]|2[0-3]):[0-5][0-9]$",
                    "type": "string"
                  },
                  "timezone": {
                    "description": "IANA time zone required when quiet hours are set",
                    "type": "string"
                  }
                },
                "required": [
                  "consent_status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NotificationPreference"
                }
              }
            },
            "description": "Updated preference"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update communication preferences and consent"
      }
    },
    "$CONSUMER_API/onboarding": {
      "get": {
        "description": "Returns the signed-in person's onboarding record: profile, notification consent, accepted terms, the list of requirements still to complete, the computed status and the current terms version. Clients use it to decide which onboarding steps to show.",
        "operationId": "getConsumerOnboarding",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerOnboarding"
                }
              }
            },
            "description": "Consumer onboarding"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get consumer onboarding status and requirements"
      },
      "patch": {
        "description": "Updates parts of the caller's onboarding record: profile fields (full_name, email, preferred_language), notification consent, and acceptance of the terms. Accepting terms requires accepted to be true and version to match the current terms version, and records the time and client IP. Invalid fields return a validation error listing each one, and the response is the updated onboarding view with recomputed requirements.",
        "operationId": "updateConsumerOnboarding",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateConsumerOnboarding"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerOnboarding"
                }
              }
            },
            "description": "Updated"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update profile, notification consent or terms"
      }
    },
    "$CONSUMER_API/overview": {
      "get": {
        "description": "Returns a dashboard summary across every account linked to the caller: the total amount due, and per account the open invoice count and balance, the latest meter reading and a consumption series of up to the last 12 periods. Accounts in different tenants are included together.",
        "operationId": "getConsumerOverview",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerOverview"
                }
              }
            },
            "description": "Overview"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Amount due, latest reading and consumption series per linked account"
      }
    },
    "$CONSUMER_API/payment-availability": {
      "get": {
        "description": "Tells the client, per tenant where the caller has an account, whether payments are enabled and which checkout methods can be offered right now, each saying whether it needs the payer's phone. When checkouts go through payment connectors, only methods a connector heard from in the last 90 seconds declares operational are listed, so a client never offers a method the checkout would refuse. The response also lists the methods for which the tenant accepts proofs of payment.",
        "operationId": "getConsumerPaymentAvailability",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "properties": {
                          "available": {
                            "type": "boolean"
                          },
                          "checkout_methods": {
                            "description": "Methods the consumer can pay with in the app now; clients offer these and nothing else. Empty while payments are unavailable or no connector is live.",
                            "items": {
                              "properties": {
                                "code": {
                                  "type": "string"
                                },
                                "label": {
                                  "description": "The utility's own label for the collection channel of this method (the operator's label, or a neutral sample label in a test account); never derived from the code. Absent when no channel names it.",
                                  "type": "string"
                                },
                                "requires_phone": {
                                  "type": "boolean"
                                }
                              },
                              "required": [
                                "code",
                                "requires_phone"
                              ],
                              "type": "object"
                            },
                            "type": "array"
                          },
                          "methods": {
                            "description": "Checkout methods a live payment connector can complete now, as the method codes the connectors declare. Absent when checkouts don't go through connectors; empty when none is live.",
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "proof_methods": {
                            "description": "The utility's enabled collection channels a consumer can pay through outside the app and then send a proof of payment for.",
                            "items": {
                              "type": "string"
                            },
                            "type": "array"
                          },
                          "tenant_id": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "tenant_id",
                          "available"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "One row per tenant the consumer holds an account in"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Whether each utility the consumer belongs to can take payments yet"
      }
    },
    "$CONSUMER_API/payment-baskets": {
      "post": {
        "description": "Starts one payment session per invoice, for 1 to 20 invoices that may belong to different utilities, and returns one result per invoice in request order. Each invoice is checked on its own exactly as when starting a single payment session: it must be on an account where the caller holds the payment.create account permission, have an outstanding balance, and use a payment method the utility currently accepts (with a phone number where the method needs one), and the utility's payments capability must be active. An invoice that fails any check gets a generic error in its result instead of a session, and the rest still proceed, so the response is 200 even when every item fails. An empty basket, more than 20 items, a missing or repeated invoice_id, or an unknown body field returns 400 before any session starts. With an Idempotency-Key header each item is made retry-safe under the key plus its invoice ID.",
        "operationId": "createConsumerPaymentBasket",
        "parameters": [
          {
            "description": "Optional retry key. Each item's session is created under this key joined with the item's invoice ID, so repeating the same basket returns the sessions already started.",
            "in": "header",
            "name": "Idempotency-Key",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConsumerPaymentBasket"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerPaymentBasket"
                }
              }
            },
            "description": "One result per invoice, each with a session or an error"
          },
          "400": {
            "description": "Basket empty, too large, missing or duplicate invoice_id, or malformed body"
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start payments for several invoices at once"
      }
    },
    "$CONSUMER_API/payment-plans": {
      "get": {
        "description": "Pages the payment plans (debt instalment agreements) on accounts linked to the caller. Filter with account_id, case_id and status; pagination uses limit and after.",
        "operationId": "listConsumerPaymentPlans",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Restrict results to one linked consumer account.",
            "in": "query",
            "name": "account_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payment plans"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List payment plans for consumer"
      }
    },
    "$CONSUMER_API/payment-plans/{id}": {
      "get": {
        "description": "Returns one payment plan, with its instalments and status, when it belongs to an account linked to the caller. Plans outside the caller's scope return 404.",
        "operationId": "getConsumerPaymentPlan",
        "parameters": [
          {
            "description": "Identifier of the payment plan to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentPlan"
                }
              }
            },
            "description": "Payment plan belonging to one of the consumer's linked accounts"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "No linked account is available in the selected tenant"
          },
          "404": {
            "description": "Payment plan not found in the authenticated consumer's linked accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a payment plan authorized for the authenticated consumer"
      }
    },
    "$CONSUMER_API/payment-proofs": {
      "get": {
        "description": "Pages the proofs of payment the caller has sent, across their tenants unless X-Tenant-ID selects one, each with its review status. Pagination uses limit and after.",
        "operationId": "consumerListPaymentProofs",
        "parameters": [
          {
            "description": "Returns only proofs sent for this invoice.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only proofs in this review status: pending, approved or rejected.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "approved",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the proofs of payment the consumer sent, with their review status"
      },
      "post": {
        "description": "Sends evidence of a payment made outside the app, such as a bank transfer slip, for staff to review against an invoice of a linked account. Send multipart/form-data with the file field, invoice_id, amount_minor (whole minor units), method, reference, paid_on and an optional note; the caller needs the payment permission on the account. Returns 400 when the tenant does not take proofs for that method, 404 when the invoice is not payable by the caller, and 409 when an open proof with the same reference already exists; the proof is created as pending.",
        "operationId": "consumerSubmitPaymentProof",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "amount_minor": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "file": {
                    "description": "PDF, JPEG or PNG, up to 5 MB",
                    "format": "binary",
                    "type": "string"
                  },
                  "invoice_id": {
                    "type": "string"
                  },
                  "method": {
                    "description": "A method code from the utility's proof_methods in the consumer payment availability: its configured channels that record a reference.",
                    "pattern": "^[a-z][a-z0-9_-]{0,63}$",
                    "type": "string"
                  },
                  "note": {
                    "maxLength": 500,
                    "type": "string"
                  },
                  "paid_on": {
                    "format": "date",
                    "type": "string"
                  },
                  "reference": {
                    "maxLength": 128,
                    "type": "string"
                  }
                },
                "required": [
                  "invoice_id",
                  "amount_minor",
                  "method",
                  "reference",
                  "paid_on",
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created; the proof waits for the utility to review it"
          },
          "409": {
            "description": "A proof with this method and reference was already sent"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send a proof of a payment made outside the app (multipart: invoice_id, amount_minor, method, reference, paid_on, note, file)"
      }
    },
    "$CONSUMER_API/payment-proofs/{id}/file": {
      "get": {
        "description": "Streams the file attached to one of the caller's own proofs of payment, inline with its stored content type and no-store caching. Proofs sent by someone else, or outside the caller's scope, return 404.",
        "operationId": "consumerGetPaymentProofFile",
        "responses": {
          "200": {
            "description": "The stored PDF, JPEG or PNG"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download one of the consumer's own proofs"
      }
    },
    "$CONSUMER_API/payment-sessions": {
      "get": {
        "description": "Pages the checkout sessions the caller started, across their tenants unless X-Tenant-ID selects one, with each session's status (for example pending, confirmed or failed). Pagination uses limit and after.",
        "operationId": "listConsumerPaymentSessions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Payment sessions visible to the authenticated consumer"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List payment sessions for linked accounts"
      },
      "post": {
        "description": "Returns provider-neutral next_action instructions; WSMS does not process payment instruments.",
        "operationId": "createConsumerPaymentSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePaymentSession"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentSession"
                }
              }
            },
            "description": "Payment session created with an external provider"
          },
          "403": {
            "description": "CAPABILITY_INACTIVE: the payments capability is not active because the utility's onboarding is not approved. RFC 7807 Problem Details with code CAPABILITY_INACTIVE and a detail naming the capability."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request provider-hosted checkout for a payable invoice"
      }
    },
    "$CONSUMER_API/payment-sessions/{id}": {
      "get": {
        "description": "Returns one checkout session the caller started, so a client can poll until it is confirmed or failed. Sessions started by someone else or outside the caller's scope return 404.",
        "operationId": "getConsumerPaymentSession",
        "parameters": [
          {
            "description": "Identifier of the payment session to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentSession"
                }
              }
            },
            "description": "Payment session and provider-neutral status"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get payment-session status"
      }
    },
    "$CONSUMER_API/payment-sessions/{id}/sandbox/confirm": {
      "post": {
        "description": "Development-only call that confirms one of the caller's own checkout sessions as if the provider had settled it, recording the payment, receipt and invoice allocation. It is available only when the sandbox payment provider is configured and returns 404 otherwise. Confirming an already confirmed session returns it unchanged.",
        "operationId": "confirmSandboxPaymentSession",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PaymentSession"
                }
              }
            },
            "description": "Confirmed session"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm a sandbox session (development only, 404 otherwise)"
      }
    },
    "$CONSUMER_API/payments": {
      "get": {
        "description": "Pages payments the caller made on accounts linked to them, across tenants unless X-Tenant-ID selects one. Pagination uses limit and after.",
        "operationId": "listConsumerPayments",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only payments on this account; it must be one of the caller's linked accounts.",
            "in": "query",
            "name": "account_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only payments allocated to this invoice.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Payments restricted to the authenticated consumer's linked accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List payments for accounts linked to the authenticated consumer"
      }
    },
    "$CONSUMER_API/prepaid/meters": {
      "get": {
        "description": "Pages the prepaid meters on accounts where the caller has the payment permission, across tenants unless X-Tenant-ID selects one. An empty page is returned when the caller has no such account. Pagination uses limit and after.",
        "operationId": "consumerListPrepaidMeters",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidMeterPage"
                }
              }
            },
            "description": "Prepaid meters linked to the consumer's authorized accounts"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Tenant selector does not match the authenticated context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the consumer's prepaid meters"
      }
    },
    "$CONSUMER_API/prepaid/purchases": {
      "post": {
        "description": "Starts a prepaid purchase (vend) for a meter on one of the caller's accounts: the vend is created pending payment and a payment session is started for amount_cents, and the token is issued once the payment is confirmed. amount_cents and idempotency_key are required, and repeating a key returns the existing vend. Returns 404 for a meter outside the caller's scope, 409 when the meter is not active, and 503 when token generation or the payment provider is unavailable.",
        "operationId": "consumerPurchasePrepaid",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumerPrepaidPurchaseRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidVend"
                }
              }
            },
            "description": "Purchase started; payment settlement and token issuance may still be pending"
          },
          "400": {
            "description": "Invalid purchase request"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Tenant selector does not match the authenticated context"
          },
          "404": {
            "description": "No authorized linked account contains this prepaid meter"
          },
          "409": {
            "description": "Purchase conflicts with the existing state"
          },
          "503": {
            "description": "Payment provider or token generator is unavailable"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Buy prepaid water by mobile money; the token is issued after settlement"
      }
    },
    "$CONSUMER_API/prepaid/vends": {
      "get": {
        "description": "Pages the prepaid purchases (vends) on accounts where the caller has the payment permission, with their status and issued tokens. An empty page is returned when the caller has no such account. Pagination uses limit and after.",
        "operationId": "consumerListPrepaidVends",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidVendPage"
                }
              }
            },
            "description": "Prepaid purchases linked to the consumer's authorized accounts"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Tenant selector does not match the authenticated context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the consumer's purchases"
      }
    },
    "$CONSUMER_API/prepaid/vends/{id}": {
      "get": {
        "description": "Returns one prepaid purchase on an account in the caller's scope, including the token once issued. When the vend is still pending payment, the call first checks its payment session and settles the vend if a confirmation was missed, so polling this call moves a paid vend forward. Vends outside the caller's scope return 404.",
        "operationId": "consumerGetPrepaidVend",
        "parameters": [
          {
            "description": "Identifier of the prepaid vend to return.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^vnd_",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PrepaidVend"
                }
              }
            },
            "description": "Purchase linked to the consumer's authorized accounts"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Tenant selector does not match the authenticated context"
          },
          "404": {
            "description": "Purchase not found in the consumer's authorized accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a purchase, reconciling it if payment has settled"
      }
    },
    "$CONSUMER_API/prepaid/vends/{id}/receipt.pdf": {
      "get": {
        "description": "Renders the PDF receipt of a prepaid purchase on an account in the caller's scope. A receipt exists only after the token has been issued; a vend in any other status returns 404. The locale (pt-MZ or en-US) and layout=mobile query parameters control language and page size.",
        "operationId": "consumerGetPrepaidVendReceipt",
        "parameters": [
          {
            "description": "Identifier of the issued prepaid vend whose receipt is rendered.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^vnd_",
              "type": "string"
            }
          },
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Purchase receipt PDF"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "Tenant selector does not match the authenticated context"
          },
          "404": {
            "description": "Purchase or receipt not found in the consumer's authorized accounts"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the purchase receipt PDF"
      }
    },
    "$CONSUMER_API/reading-disputes": {
      "get": {
        "description": "Pages the disputes raised on meter readings of one linked account. account_id is required (400 without it) and the caller needs read access to the account, otherwise 403. Pagination uses limit and after.",
        "operationId": "listConsumerReadingDisputes",
        "parameters": [
          {
            "description": "Tenant (utility workspace) that owns the account; when omitted it is worked out from the caller's account memberships.",
            "in": "query",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required identifier of the linked account whose reading disputes are listed.",
            "in": "query",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only disputes about this meter reading.",
            "in": "query",
            "name": "reading_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingDisputePage"
                }
              }
            },
            "description": "Disputes in the selected linked account"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List disputes for a reading linked to the authenticated consumer"
      },
      "post": {
        "description": "Disputes a meter reading on a linked account, for example when the recorded value looks wrong. account_id, reading_id, a reason of up to 500 characters and an idempotency_key of up to 160 characters are required, and the reading must belong to the account (403 otherwise). Resending the same key with the same content returns the existing dispute, while the same key with different content returns 409; the dispute is created open for staff review and the call answers 202.",
        "operationId": "submitConsumerReadingDispute",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumerReadingDisputeSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ReadingDispute"
                }
              }
            },
            "description": "Consumer reading dispute submitted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Dispute a reading linked to an explicitly authorized account"
      }
    },
    "$CONSUMER_API/readings": {
      "get": {
        "description": "Pages the meter readings of one linked account, each with its meter serial. account_id is required (400 without it) and the caller needs read access to the account, otherwise 403. Pagination uses limit and after.",
        "operationId": "listConsumerReadings",
        "parameters": [
          {
            "description": "Tenant (utility workspace) that owns the account; when omitted it is worked out from the caller's account memberships.",
            "in": "query",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Required identifier of the linked account whose readings are listed.",
            "in": "query",
            "name": "account_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Returns only readings of this meter.",
            "in": "query",
            "name": "meter_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Returns only readings in this status: submitted, validating, accepted, review_required, rejected or superseded; any other value returns 400.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "submitted",
                "validating",
                "accepted",
                "review_required",
                "rejected",
                "superseded"
              ],
              "type": "string"
            }
          },
          {
            "description": "Returns only readings taken by this method: manual, consumer, remote, imported or estimated; any other value returns 400.",
            "in": "query",
            "name": "method",
            "schema": {
              "enum": [
                "manual",
                "consumer",
                "remote",
                "imported",
                "estimated"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Readings in the selected account after membership authorization"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List readings for an explicitly linked account"
      },
      "post": {
        "description": "Submits a self-read meter value for an active meter on a linked account where the caller has the reading create permission. meter_id, value, a unit that matches the meter's unit, measured_at, client_reading_id (up to 120 characters) and idempotency_key (up to 160 characters) are required, with up to 20 evidence ids. The reading is checked for plausibility and stays submitted (or review_required) for the utility to accept; reusing an idempotency key with different content returns 409, and the call answers 202.",
        "operationId": "submitConsumerMeterReading",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConsumerReadingSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Consumer reading recorded for validation or review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit a meter reading for an explicitly linked account"
      }
    },
    "$CONSUMER_API/receipts": {
      "get": {
        "description": "Pages payment receipts for accounts linked to the caller, across tenants unless X-Tenant-ID selects one. Filter with account_id (which must be one of the caller's accounts) and invoice_id; pagination uses limit and after.",
        "operationId": "listConsumerReceipts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Receipts authorized for this consumer identity"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List payment receipts for explicitly linked consumer accounts"
      }
    },
    "$CONSUMER_API/receipts/{number}": {
      "get": {
        "description": "Returns one payment receipt by its number when it belongs to an account linked to the caller, or was issued to the caller without an account. The tenant is taken from X-Tenant-ID or the token when set, otherwise all of the caller's tenants are searched; anything outside the scope returns 404.",
        "operationId": "getConsumerReceipt",
        "parameters": [
          {
            "description": "Receipt number as printed on the receipt, unique within the tenant.",
            "in": "path",
            "name": "number",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Receipt in an account linked to the authenticated consumer"
          },
          "404": {
            "description": "Receipt is missing or not visible to the authenticated consumer"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a receipt authorized for the authenticated consumer"
      }
    },
    "$CONSUMER_API/receipts/{number}/document": {
      "get": {
        "description": "Renders one of the caller's receipts as a printable HTML page with the tenant's name, logo and footer, served inline with a restrictive content security policy. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale. Receipts outside the caller's scope return 404.",
        "operationId": "getConsumerReceiptDocument",
        "parameters": [
          {
            "description": "Receipt number",
            "in": "path",
            "name": "number",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/html": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "Receipt document"
          },
          "404": {
            "description": "Unknown receipt or not the caller's"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Printable HTML receipt in Portuguese"
      }
    },
    "$CONSUMER_API/receipts/{number}/pdf": {
      "get": {
        "description": "Renders one of the caller's receipts as a PDF, including the paid invoice number when the payment was allocated to one. The locale query parameter (pt-MZ or en-US) picks the language, falling back to the caller's profile locale, and layout=mobile returns a phone-sized layout instead of A4. Receipts outside the caller's scope return 404.",
        "operationId": "getConsumerReceiptPDF",
        "parameters": [
          {
            "description": "Page format. `mobile` is one narrow column sized to its content, for reading on a phone. An unknown value renders A4.",
            "in": "query",
            "name": "layout",
            "required": false,
            "schema": {
              "default": "a4",
              "enum": [
                "a4",
                "mobile"
              ],
              "type": "string"
            }
          },
          {
            "description": "Receipt number",
            "in": "path",
            "name": "number",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/pdf": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "PDF document"
          },
          "403": {
            "description": "Caller may not read this resource"
          },
          "404": {
            "description": "Unknown or foreign resource"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download one of the caller's receipts as PDF"
      }
    },
    "$CONSUMER_API/relationships": {
      "get": {
        "description": "Returns one list, newest first, of everything that links the signed-in person to a utility: account memberships (as holder, delegate, payer, tenant or landlord, with the permissions each grants) and utility-only relationships the person started (requester or follower). Ended and expired entries are included unless filtered out. The caller must be a consumer identity that is not bound to a tenant; otherwise the response is 403.",
        "operationId": "listConsumerRelationships",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Return only entries of this kind: holder, delegate, payer, tenant, landlord, requester or follower.",
            "in": "query",
            "name": "kind",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only entries in this status, for example active, pending_review, ended or expired.",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerRelationshipPage"
                }
              }
            },
            "description": "The caller's relationships"
          },
          "400": {
            "description": "Invalid limit or cursor"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity, or the token is bound to a tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the caller's relationships with utilities"
      },
      "post": {
        "description": "Lets a person follow a utility, or ask it about something, before or without holding an account there. A follower relationship is active at once; a requester relationship starts in pending_review and needs subject_id naming what the request is about. The caller must be a consumer identity that is not bound to a tenant (403 otherwise). A missing tenant_id, a kind other than requester or follower, a requester without subject_id, or an unknown body field returns 400.",
        "operationId": "createConsumerRelationship",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateConsumerRelationship"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConsumerUtilityRelationship"
                }
              }
            },
            "description": "Relationship created"
          },
          "400": {
            "description": "Invalid input"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity, or the token is bound to a tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start a relationship with a utility without an account"
      }
    },
    "$CONSUMER_API/relationships/{id}/end": {
      "post": {
        "description": "Ends an entry from the caller's relationship list. For an account membership the caller leaves the account (recorded as left by the person) and loses the permissions it granted; for a utility-only relationship its status becomes ended. Ending an entry that has already ended succeeds. An ID that is not one of the caller's entries returns 404. The caller must be a consumer identity that is not bound to a tenant.",
        "operationId": "endConsumerRelationship",
        "parameters": [
          {
            "description": "ID of the entry to end, as returned by the list call: a membership ID or a utility relationship ID (prefix `ulr`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Relationship ended"
          },
          "401": {
            "description": "Authentication required"
          },
          "403": {
            "description": "The caller is not a consumer identity, or the token is bound to a tenant"
          },
          "404": {
            "description": "Not one of the caller's relationships"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "End one of the caller's relationships with a utility"
      }
    },
    "$CONSUMER_API/search": {
      "get": {
        "description": "Searches only the accounts the consumer holds a membership on and the resources reachable through those memberships, plus tickets the consumer opened. Lookups run concurrently with a per-request timeout. Sources the caller's scopes exclude are omitted; a source that fails for any other reason is omitted and `partial` becomes true.",
        "operationId": "searchConsumer",
        "parameters": [
          {
            "$ref": "#/components/parameters/SearchQuery"
          },
          {
            "description": "Comma-separated subset of [account, connection, invoice, payment, ticket]. Defaults to all of them; an unknown type is rejected.",
            "in": "query",
            "name": "types",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/SearchLimit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "description": "Matching resources, grouped by type in a stable order"
          },
          "400": {
            "description": "Invalid q, types or limit"
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Search the authenticated consumer's own resources"
      }
    },
    "$CONSUMER_API/service-quotes/{id}/accept": {
      "post": {
        "description": "The request becomes a customer, premise, connection application and an account the requester holds, and the quote an invoice (invoice_id) paid through POST $CONSUMER_API/payment-sessions with a method from GET $CONSUMER_API/payment-availability. Once paid the request is scheduled with an installation work order.",
        "operationId": "acceptConsumerServiceQuote",
        "parameters": [
          {
            "description": "Identifier of the quote to accept (starts with `sqt_`); it must belong to one of the caller's own service requests and be the current issued quote, otherwise the call answers 404 or 400.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "The request, now payment_pending"
          },
          "400": {
            "description": "The quote is no longer open"
          },
          "404": {
            "description": "Missing or someone else's quote"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The quote has expired (SERVICE_QUOTE_EXPIRED); the request returns to the utility for a new one"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept a quote"
      }
    },
    "$CONSUMER_API/service-quotes/{id}/decline": {
      "post": {
        "description": "The request returns to the utility, which may send a revised version.",
        "operationId": "declineConsumerServiceQuote",
        "parameters": [
          {
            "description": "Identifier of the quote to decline (starts with `sqt_`); it must be the current issued quote on one of the caller's own service requests.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeclineQuoteInput"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "The request"
          },
          "400": {
            "description": "The quote is no longer open",
            "or the note is too long": null
          },
          "404": {
            "description": "Missing or someone else's quote"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The quote has expired (SERVICE_QUOTE_EXPIRED)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Decline a quote"
      }
    },
    "$CONSUMER_API/service-requests": {
      "get": {
        "description": "Returns the requests the signed-in identity submitted, across every utility, including requests that have no account yet. Each item shows its current status, any account or connection it led to, and `can_book_visit` when the request is waiting for a site visit to be booked. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listConsumerServiceRequests",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequestPage"
                }
              }
            },
            "description": "The caller's requests across utilities"
          },
          "401": {
            "description": "Not signed in"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the signed-in person's own service requests"
      }
    },
    "$CONSUMER_API/service-requests/{id}": {
      "get": {
        "description": "Returns the request with its current status, refreshed before it is returned (for example, a quote whose invoice has been paid moves the request forward). A request that belongs to another identity answers 404, never 403.",
        "operationId": "getConsumerServiceRequest",
        "parameters": [
          {
            "description": "Identifier of the service request; only requests submitted by the signed-in identity are found.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "The request, including a private decline reason"
          },
          "404": {
            "description": "Missing or someone else's request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one of the signed-in person's own service requests"
      }
    },
    "$CONSUMER_API/service-requests/{id}/quotes": {
      "get": {
        "description": "Returns every quote version the utility has issued for the request, including superseded, declined, expired and accepted ones, so the caller can see the history and find the open quote to accept or decline. The response wraps the list in `data` and is not paginated. A request that belongs to another identity answers 404.",
        "operationId": "getConsumerServiceRequestQuotes",
        "parameters": [
          {
            "description": "Identifier of one of the signed-in identity's own service requests.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceQuoteList"
                }
              }
            },
            "description": "Quote versions, newest first"
          },
          "404": {
            "description": "Missing or someone else's request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the quotes of one of the signed-in person's requests"
      }
    },
    "$CONSUMER_API/service-requests/{id}/site-visits": {
      "post": {
        "description": "Books a site visit so the utility can price a request whose estimate is a range rather than a fixed amount; the `date` must be one of the days returned by the visit-slots operation, and `notes` are limited to 1000 characters. Booking cancels any visit still scheduled on the request and supersedes an open quote, and the request moves to `visit_scheduled`. Returns 201 with the visit; a request that does not need a visit now (already priced exactly, or past the submitted and accepted states) answers 400.",
        "operationId": "bookConsumerServiceRequestSiteVisit",
        "parameters": [
          {
            "description": "Identifier of one of the signed-in identity's own service requests that is waiting for a visit to be booked.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BookSiteVisitInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SiteVisit"
                }
              }
            },
            "description": "Booked visit"
          },
          "400": {
            "description": "Day not offered",
            "or the request needs no visit now": null
          },
          "404": {
            "description": "Missing or someone else's request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Book a site visit on one of the offered days"
      }
    },
    "$CONSUMER_API/service-requests/{id}/visit-slots": {
      "get": {
        "description": "Empty unless can_book_visit is true on the request (a price that depends on the site).",
        "operationId": "getConsumerServiceRequestVisitSlots",
        "parameters": [
          {
            "description": "Identifier of one of the signed-in identity's own service requests; when the request does not need a visit the response holds an empty list of dates.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/VisitSlots"
                }
              }
            },
            "description": "Offered days"
          },
          "404": {
            "description": "Missing or someone else's request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the days the requester can choose for a site visit"
      }
    },
    "$CONSUMER_API/service-requests/{id}/withdraw": {
      "post": {
        "description": "Moves the request to `withdrawn` and closes everything open on it: an issued quote is cancelled, an accepted quote has its invoice voided, a scheduled site visit is cancelled and a connection that is not yet active is retired. A request can be withdrawn at any point before its quote is paid; once it is scheduled, completed, declined or already withdrawn the call answers 400. Returns the updated request.",
        "operationId": "withdrawConsumerServiceRequest",
        "parameters": [
          {
            "description": "Identifier of one of the signed-in identity's own open service requests.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ServiceRequest"
                }
              }
            },
            "description": "Withdrawn request"
          },
          "400": {
            "description": "The request is no longer open"
          },
          "404": {
            "description": "Missing or someone else's request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Withdraw one of the signed-in person's open service requests"
      }
    },
    "$CONSUMER_API/tickets": {
      "get": {
        "description": "Returns the tickets the caller opened plus tickets on accounts the caller can read, across the utilities where the caller holds accounts, or only one utility when the `X-Tenant-ID` header selects it. The list can be narrowed with `account_id`, `category` and `status`, and is cursor-paginated with `limit` (default 20, at most 100) and `after`. Answers 403 when the caller has no consumer access.",
        "operationId": "listConsumerTickets",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Consumer tickets"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List consumer support tickets"
      },
      "post": {
        "description": "Opens a ticket in the `open` status on behalf of the signed-in person; `subject` and `description` are required, `category` defaults to `complaint` and `priority` to `medium`. When `account_id` is given, the ticket is filed with the utility that holds that account and the caller must be allowed to open tickets on it (403 otherwise); without it, the utility comes from the `X-Tenant-ID` header or the caller's only utility, and the call answers 400 when the choice is ambiguous. Returns 201 with the new ticket.",
        "operationId": "createConsumerTicket",
        "responses": {
          "201": {
            "description": "Ticket submitted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit a consumer complaint or service request"
      }
    },
    "$CONSUMER_API/tickets/{id}": {
      "get": {
        "description": "Returns the ticket with its status, category, priority and timestamps. Only tickets the caller opened, or tickets on accounts the caller can read, are found; any other ticket answers 404.",
        "operationId": "getConsumerTicket",
        "parameters": [
          {
            "description": "Identifier of the ticket (starts with `tkt_`); it must be one the caller opened or one on an account the caller can read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Consumer ticket details"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get consumer ticket details"
      }
    },
    "$CONSUMER_API/tickets/{id}/comments": {
      "get": {
        "description": "Returns the conversation on a ticket, with comments from both the caller and utility staff marked by `author_type` (`consumer` or `staff`). The caller must be able to read the ticket, otherwise the call answers 404. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listConsumerTicketComments",
        "parameters": [
          {
            "description": "Identifier of a ticket the caller opened or that is on an account the caller can read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Comments"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List comments on consumer ticket"
      },
      "post": {
        "description": "Adds a comment authored by the signed-in person; `content` is required and an empty value answers 400. When the ticket was waiting on the consumer (`pending_consumer`), the comment moves it back to `in_progress`. Returns 201 with the comment; a ticket the caller cannot read answers 404.",
        "operationId": "addConsumerTicketComment",
        "parameters": [
          {
            "description": "Identifier of a ticket the caller opened or that is on an account the caller can read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "201": {
            "description": "Comment added"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add comment to consumer ticket"
      }
    },
    "$PLATFORM_API/appliance/available": {
      "get": {
        "description": "Requires the platform owner role and `platform:appliance:read`.",
        "operationId": "getApplianceAvailability",
        "responses": {
          "204": {
            "description": "Appliance controls are enabled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check whether this server is appliance-enabled",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:read"
        ]
      }
    },
    "$PLATFORM_API/appliance/backup": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "runApplianceBackup",
        "responses": {
          "204": {
            "description": "Backup started"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Start an appliance backup",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/backup-target": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceBackupTarget",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "recipient": {
                    "type": "string"
                  },
                  "target": {
                    "type": "string"
                  }
                },
                "required": [
                  "target",
                  "recipient"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Backup target configured"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Configure appliance backup target",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/console-pin": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceConsolePIN",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "pin": {
                    "pattern": "^[0-9]{6,12}$",
                    "type": "string"
                  }
                },
                "required": [
                  "pin"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Console PIN saved"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Set the local appliance console PIN",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/domain": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceDomain",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "domain": {
                    "maxLength": 253,
                    "type": "string"
                  }
                },
                "required": [
                  "domain"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Domain configuration applied"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Configure the appliance domain",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/factory-reset": {
      "post": {
        "description": "Fails closed until owner password re-authentication is wired. Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "requestApplianceFactoryReset",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "box_name": {
                    "type": "string"
                  },
                  "confirmation": {
                    "type": "string"
                  },
                  "password": {
                    "type": "string",
                    "writeOnly": true
                  }
                },
                "required": [
                  "box_name",
                  "password",
                  "confirmation"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "501": {
            "description": "Password re-authentication is not available; reset is refused"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request appliance factory reset",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/heartbeat": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceHeartbeat",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "enabled": {
                    "type": "boolean"
                  },
                  "endpoint": {
                    "format": "uri",
                    "type": "string"
                  }
                },
                "required": [
                  "enabled"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Heartbeat settings saved"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Configure opt-in appliance heartbeat",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/proxy": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceProxy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "https_proxy": {
                    "format": "uri",
                    "type": "string"
                  },
                  "no_proxy": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Proxy settings saved"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Configure appliance outbound proxy",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/status": {
      "get": {
        "description": "Returns appliance state from the local privileged helper. Requires the platform owner role and `platform:appliance:read`.",
        "operationId": "getApplianceStatus",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "Appliance status"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get appliance status",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:read"
        ]
      }
    },
    "$PLATFORM_API/appliance/support-bundle": {
      "get": {
        "description": "The bundle contains allowlisted configuration and operational state only. Requires the platform owner role and `platform:appliance:read`.",
        "operationId": "downloadApplianceSupportBundle",
        "responses": {
          "200": {
            "content": {
              "application/zstd": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Compressed support bundle"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Generate and download an appliance support bundle",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:read"
        ]
      }
    },
    "$PLATFORM_API/appliance/support-tunnel": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceSupportTunnel",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "authorized_keys": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "enabled": {
                    "type": "boolean"
                  },
                  "expires_in_hours": {
                    "maximum": 168,
                    "minimum": 1,
                    "type": "integer"
                  },
                  "hub": {
                    "type": "string"
                  },
                  "public_key": {
                    "type": "string"
                  }
                },
                "required": [
                  "enabled"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Support tunnel state changed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Enable or disable the appliance support tunnel",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/time-server": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "setApplianceTimeServer",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "server": {
                    "maxLength": 253,
                    "type": "string"
                  }
                },
                "required": [
                  "server"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "NTP server configured"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Configure appliance NTP server",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/updates/check": {
      "post": {
        "description": "Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "checkApplianceUpdates",
        "responses": {
          "204": {
            "description": "Update check started"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check for appliance updates",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/appliance/updates/upload": {
      "post": {
        "description": "The helper verifies the signed manifest and artifact hashes before writing the inactive system slot. Requires the platform owner role and `platform:appliance:manage`.",
        "operationId": "uploadApplianceUpdate",
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "update": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "update"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Update accepted and application started"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload and apply a signed offline appliance update",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:appliance:manage"
        ]
      }
    },
    "$PLATFORM_API/attention": {
      "get": {
        "description": "Each source is queried independently with a short deadline. A failed source is left out and sets partial. Items at zero are not returned.",
        "operationId": "getPlatformAttention",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AttentionReport"
                }
              }
            },
            "description": "Work queue"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "403": {
            "$ref": "#/components/responses/Forbidden"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Work queue for the platform home (RFC 0065). Counts only, filtered by the caller's scopes",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:overview:read"
        ]
      }
    },
    "$PLATFORM_API/audit/events": {
      "get": {
        "description": "Requires the `platform:audit:read` permission; without it the call answers 403. Events can be narrowed by `actor_id`, `action`, `resource_type`, `resource_id` and an RFC 3339 `from`/`to` window (unparseable timestamps are ignored), and each event carries a readable summary in the caller's locale. Results are cursor-paginated with `limit` and `after`.",
        "operationId": "listPlatformAuditEvents",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Restrict to one tenant; omit to read across tenants",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by exact action code, e.g. ticket.closed",
            "in": "query",
            "name": "action",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by actor",
            "in": "query",
            "name": "actor_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by resource type",
            "in": "query",
            "name": "resource_type",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by resource",
            "in": "query",
            "name": "resource_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC3339 start",
            "in": "query",
            "name": "from",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "RFC3339 end",
            "in": "query",
            "name": "to",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/AuditEventPage"
                }
              }
            },
            "description": "Audit events, newest first"
          },
          "403": {
            "description": "Missing platform:audit:read scope or platform principal context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List recent audit events across tenants, or one tenant's when tenant_id is given",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:audit:read"
        ]
      }
    },
    "$PLATFORM_API/billing/campaigns": {
      "get": {
        "description": "Newest first, one cursor page at a time. The response is the standard page (data, has_more, next_cursor); items repeats data for older clients.",
        "operationId": "listPlatformCampaigns",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Campaign page"
          },
          "400": {
            "description": "Invalid cursor"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform promotional campaigns",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:subscriptions:read"
        ]
      },
      "post": {
        "description": "Creates a promo-code campaign in the `draft` status; `name`, `code` and a positive `amount_minor` are required. The code is stored only as a hash with its first four characters kept for display, so it cannot be read back later. `currency` defaults to MZN and `per_tenant_limit` to 1; the campaign accepts no redemptions until it is activated.",
        "operationId": "createPlatformCampaign",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Platform campaign created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a platform promotional campaign",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:subscriptions:write"
        ]
      }
    },
    "$PLATFORM_API/billing/campaigns/{id}/activate": {
      "post": {
        "description": "Moves a campaign from `draft` or `paused` to `active`, after which utilities can redeem its code for platform credit. Requires the `platform:subscriptions:write` permission and returns the updated campaign; an unknown campaign answers 404.",
        "operationId": "activatePlatformCampaign",
        "parameters": [
          {
            "description": "Identifier of the campaign to activate (starts with `ppc_`); it must be in the `draft` or `paused` status.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Platform campaign activated"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate a platform promotional campaign",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:subscriptions:write"
        ]
      }
    },
    "$PLATFORM_API/billing/credit-grants": {
      "post": {
        "description": "Creates an active credit grant for a utility; `tenant_id` and a positive `amount_minor` are required. `funding` defaults to `granted`, `source` to `promotion` and `currency` to MZN, and an optional `expires_at` limits how long the grant counts. The new credit is applied straight away to the utility's open platform invoices, and the response shows the grant with what remains after that. Requires the `platform:subscriptions:write` permission.",
        "operationId": "grantPlatformCredit",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Platform credit grant created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Grant platform credit to a utility tenant",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:subscriptions:write"
        ]
      }
    },
    "$PLATFORM_API/billing/invoices": {
      "get": {
        "description": "Returns the invoices the platform issued to utilities and organizations for their subscriptions, newest first, with balance and status. Requires the `platform:billing:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listPlatformInvoices",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Limits the list to invoices issued to this utility workspace; omit it to list invoices of every utility.",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Limits the list to invoices in this status: `open` (balance still due), `paid` or `void`.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "open",
                "paid",
                "void"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformInvoicePage"
                }
              }
            },
            "description": "Invoices"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform invoices across utilities",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/billing/invoices/{id}": {
      "get": {
        "description": "Returns the invoice with its lines, total, outstanding balance, due date and status, whichever utility or organization it was issued to. Requires the `platform:billing:read` permission; an unknown invoice answers 404.",
        "operationId": "getPlatformInvoice",
        "parameters": [
          {
            "description": "Identifier of the platform invoice.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformInvoice"
                }
              }
            },
            "description": "Invoice"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one platform invoice",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/billing/invoices/{id}/pay": {
      "post": {
        "description": "Records a payment received outside the API against the invoice: `amount_cents` must be positive, `reference` is required, and `method` must be one of the configured payment methods (it may be left out when only one is configured). The amount is capped at the outstanding balance; when the balance reaches zero the invoice becomes `paid`, an invoice-paid event is emitted, and a past-due or suspended subscription returns to active once no overdue invoice remains. Repeating the call with the same reference returns the first payment with `duplicate: true` and changes nothing; an invoice that is not open answers 409.",
        "operationId": "payPlatformInvoice",
        "parameters": [
          {
            "description": "Identifier of the platform invoice to record the payment on; it must be open.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount_cents": {
                    "minimum": 1,
                    "type": "integer"
                  },
                  "method": {
                    "description": "One of GET $PLATFORM_API/billing/payment-methods. Required unless exactly one method is configured, in which case it is used.",
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  }
                },
                "required": [
                  "amount_cents",
                  "reference"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "The invoice after payment and whether the reference was a duplicate"
          },
          "400": {
            "description": "method is missing (validation.field_required) or not configured (payment.method_not_configured)"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a payment on a platform invoice; reference makes it idempotent",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:billing:write"
        ]
      }
    },
    "$PLATFORM_API/billing/payment-methods": {
      "get": {
        "description": "Requires platform:billing:read. Clients word each method from its code.",
        "operationId": "getPlatformPaymentMethods",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "type": "string"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Method codes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Methods a platform payment can be recorded with, in configuration order",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/billing/payment-proofs": {
      "get": {
        "description": "Returns the proofs of payment utilities uploaded for their platform invoices, so operators can review them. Requires the `platform:billing:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listPlatformPaymentProofs",
        "parameters": [
          {
            "description": "Limits the list to proofs in this review state: `pending` (waiting for review), `approved` or `rejected`.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "pending",
                "approved",
                "rejected"
              ],
              "type": "string"
            }
          },
          {
            "description": "Limits the list to proofs uploaded by this utility workspace.",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Limits the list to proofs submitted for this platform invoice.",
            "in": "query",
            "name": "invoice_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utilities' proofs of payment, such as those waiting for review",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/billing/payment-proofs/{id}": {
      "get": {
        "description": "Returns the proof's metadata: the invoice it pays, the amount, reference and method the utility declared, the file name and type, and its review state with reviewer and note once reviewed. The file itself is downloaded with the file operation. Requires the `platform:billing:read` permission; an unknown proof answers 404.",
        "operationId": "getPlatformPaymentProof",
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a utility's proof of payment",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/billing/payment-proofs/{id}/approve": {
      "post": {
        "description": "Records the proof as a payment on its invoice, using the proof's reference and method, and marks the proof `approved`. The optional body can correct `amount_cents` and `reference` (at most 128 characters) before recording and add a `note` of up to 500 characters; an empty body is accepted. The response holds the reviewed proof and the updated invoice. A proof that was already reviewed answers 409, as does an invoice that is no longer open.",
        "operationId": "approvePlatformPaymentProof",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "amount_cents": {
                    "format": "int64",
                    "type": "integer"
                  },
                  "note": {
                    "type": "string"
                  },
                  "reference": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "description": "The approved proof and the invoice"
          },
          "409": {
            "description": "Already reviewed, or the invoice is no longer open"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve: records the payment on the invoice and restores a past-due or suspended utility",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:billing:write"
        ]
      }
    },
    "$PLATFORM_API/billing/payment-proofs/{id}/file": {
      "get": {
        "description": "Streams the uploaded file with its stored content type and an inline `Content-Disposition` carrying the original file name. The response is sent with `Cache-Control: private, no-store` and a sandboxing content security policy, so it can be shown in a browser without running scripts. Requires the `platform:billing:read` permission; an unknown proof answers 404.",
        "operationId": "getPlatformPaymentProofFile",
        "responses": {
          "200": {
            "description": "The stored PDF, JPEG or PNG"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the proof file",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/billing/payment-proofs/{id}/reject": {
      "post": {
        "description": "Marks a pending proof `rejected` without recording any payment, so the invoice stays as it was. `reason` is required and limited to 500 characters; it is stored as the review note the utility sees. A proof that was already reviewed answers 409.",
        "operationId": "rejectPlatformPaymentProof",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "maxLength": 500,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject with a reason the utility will read",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:billing:write"
        ]
      }
    },
    "$PLATFORM_API/billing/subscriptions/{id}/change-plan": {
      "post": {
        "description": "Switches the subscription to the plan in `plan_id` at once. When the subscription is not trialing and the period is still running, the price difference for the rest of the period is prorated and added as a pending line on the next invoice; a downgrade gives a negative amount. Answers 409 when the subscription is cancelled or already on that plan, and 400 when the two plans use different currencies.",
        "operationId": "changePlatformSubscriptionPlan",
        "parameters": [
          {
            "description": "Identifier of the utility subscription whose plan changes.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePlanResult"
                }
              }
            },
            "description": "Result with proration_cents"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change a utility's plan, prorating the difference onto the next invoice",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:billing:write"
        ]
      }
    },
    "$PLATFORM_API/billing/subscriptions/{id}/change-plan/preview": {
      "post": {
        "description": "Runs the same checks and proration as the change-plan operation and returns the source and target plans, the prorated amount, its currency and the current period end, without changing anything. The proration is zero for a trialing subscription or one whose period has ended. Errors match the change: 409 for a cancelled subscription or the same plan, 400 for plans in different currencies.",
        "operationId": "previewPlatformSubscriptionPlanChange",
        "parameters": [
          {
            "description": "Identifier of the utility subscription to preview the plan change for.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ChangePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ChangePlanPreview"
                }
              }
            },
            "description": "Preview with proration_cents"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Compute the proration of a utility's plan change without making it",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:billing:write"
        ]
      }
    },
    "$PLATFORM_API/billing/tenants/{id}/credits": {
      "get": {
        "description": "Returns all of the utility's credit grants with the spendable balance split into cash-funded and granted credit, plus their total. Grants that are exhausted, inactive or past their expiry are listed but not counted in the balances. The caller needs `business:billing:read` on that utility or `platform:subscriptions:read`.",
        "operationId": "getTenantPlatformCredits",
        "parameters": [
          {
            "description": "Identifier of the utility workspace whose platform credits are read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Platform credit summary"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get utility tenant platform credit balance and grants",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:subscriptions:read"
        ]
      }
    },
    "$PLATFORM_API/branding": {
      "get": {
        "description": "Requires platform:branding:read (platform owner).",
        "operationId": "getPlatformBranding",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformBranding"
                }
              }
            },
            "description": "Brand with sources"
          },
          "403": {
            "description": "Missing platform:branding:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The effective brand and where each value comes from",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:read"
        ]
      },
      "patch": {
        "description": "Requires platform:branding:write. Omitted fields stay as they are; null resets a field to the configured value (a null colors object resets all three colours). The nested public shape (support, links objects) is also accepted. The result must keep valid #RRGGBB colours and a brand_foreground on brand contrast of at least 4.5:1. Every change is audited (branding.updated).",
        "operationId": "updatePlatformBranding",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/BrandingPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformBranding"
                }
              }
            },
            "description": "Updated brand with sources"
          },
          "400": {
            "description": "A value is invalid or the colours lack contrast; invalid_params names each field"
          },
          "403": {
            "description": "Missing platform:branding:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Change brand values",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:write"
        ]
      }
    },
    "$PLATFORM_API/branding/assets/{kind}": {
      "delete": {
        "description": "Requires platform:branding:write. Audited as branding.asset_removed.",
        "operationId": "deletePlatformBrandingAsset",
        "parameters": [
          {
            "description": "Which brand file to remove: logo, logo_dark or icon; any other value answers 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformBranding"
                }
              }
            },
            "description": "Updated brand with sources"
          },
          "403": {
            "description": "Missing platform:branding:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Return a brand file to the configured one, or none",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:write"
        ]
      },
      "put": {
        "description": "Requires platform:branding:write. PNG, SVG or WebP, plus ICO for the icon, up to storage.uploads.max_file_bytes. SVG is sanitised: scripts, foreignObject, event handlers and external references are removed; an unparsable SVG is refused. Audited as branding.asset_uploaded.",
        "operationId": "uploadPlatformBrandingAsset",
        "parameters": [
          {
            "description": "Which brand file to replace: logo, logo_dark or icon; any other value answers 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "properties": {
                  "file": {
                    "format": "binary",
                    "type": "string"
                  }
                },
                "required": [
                  "file"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformBranding"
                }
              }
            },
            "description": "Updated brand with sources"
          },
          "400": {
            "description": "The file is empty",
            "too large or not an allowed type": null
          },
          "403": {
            "description": "Missing platform:branding:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload a brand file",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:write"
        ]
      }
    },
    "$PLATFORM_API/calendar": {
      "get": {
        "description": "Returns the platform operator's own working calendar: its time zone, the weekdays it works (0 = Sunday to 6 = Saturday) and any holiday template it follows. When nothing has been saved yet, the defaults are returned (Monday to Friday in the default time zone). Requires the `platform:calendar:read` permission.",
        "operationId": "getPlatformCalendar",
        "responses": {
          "200": {
            "description": "Platform calendar"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the platform's own tenant calendar",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:calendar:read"
        ]
      },
      "put": {
        "description": "Saves the operator's calendar settings: `timezone` must be a known IANA zone and `working_days` holds at most seven weekday numbers from 0 to 6. An empty `timezone` or a missing `working_days` keeps the stored value, while `template_key` and `template_version` are always replaced by what is sent, so leaving them out clears the template. Requires the `platform:calendar:write` permission and returns the saved calendar.",
        "operationId": "updatePlatformCalendar",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated calendar"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Set the platform's own tenant calendar",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:calendar:write"
        ]
      }
    },
    "$PLATFORM_API/calendar/days": {
      "get": {
        "description": "Returns the dated exceptions on the operator's calendar, ordered by date: holidays, closures and extra working days. The list is not paginated and is wrapped in `data`. Requires the `platform:calendar:read` permission.",
        "operationId": "listPlatformCalendarDays",
        "parameters": [
          {
            "description": "Earliest date to include, compared with the day's `YYYY-MM-DD` date and inclusive; omit it for no lower bound.",
            "in": "query",
            "name": "from",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "Latest date to include, compared with the day's `YYYY-MM-DD` date and inclusive; omit it for no upper bound.",
            "in": "query",
            "name": "to",
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Calendar days"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the platform's own holidays and closures",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:calendar:read"
        ]
      },
      "post": {
        "description": "Adds a manual entry to the operator's calendar; `date` must be in `YYYY-MM-DD` format and `kind` is `holiday` (the default), `closure` or `working`. The names fall back from `name` to `name_pt`, and `name_en` copies the Portuguese name when left out. Returns 201 with the new day.",
        "operationId": "addPlatformCalendarDay",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CalendarDayInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Created day"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a day to the platform's own calendar",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:calendar:write"
        ]
      }
    },
    "$PLATFORM_API/calendar/days/{id}": {
      "delete": {
        "description": "Deletes the entry so its date follows the regular working-day rules again. Returns 204 with no body; an unknown day answers 404. Requires the `platform:calendar:write` permission.",
        "operationId": "deletePlatformCalendarDay",
        "parameters": [
          {
            "description": "Identifier of the calendar day to remove (starts with `cdy_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Deleted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a day from the platform's own calendar",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:calendar:write"
        ]
      }
    },
    "$PLATFORM_API/calendar/templates": {
      "get": {
        "description": "Expands the latest version of the country's holiday template, both fixed dates and recurring rules, into the concrete dates that fall in the requested year, sorted by date. Nothing is saved; the dates are meant to be reviewed before they are added to a calendar. An unknown country answers 404.",
        "operationId": "getHolidayTemplates",
        "parameters": [
          {
            "description": "Country code of the holiday template, matched case-insensitively (for example `mz`).",
            "in": "query",
            "name": "country",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Calendar year to expand the template for, as a four-digit number; defaults to the current year.",
            "in": "query",
            "name": "year",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Template days"
          },
          "404": {
            "description": "No template for the country"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a country's holiday template for a year, flagged for confirmation",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:calendar:read"
        ]
      }
    },
    "$PLATFORM_API/collectors": {
      "get": {
        "description": "Returns collectors with their status and when they were last seen. Requires the `platform:collectors:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listCollectors",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Limits the list to collectors of this utility workspace; omit it to list collectors of every utility.",
            "in": "query",
            "name": "tenant_id",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collectors"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List collectors",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      },
      "post": {
        "description": "Registers a collector, the on-site agent that reads meters and runs commands for one utility, in the `registered` status. `tenant_id` and a `name` of at most 120 characters are required, and `description` is limited to 500 characters. The collector cannot connect until a credential is issued for it. Requires the `platform:collectors:manage` permission.",
        "operationId": "createCollector",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "description": {
                    "type": "string"
                  },
                  "name": {
                    "maxLength": 120,
                    "type": "string"
                  },
                  "tenant_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "tenant_id",
                  "name"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Collector created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a collector for a utility",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}": {
      "delete": {
        "description": "Sets the collector to `revoked` and ends all of its open sessions; this cannot be undone, and a revoked collector can no longer receive credentials or assignments. Revoking a collector that is already revoked succeeds without changes. Returns 204 with no body.",
        "operationId": "revokeCollector",
        "parameters": [
          {
            "description": "Identifier of the collector to revoke (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a collector and terminate its sessions",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      },
      "get": {
        "description": "Returns the collector's utility, name, description, status (`registered`, `active`, `suspended` or `revoked`) and timestamps. Requires the `platform:collectors:read` permission; an unknown collector answers 404.",
        "operationId": "getCollector",
        "parameters": [
          {
            "description": "Identifier of the collector (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Collector"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a collector",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      },
      "patch": {
        "description": "Changes only the fields sent: `name` (1 to 120 characters), `description` (at most 500) and `status` (`active`, `suspended` or `revoked`). Suspending or revoking ends the collector's open sessions. A revoked collector cannot be changed, and a collector still `registered` cannot be set to `active` by hand; both answer 409.",
        "operationId": "updateCollector",
        "parameters": [
          {
            "description": "Identifier of the collector to update (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "name": {
                    "type": "string"
                  },
                  "status": {
                    "enum": [
                      "active",
                      "suspended",
                      "revoked"
                    ],
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Collector"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Rename or change a collector status",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/assignments": {
      "get": {
        "description": "Returns the meters assigned to the collector, both active and removed, with device, driver configuration and revision. Requires the `platform:collectors:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listCollectorAssignments",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Identifier of the collector whose assignments are listed (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List meter assignments",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      },
      "post": {
        "description": "Assigns a meter of the collector's utility to the collector, with an optional `device_id` (at most 160 characters) and a free-form `configuration` object passed to the collector's driver. Assigning a meter the collector already has replaces its device and configuration and reactivates it, and every change bumps the revision the collector syncs from. Answers 400 when the meter is not in the collector's utility, and 409 when the collector is revoked or the meter is actively assigned to another collector.",
        "operationId": "createCollectorAssignment",
        "parameters": [
          {
            "description": "Identifier of the collector that receives the meter (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "configuration": {
                    "type": "object"
                  },
                  "device_id": {
                    "type": "string"
                  },
                  "meter_id": {
                    "type": "string"
                  }
                },
                "required": [
                  "meter_id"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Conflict or created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Assign a meter to a collector with opaque driver configuration",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/assignments/{assignment_id}": {
      "delete": {
        "description": "Marks the assignment `removed` and bumps the collector's revision so the collector stops reading that meter on its next sync. The record is kept, and removing an assignment that is already removed succeeds without changes. Returns 204 with no body; an unknown collector or assignment answers 404.",
        "operationId": "removeCollectorAssignment",
        "parameters": [
          {
            "description": "Identifier of the collector that holds the assignment (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the assignment to remove (starts with `cag_`).",
            "in": "path",
            "name": "assignment_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a meter assignment",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/credentials": {
      "get": {
        "description": "Returns the collector's enrollment and public-key credentials with label, expiry and revocation time; enrollment token secrets are never returned. Requires the `platform:collectors:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listCollectorCredentials",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Identifier of the collector whose credentials are listed (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List credentials",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      },
      "post": {
        "description": "Issues a credential the collector uses to authenticate. With `kind: enrollment`, a one-time token is generated and returned only in this response, valid for `expires_in_seconds` (default 24 hours, at most 604800); with `kind: public_key`, `public_key` must be a PEM `PUBLIC KEY` block holding an Ed25519 or RSA key. `label` is limited to 120 characters. A revoked collector answers 409.",
        "operationId": "createCollectorCredential",
        "parameters": [
          {
            "description": "Identifier of the collector the credential is issued to (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "expires_in_seconds": {
                    "type": "integer"
                  },
                  "kind": {
                    "enum": [
                      "enrollment",
                      "public_key"
                    ],
                    "type": "string"
                  },
                  "label": {
                    "type": "string"
                  },
                  "public_key": {
                    "type": "string"
                  }
                },
                "required": [
                  "kind"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Conflict or created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue an enrollment or public key credential; an enrollment token is returned once",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/credentials/{credential_id}": {
      "delete": {
        "description": "Marks the credential revoked and ends every session that was opened with it, so the collector must authenticate with another credential. Revoking a credential that is already revoked succeeds. Returns 204 with no body; an unknown collector or credential answers 404.",
        "operationId": "revokeCollectorCredential",
        "parameters": [
          {
            "description": "Identifier of the collector that owns the credential (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the credential to revoke (starts with `crd_`).",
            "in": "path",
            "name": "credential_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a credential and its sessions",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:collectors:manage"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/health": {
      "get": {
        "description": "Counts the collector's instances as online (heartbeat within the last 90 seconds), degraded (within 5 minutes) or offline, and reports the collector as operational at the best level any instance reaches. The response also lists the instances, the number of active sessions and active meter assignments, and when the collector was last seen. Requires the `platform:collectors:read` permission.",
        "operationId": "getCollectorHealth",
        "parameters": [
          {
            "description": "Identifier of the collector (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Collector operational health derived from heartbeats",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/instances": {
      "get": {
        "description": "Returns the running copies of the collector that have registered, each with a status worked out from its last heartbeat: `online` within 90 seconds, `degraded` within 5 minutes, otherwise `offline` (retired instances keep `retired`). Requires the `platform:collectors:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listCollectorInstances",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Identifier of the collector whose instances are listed (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List collector instances",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/instances/{instance_id}": {
      "get": {
        "description": "Returns one registered instance with its status worked out from the last heartbeat (`online` within 90 seconds, `degraded` within 5 minutes, otherwise `offline`). Requires the `platform:collectors:read` permission; an instance that does not belong to the collector answers 404.",
        "operationId": "getCollectorInstance",
        "parameters": [
          {
            "description": "Identifier of the collector the instance belongs to (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the collector instance.",
            "in": "path",
            "name": "instance_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get a collector instance",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/sessions": {
      "get": {
        "description": "Returns the sessions the collector's instances opened, including expired and revoked ones, with the credential used and their expiry; session tokens last one hour. Requires the `platform:collectors:read` permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listCollectorSessions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Identifier of the collector whose sessions are listed (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List collector sessions",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      }
    },
    "$PLATFORM_API/collectors/{id}/statistics": {
      "get": {
        "description": "Returns counts of meter observations the collector submitted (accepted, flagged and rejected) and of meter commands sent through it (queued, leased, succeeded and failed). All counters are zero when statistics are not available on the installation. Requires the `platform:collectors:read` permission.",
        "operationId": "getCollectorStatistics",
        "parameters": [
          {
            "description": "Identifier of the collector (starts with `clc_`).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Observation and command counters",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:collectors:read"
        ]
      }
    },
    "$PLATFORM_API/communications/connectors": {
      "get": {
        "description": "Returns the enrolled connectors that deliver email, text message and other messages, with their channels, the utilities they serve, their last heartbeat, and their successful and failed deliveries over the last 24 hours. Requires the platform communications read permission. Results are cursor-paginated with `limit` (default 20, at most 100) and `after`.",
        "operationId": "listCommunicationConnectors",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "A page of connectors"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List communication connectors",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:communications:read"
        ]
      }
    },
    "$PLATFORM_API/communications/connectors/{id}": {
      "delete": {
        "description": "Deletes the connector record, so its token stops working and no further messages are routed to it. Returns 204 with no body; an unknown connector answers 404. Requires the platform communications manage permission.",
        "operationId": "deleteCommunicationConnector",
        "parameters": [
          {
            "description": "Identifier of the communication connector to remove.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Connector removed"
          },
          "404": {
            "description": "RFC 7807 problem when the connector does not exist"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a connector and invalidate its token",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:communications:manage"
        ]
      }
    },
    "$PLATFORM_API/communications/connectors/{id}/test": {
      "post": {
        "description": "Queues a test message on `channel` (`email` or the channel's code) through this connector to the calling operator's own verified email address or phone number, written in the operator's locale. The connector must support that channel and have sent a heartbeat in the last two minutes, and the operator must have a verified contact for the channel; otherwise the call answers 400. Returns 202 with the job `id` and status `pending`; poll the test result operation with that id.",
        "operationId": "sendCommunicationConnectorTest",
        "parameters": [
          {
            "description": "Identifier of the connector the test message is sent through.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "channel": {
                    "enum": [
                      "email"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "channel"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "id": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "pending"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Test delivery queued for the named connector"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProblemDetails"
                    },
                    {
                      "properties": {
                        "code": {
                          "enum": [
                            "OPERATOR_CONTACT_UNVERIFIED"
                          ],
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "The connector is offline, the channel is unsupported, or the operator has no verified contact on the channel. The last case carries the stable problem code OPERATOR_CONTACT_UNVERIFIED (the detail text is not stable); the others carry no specific code."
          },
          "403": {
            "description": "Missing platform:communications:manage scope"
          },
          "404": {
            "description": "Connector not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Queue a test message to the operator's verified email or phone through one connector",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:communications:manage"
        ]
      }
    },
    "$PLATFORM_API/communications/enrollment-tokens": {
      "post": {
        "description": "Optional body field tenant_ids is the exact grant: the connector then only leases jobs for those tenants, never tenantless identity messages. Without it the connector serves every tenant.",
        "operationId": "createCommunicationEnrollmentToken",
        "responses": {
          "201": {
            "description": "Token issued"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a connector enrollment token, returned once",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:communications:manage"
        ]
      }
    },
    "$PLATFORM_API/communications/tests/{id}": {
      "get": {
        "description": "Returns the state of a queued test message: its channel, delivery status (`pending`, `leased`, `sent`, `delivered`, `failed` or `expired`), the delivery service's reference, any failure reason, the next retry time and when it completed. Only jobs created by the connector test operation are found; any other id answers 404.",
        "operationId": "getCommunicationConnectorTest",
        "parameters": [
          {
            "description": "Job identifier returned by the connector test operation.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "channel": {
                      "enum": [
                        "email"
                      ],
                      "type": "string"
                    },
                    "completed_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "created_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "failure_reason": {
                      "type": "string"
                    },
                    "id": {
                      "type": "string"
                    },
                    "next_attempt_at": {
                      "format": "date-time",
                      "type": "string"
                    },
                    "provider_receipt_reference": {
                      "type": "string"
                    },
                    "status": {
                      "enum": [
                        "pending",
                        "leased",
                        "sent",
                        "delivered",
                        "failed",
                        "expired"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "id",
                    "channel",
                    "status",
                    "created_at"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Current or completed test delivery outcome"
          },
          "403": {
            "description": "Missing platform:communications:manage scope"
          },
          "404": {
            "description": "Test delivery not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a test delivery receipt or provider failure",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:communications:manage"
        ]
      }
    },
    "$PLATFORM_API/contact-requests": {
      "get": {
        "description": "Returns contact requests submitted through the public contact form, newest first, with optional status and topic filters. Results are paged with limit (default 50, at most 100; other values fall back to 50) and cursor: pass the previous page's next_cursor to continue. An unknown status or topic returns 400. Requires a platform principal with the platform:onboarding:read scope; any other caller gets 403.",
        "operationId": "getPlatformContactRequests",
        "parameters": [
          {
            "description": "Only return requests in this follow-up status.",
            "in": "query",
            "name": "status",
            "required": false,
            "schema": {
              "enum": [
                "new",
                "contacted",
                "closed"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only return requests about this topic.",
            "in": "query",
            "name": "topic",
            "required": false,
            "schema": {
              "enum": [
                "sales",
                "support",
                "partnership",
                "press",
                "security"
              ],
              "type": "string"
            }
          },
          {
            "description": "Page size, 1 to 100. Missing, zero or larger values return 50 items.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The next_cursor of the previous page; omit for the first page. An unknown cursor is ignored and the first page is returned.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformContactRequestPage"
                }
              }
            },
            "description": "One page of contact requests"
          },
          "400": {
            "description": "Unknown status or topic (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a platform principal, the scope is missing, or the platform access policy refused the request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Contact requests sent from the public site",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:read"
        ]
      }
    },
    "$PLATFORM_API/contact-requests/{id}": {
      "patch": {
        "description": "Moves a contact request to new, contacted or closed (case-insensitive) and returns the updated request with a fresh updated_at. Any status can follow any other. A missing or unknown status returns 400 and an unknown identifier returns 404. Requires a platform principal with the platform:onboarding:review scope; any other caller gets 403. Each change is written to the audit trail as intake.contact_request.status_changed.",
        "operationId": "updatePlatformContactRequest",
        "parameters": [
          {
            "description": "Identifier of the contact request (prefix crq_).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePlatformContactRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformContactRequest"
                }
              }
            },
            "description": "Updated contact request"
          },
          "400": {
            "description": "Invalid JSON body, or missing or unknown status (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a platform principal, the scope is missing, or the platform access policy refused the request"
          },
          "404": {
            "description": "No contact request with this identifier"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Set the follow-up status of a contact request",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/definitions": {
      "get": {
        "description": "Returns report definitions in the platform scope, not utility-level ones, optionally narrowed by `category`. Requires the `reports:read` platform permission. Results are cursor-paginated with `limit` and `after`; a malformed cursor answers 400.",
        "operationId": "listPlatformReportDefinitions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Report definitions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform report definitions",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:read"
        ]
      },
      "post": {
        "description": "Creates a report definition in the platform scope that runs against the dataset named by `dataset_key`; `key`, `name` and `dataset_key` are required, while `description` and `category` are optional. Requires the `reports:write` platform permission and returns 201 with the new definition.",
        "operationId": "createPlatformReportDefinition",
        "responses": {
          "201": {
            "description": "Definition created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create platform report definition",
        "x-roles": [
          "admin",
          "analyst",
          "finance",
          "owner"
        ],
        "x-scopes": [
          "reports:write"
        ]
      }
    },
    "$PLATFORM_API/developer/api-keys": {
      "get": {
        "description": "Returns the API keys issued in the platform context, newest first, one cursor page at a time. Platform keys are shared by the platform team: every platform principal with platform:developer:read sees all of them, whoever created them. Keys are identified by prefix and last four characters; the secret is never returned again. Each key reports its computed status (active, expired or revoked). A caller that is not a platform principal, or lacks the scope, gets 403.",
        "operationId": "listPlatformDeveloperApiKeys",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKeyPage"
                }
              }
            },
            "description": "Platform API keys"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a platform principal, or platform:developer:read not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform API keys by prefix and last four",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:developer:read"
        ]
      },
      "post": {
        "description": "Issues an API key in the platform context and returns its full secret only in this response. A secret key (no scopes given) receives every platform scope the caller holds; a restricted key needs at least one scope, and every scope must be in the platform catalog and held by the caller. Platform keys are live keys only: mode test returns 400. The request must come from a person signed in as a platform principal, not from an API key (403 api_key_not_allowed), and needs platform:developer:write. A missing or over-long name (128 characters), an unknown scope, a past expires_at, a malformed allowed_ips entry or scopes on a secret key return 400; a scope the caller does not hold returns 403. The creation is written to the audit trail.",
        "operationId": "createPlatformDeveloperApiKey",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateDeveloperApiKey"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKey"
                }
              }
            },
            "description": "Key created; the secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Request made with an API key, not a platform principal, scope missing, or a requested scope not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a platform API key; the full key appears once in the response",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:developer:write"
        ]
      }
    },
    "$PLATFORM_API/developer/api-keys/{id}": {
      "delete": {
        "description": "Ends the platform key at once, so requests made with it fail from now on, and writes an audit record. The request must come from a person signed in as a platform principal, not from an API key, and needs platform:developer:write; the caller does not need to hold the key's scopes. An unknown key returns 404.",
        "operationId": "revokePlatformDeveloperApiKey",
        "parameters": [
          {
            "description": "Identifier of the platform API key to revoke.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Revoked"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Request made with an API key, not a platform principal, or platform:developer:write not held"
          },
          "404": {
            "description": "No platform API key with this identifier"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a platform key immediately",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:developer:write"
        ]
      }
    },
    "$PLATFORM_API/developer/api-keys/{id}/roll": {
      "post": {
        "description": "Issues a replacement platform key with the same name, kind, mode, scopes, allowed IPs and expiry, returns its secret once, and keeps the old key valid for overlap_seconds (default 24 hours, maximum 7 days, never past the old key's own expiry). The body is optional. Only an active key that has not already been rolled can be rolled; otherwise the response is 409. The request must come from a person signed in as a platform principal, not from an API key, needs platform:developer:write, and the caller must hold every scope the key carries, or the response is 403. An unknown key returns 404. The roll is written to the audit trail.",
        "operationId": "rollPlatformDeveloperApiKey",
        "parameters": [
          {
            "description": "Identifier of the active platform API key to replace.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/DeveloperRoll"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperApiKey"
                }
              }
            },
            "description": "Replacement key; the secret is shown only here"
          },
          "400": {
            "description": "Invalid JSON body or overlap_seconds out of range (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Request made with an API key, not a platform principal, scope missing, or a key scope not held"
          },
          "404": {
            "description": "No platform API key with this identifier"
          },
          "409": {
            "description": "The key is not active or has already been rolled"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace a platform key, keeping the old one valid for the overlap",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:developer:write"
        ]
      }
    },
    "$PLATFORM_API/developer/scopes": {
      "get": {
        "description": "Returns the scopes the caller can put on a restricted platform API key: the platform scope catalog (every scope of every platform role) narrowed to the scopes the caller holds. A secret platform key created now would carry this same list. The caller must be a platform principal holding platform:developer:read (the owner and admin platform roles have it); anyone else gets 403.",
        "operationId": "getPlatformDeveloperScopes",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeveloperScopes"
                }
              }
            },
            "description": "Grantable platform scopes"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a platform principal, or platform:developer:read not held"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Scopes a platform API key can carry",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:developer:read"
        ]
      }
    },
    "$PLATFORM_API/docs-feedback": {
      "get": {
        "description": "Returns documentation feedback, newest first, optionally for one page path and only helpful or unhelpful votes, with a per-path summary of helpful and unhelpful counts. The summary covers every vote (or every vote on the filtered path) regardless of the helpful filter and of paging. Results are paged with limit (default 50, at most 100) and cursor. A helpful value that is not a boolean returns 400. Requires a platform principal with the platform:metrics:read scope; any other caller gets 403.",
        "operationId": "getPlatformDocsFeedback",
        "parameters": [
          {
            "description": "Only return feedback for this documentation page path (exact match, for example /docs/api/authentication).",
            "in": "query",
            "name": "path",
            "required": false,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "true for helpful votes only, false for unhelpful votes only; omit for both.",
            "in": "query",
            "name": "helpful",
            "required": false,
            "schema": {
              "type": "boolean"
            }
          },
          {
            "description": "Page size, 1 to 100. Missing, zero or larger values return 50 items.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 50,
              "maximum": 100,
              "minimum": 1,
              "type": "integer"
            }
          },
          {
            "description": "The next_cursor of the previous page; omit for the first page. An unknown cursor is ignored and the first page is returned.",
            "in": "query",
            "name": "cursor",
            "required": false,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformDocsFeedbackPage"
                }
              }
            },
            "description": "One page of feedback with per-path totals"
          },
          "400": {
            "description": "helpful is not a boolean (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not a platform principal, the scope is missing, or the platform access policy refused the request"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Helpfulness votes left on documentation pages",
        "x-roles": [
          "admin",
          "analyst",
          "owner"
        ],
        "x-scopes": [
          "platform:metrics:read"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/scim/tokens": {
      "get": {
        "description": "Lets a platform operator see the SCIM directory tokens of the tenant in the path, newest first, as a plain array (not paged). Token secrets are never included. Requires a platform principal with platform:team:manage.",
        "operationId": "getPlatformTenantScimTokens",
        "parameters": [
          {
            "description": "Identifier of the tenant whose tokens are listed.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "items": {
                    "$ref": "#/components/schemas/EnterpriseScimToken"
                  },
                  "type": "array"
                }
              }
            },
            "description": "SCIM tokens"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No tenant has this ID, or the item does not exist"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Show a tenant's SCIM directory tokens",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      },
      "post": {
        "description": "Lets a platform operator issue a SCIM bearer token for the tenant in the path, for example while onboarding its identity provider. The secret is returned only in this response and only its SHA-256 digest is stored. name defaults to \"Default SCIM Directory Sync\"; expires_in_days 0 or omitted means it never expires. Requires a platform principal with platform:team:manage. The issue is recorded in the tenant's audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "createPlatformTenantScimToken",
        "parameters": [
          {
            "description": "Identifier of the tenant the token will provision.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseScimTokenCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseScimTokenCreated"
                }
              }
            },
            "description": "Token issued; the secret is shown only here"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No tenant has this ID, or the item does not exist"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Issue a SCIM directory token for a tenant; the secret appears once",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/scim/tokens/{id}": {
      "delete": {
        "description": "Lets a platform operator revoke a SCIM token of the tenant in the path. Idempotent: an unknown id returns 204. Requires a platform principal with platform:team:manage. The revocation is recorded in the tenant's audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "deletePlatformTenantScimToken",
        "parameters": [
          {
            "description": "Identifier of the tenant that owns the token.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the SCIM token to revoke (sct_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Token revoked"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No tenant has this ID, or the item does not exist"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a tenant's SCIM directory token",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/sso": {
      "get": {
        "description": "Lets a platform operator read the single sign-on connection of the tenant in the path, or a JSON null body with 200 when it has none. Secrets are never returned. Requires a platform principal with platform:team:manage (platform owner and admin roles), even for this read.",
        "operationId": "getPlatformTenantSsoConnection",
        "parameters": [
          {
            "description": "Identifier of the tenant whose connection is read.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/EnterpriseSsoConnection"
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            },
            "description": "The connection, or null when none is configured"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No tenant has this ID, or the item does not exist"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read a tenant's single sign-on connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      },
      "put": {
        "description": "Lets a platform operator save the single sign-on connection of the tenant in the path, with the same rules as the tenant's own save: saml or oidc, a valid domain, the protocol's required fields, public https URLs, tenant roles other than owner, and a write-only client_secret that is kept when omitted. Requires a platform principal with platform:team:manage. An unknown tenant returns 404, invalid input 400, and a domain claimed by another connection 409. The change is recorded in the tenant's audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "savePlatformTenantSsoConnection",
        "parameters": [
          {
            "description": "Identifier of the tenant whose connection is saved.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseSsoConnectionInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSsoConnection"
                }
              }
            },
            "description": "The saved connection, without secrets"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Tenant not found"
          },
          "409": {
            "description": "The domain is already claimed by another connection"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create or replace a tenant's single sign-on connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/sso/saml/metadata": {
      "post": {
        "description": "Lets a platform operator parse a SAML identity provider metadata document while configuring the tenant in the path. Returns the entity ID, single sign-on URL, optional single logout URL and signing certificate; nothing is stored. A document that is empty, larger than 1 MiB, not well-formed or without an IDPSSODescriptor returns 400. Requires a platform principal with platform:team:manage; an unknown tenant returns 404. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "parsePlatformTenantSamlMetadata",
        "parameters": [
          {
            "description": "Identifier of the tenant being configured.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/EnterpriseSamlMetadataRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSamlIdpSettings"
                }
              }
            },
            "description": "Settings found in the metadata"
          },
          "400": {
            "description": "Invalid input (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Tenant not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Extract SAML settings from metadata for a tenant",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/sso/test": {
      "post": {
        "description": "Lets a platform operator run the live identity provider checks for the tenant in the path and see each result; valid is true only when all pass. Takes no request body. Requires a platform principal with platform:team:manage. An unknown tenant, or a tenant without a connection, returns 404. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "testPlatformTenantSsoConnection",
        "parameters": [
          {
            "description": "Identifier of the tenant whose connection is tested.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSsoTestResult"
                }
              }
            },
            "description": "Check results"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Tenant not found, or no single sign-on connection is configured"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Probe a tenant's identity provider",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/sso/verify-domain": {
      "post": {
        "description": "Lets a platform operator check the DNS TXT record for the domain of the tenant in the path and, when it holds the connection's domain_verification_token, mark the domain verified for that tenant. A missing or wrong record returns 400 naming the record to publish; a domain verified by another tenant returns 409; an unknown tenant or missing connection returns 404. Takes no request body. Requires a platform principal with platform:team:manage. The verification is recorded in the tenant's audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "verifyPlatformTenantSsoDomain",
        "parameters": [
          {
            "description": "Identifier of the tenant whose domain is verified.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/EnterpriseSsoConnection"
                }
              }
            },
            "description": "The connection with domain_verified_at set"
          },
          "400": {
            "description": "The DNS record was not found or does not match (RFC 7807)"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "Tenant not found, or no single sign-on connection is configured"
          },
          "409": {
            "description": "The domain is already claimed by another connection"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Verify a tenant's single sign-on domain",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/enterprise/{tenantID}/sso/{id}": {
      "delete": {
        "description": "Lets a platform operator delete the single sign-on connection with this id from the tenant in the path. Idempotent: an id that does not match returns 204. Requires a platform principal with platform:team:manage. The deletion is recorded in the tenant's audit log. Needs a person's session: API keys are refused with 403 and code api_key_not_allowed, whatever scopes they hold.",
        "operationId": "deletePlatformTenantSsoConnection",
        "parameters": [
          {
            "description": "Identifier of the tenant that owns the connection.",
            "in": "path",
            "name": "tenantID",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Identifier of the tenant's single sign-on connection (sso_...).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Connection removed"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "403": {
            "description": "Not authorized, or scope not held"
          },
          "404": {
            "description": "No tenant has this ID, or the item does not exist"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a tenant's single sign-on connection",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/first-run/abandon": {
      "post": {
        "description": "Records that the user explicitly exited or cancelled the journey at the given step. It is sent only after an explicit exit; closing a tab, losing the network or inactivity are never recorded. The body carries only the opaque run token and the stable step ID: no reason text or identity. Repeats are idempotent. Requires the platform:onboarding:write scope and a run token issued for the platform setup journey.",
        "operationId": "abandonPlatformFirstRun",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunAbandonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Exit recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid or expired run token, or unknown step"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the token was issued to someone else"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The step is already done"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an explicit exit from a first-use journey"
      }
    },
    "$PLATFORM_API/first-run/funnel": {
      "get": {
        "description": "For every journey, the number of distinct runs that started, completed, skipped or explicitly exited each step in the interval, and the median seconds from the journey's start to its moment of value with the number of runs in that median (null and 0 when none). Exits are counted only when the user explicitly left; silence is never an exit. Aggregates are platform-wide with no tenant, user, role or locale segmentation and no small-group suppression; no event rows or run IDs are returned. from and to are RFC3339, from before to, at most 366 days apart. Requires platform:onboarding:read.",
        "operationId": "getPlatformFunnel",
        "parameters": [
          {
            "description": "Start of the interval (inclusive, RFC3339)",
            "in": "query",
            "name": "from",
            "required": true,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          },
          {
            "description": "End of the interval (exclusive, RFC3339)",
            "in": "query",
            "name": "to",
            "required": true,
            "schema": {
              "format": "date-time",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformFunnel"
                }
              }
            },
            "description": "Funnel per journey"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid bounds"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Platform-wide first-use funnel"
      }
    },
    "$PLATFORM_API/first-run/health": {
      "get": {
        "description": "Returns connector online state, recent message delivery outcome, the last payment test outcome, error rate and backups. Each item has state (healthy, degraded, down, unknown), checked_at, a reason code and a safe in-app fix route, and a measured value with its interval only when the server measured one. Missing telemetry is unknown, never healthy; no backup or error-rate value is invented. Requires platform:onboarding:read.",
        "operationId": "getPlatformHealth",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformHealth"
                }
              }
            },
            "description": "Health items"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Platform health at a glance"
      }
    },
    "$PLATFORM_API/first-run/progress": {
      "get": {
        "description": "Returns the durable progress of the signed-in platform operator for one journey (platform_setup): every step by stable ID in server order, its state (todo, done, skipped or blocked with a reason), whether and why it can be skipped, who changed it and when, and the qualifying action that completed it. A journey with no record returns its steps as todo. The response also carries an opaque run token the client sends back in the X-First-Run-Token header so funnel events join without storing who ran them. Requires the platform:onboarding:read scope.",
        "operationId": "getPlatformFirstRunProgress",
        "parameters": [
          {
            "description": "Journey ID",
            "in": "query",
            "name": "journey",
            "required": true,
            "schema": {
              "enum": [
                "platform_setup"
              ],
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirstRunProgress"
                }
              }
            },
            "description": "Journey progress"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or entitlement"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Journey not available to this audience"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read first-use progress for one journey"
      }
    },
    "$PLATFORM_API/first-run/progress/{journey}/{step}": {
      "patch": {
        "description": "Records an explicit skip (state skipped with a reason_code from the step's allowed_skip_reasons) or resumes a skipped step (state todo). A client can never write done or blocked: domain actions complete steps and prerequisites block them. A done step cannot be reopened (409). Security, identity and legal steps and the moment-of-value steps have no skip reasons. Requires the platform:onboarding:write scope.",
        "operationId": "updatePlatformFirstRunStep",
        "parameters": [
          {
            "description": "Journey ID",
            "in": "path",
            "name": "journey",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Step ID",
            "in": "path",
            "name": "step",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunStepUpdate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/FirstRunProgress"
                }
              }
            },
            "description": "Updated journey progress"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not skippable, unknown reason or a state the client cannot write"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unknown journey or step"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The step is done"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Skip or resume one first-use step"
      }
    },
    "$PLATFORM_API/first-run/setup": {
      "get": {
        "description": "Returns the six setup items in fixed order (brand, domains, messaging_connector, payment_connector, plans, first_utility) with localized title and line, state (todo, done, skipped, blocked) and reason, the last check time, the in-app action and the settings that belong to each item, plus the whole settings catalogue. States derive from configuration, recorded check results, published plans, invitation and handover state, and the caller's first-run progress (skips). first_utility is done only when an invited or platform-set-up owner has signed in after any required handover; a skip never completes it. Settings say whether they change at run time (with their in-app route) or only in the configuration file (with the key, the current non-secret value and how to change it); connector tokens show only whether one is configured. Requires platform:onboarding:read.",
        "operationId": "getPlatformSetup",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformSetup"
                }
              }
            },
            "description": "Checklist"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The platform setup checklist and day-one settings"
      }
    },
    "$PLATFORM_API/first-run/setup/domains/check": {
      "post": {
        "description": "Fetches the configured site, dashboard and API origins and returns each origin's result with the time and a reason code when it fails. Unset optional origins are reported as not_configured; the API origin is required. It changes no DNS, certificate, setting or listen address. A pass completes the domains item. Safe to retry. Requires platform:onboarding:write.",
        "operationId": "checkPlatformDomains",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformDomainCheck"
                }
              }
            },
            "description": "Per-origin results"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check that the configured addresses answer"
      }
    },
    "$PLATFORM_API/first-run/setup/payment-test": {
      "post": {
        "description": "Runs the payment check through the named (or first) payment connection registered under connectors.payments[], for its test account, and returns a non-secret outcome, a reason code when it fails, whether to retry and the next in-app action. It never charges a resident or utility account. With no registered connection the outcome is failed with code no_payment_connector. A success completes the payment_connector item. Safe to retry. Requires platform:onboarding:write.",
        "operationId": "testPlatformPayment",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PlatformPaymentTestRequest"
              }
            }
          },
          "required": false
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformPaymentTest"
                }
              }
            },
            "description": "Outcome"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Malformed body"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Run the payment test through the registered payment connection"
      }
    },
    "$PLATFORM_API/jobs": {
      "get": {
        "description": "Returns background jobs from every tenant, newest first, with cursor pagination (limit defaults to 20, max 100; pass next_cursor as after). Payloads are never included; each job shows its kind, status, attempt counts, last error and timestamps. Jobs that exhausted their attempts have moved to the dead-letter list and do not appear here. When the installation runs without the job queue the list is empty. Requires the platform:jobs:read scope.",
        "operationId": "listPlatformJobs",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only return jobs in this state: queued, running or succeeded; omit for all states.",
            "in": "query",
            "name": "status",
            "schema": {
              "enum": [
                "queued",
                "running",
                "succeeded"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only return jobs of this exact job kind (case-sensitive match on the kind name).",
            "in": "query",
            "name": "kind",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only return jobs that belong to this tenant ID; omit to list jobs across all tenants.",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobPage"
                }
              }
            },
            "description": "Jobs"
          },
          "403": {
            "description": "Missing platform:jobs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List durable background jobs",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:jobs:read"
        ]
      }
    },
    "$PLATFORM_API/jobs/dead-letters": {
      "get": {
        "description": "Returns dead letters from every tenant, most recently failed first, with cursor pagination (limit defaults to 20, max 100). Each entry carries the attempt count, last error and, once it has been retried, retried_at and the ID of the new job. Add retried=false to hide entries that were already retried. Requires the platform:jobs:read scope; the list is empty when the job queue is disabled.",
        "operationId": "listPlatformJobDeadLetters",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only return dead letters of this exact job kind.",
            "in": "query",
            "name": "kind",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Only return dead letters that belong to this tenant ID; omit to list across all tenants.",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/DeadJobPage"
                }
              }
            },
            "description": "Dead letters"
          },
          "403": {
            "description": "Missing platform:jobs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List jobs that exhausted their attempts",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:jobs:read"
        ]
      }
    },
    "$PLATFORM_API/jobs/dead-letters/{id}/retry": {
      "post": {
        "description": "Puts a copy of the dead job back on the queue. The new job keeps the original tenant, kind and payload and starts again with fresh attempts. The dead letter is marked as retried in the same transaction, and workers are woken at once. Returns 202 with the new job. A dead letter can be retried only once: a second retry returns 409, and 409 is also returned when the installation runs without the job queue. Requires the platform:jobs:retry scope.",
        "operationId": "retryPlatformJobDeadLetter",
        "parameters": [
          {
            "description": "ID of the dead letter to retry, as returned by the dead-letter list, from any tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            },
            "description": "The new queued job"
          },
          "403": {
            "description": "Missing platform:jobs:retry scope"
          },
          "404": {
            "description": "Dead letter not found"
          },
          "409": {
            "description": "The dead letter was already retried, or the job queue is not enabled on this installation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Requeue a dead letter as a new job; a dead letter can be retried once",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:jobs:retry"
        ]
      }
    },
    "$PLATFORM_API/jobs/summary": {
      "get": {
        "description": "Counts jobs across all tenants, grouped by status. The counts include dead letters, so operators can watch the queue backlog and failures in one call. When the installation runs without the job queue, enabled is false and counts is empty. Requires the platform:jobs:read scope.",
        "operationId": "getPlatformJobSummary",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobSummary"
                }
              }
            },
            "description": "Status counts. enabled is false, with empty counts, when this installation runs without the job queue."
          },
          "403": {
            "description": "Missing platform:jobs:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Counts of jobs by status, including dead letters",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:jobs:read"
        ]
      }
    },
    "$PLATFORM_API/jobs/{id}": {
      "get": {
        "description": "Returns one background job from any tenant, with its status, attempts, lock owner, last error, request ID and lifecycle timestamps. The payload is not returned. Returns 404 when no job has this ID, including when the job has moved to the dead-letter list or the job queue is disabled. Requires the platform:jobs:read scope.",
        "operationId": "getPlatformJob",
        "parameters": [
          {
            "description": "ID of the job to read, from any tenant.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JobView"
                }
              }
            },
            "description": "The job"
          },
          "403": {
            "description": "Missing platform:jobs:read scope"
          },
          "404": {
            "description": "Job not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one job",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:jobs:read"
        ]
      }
    },
    "$PLATFORM_API/ledger/accounts": {
      "get": {
        "description": "Lists the chart of accounts of the platform's own books. These books are separate from every tenant's ledger and hold subscription invoices and payments from utilities. Results are cursor-paginated and can be narrowed with q (a text search) and active=true or active=false. This endpoint is read-only and requires the platform ledger read permission.",
        "operationId": "listPlatformLedgerAccounts",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerAccountPage"
                }
              }
            },
            "description": "Accounts"
          },
          "403": {
            "description": "Missing platform:billing:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the platform's own chart of accounts",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/ledger/entries": {
      "get": {
        "description": "Lists journal entries in the platform's own books, which record subscription invoices issued to utilities and the payments they make. You can filter by account_id, party_id, source_module, source_reference_id and a from/to window; from and to must be RFC 3339 timestamps, otherwise the call returns 400. Results are cursor-paginated. Requires the platform ledger read permission.",
        "operationId": "listPlatformLedgerEntries",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerEntryPage"
                }
              }
            },
            "description": "Journal entries"
          },
          "400": {
            "description": "Invalid date filter"
          },
          "403": {
            "description": "Missing platform:billing:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the platform's journal entries",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/ledger/entries/{id}": {
      "get": {
        "description": "Returns one journal entry of the platform's own books with all of its debit and credit lines. Returns 404 when the entry does not exist in the platform ledger. Tenant ledger entries cannot be read through this endpoint.",
        "operationId": "getPlatformLedgerEntry",
        "parameters": [
          {
            "description": "ID of the journal entry in the platform ledger.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerEntry"
                }
              }
            },
            "description": "Journal entry"
          },
          "403": {
            "description": "Missing platform:billing:read scope"
          },
          "404": {
            "description": "Entry not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one platform journal entry",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/ledger/trial-balance": {
      "get": {
        "description": "Totals debits and credits for each account in the platform's own books. Each line shows the account's balance, signed in its normal direction. The response also gives the overall debit and credit totals and a balanced flag. Pass as_of as an RFC 3339 timestamp to compute the balance at that moment; an invalid value returns 400.",
        "operationId": "getPlatformLedgerTrialBalance",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/LedgerTrialBalance"
                }
              }
            },
            "description": "Trial balance"
          },
          "400": {
            "description": "Invalid as_of timestamp"
          },
          "403": {
            "description": "Missing platform:billing:read scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Platform trial balance of SaaS receivables and revenue",
        "x-roles": [
          "admin",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:billing:read"
        ]
      }
    },
    "$PLATFORM_API/metadata": {
      "get": {
        "description": "Searches the metadata that platform operators have attached to organizations and subscriptions. You must give key, value or both, otherwise the call returns 400. resource_type, when given, must be organization or subscription. Results are cursor-paginated and each entry names the resource and its full metadata map. Requires the platform:metadata:read scope.",
        "operationId": "listPlatformMetadataResources",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Metadata key",
            "in": "query",
            "name": "key",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Exact metadata value",
            "in": "query",
            "name": "value",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Restrict to one resource type",
            "in": "query",
            "name": "resource_type",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntryPage"
                }
              }
            },
            "description": "Resources with metadata"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List resources by metadata; key or value is required",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:metadata:read"
        ]
      }
    },
    "$PLATFORM_API/metrics": {
      "get": {
        "description": "Returns the governed platform metrics, computed at request time: monthly recurring revenue (mrr_cents) and the number of active utility tenants. Each metric has a key, name, unit, value and timestamp, and the list is wrapped in data. Requires the platform:metrics:read scope.",
        "operationId": "listPlatformMetrics",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Metrics catalog"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform governed metrics catalog",
        "x-roles": [
          "admin",
          "analyst",
          "owner"
        ],
        "x-scopes": [
          "platform:metrics:read"
        ]
      }
    },
    "$PLATFORM_API/next-steps": {
      "get": {
        "description": "Returns the next one to three actionable steps for the signed-in platform operator, chosen and ordered by the server from progress, review state, capabilities, counts and connectors; an empty list when nothing is waiting. Each step has a stable ID, localized title and line (saved language, then Accept-Language, then the platform default), the role that acts, a portable action ID the client maps to its own screen, and a help article ID from the shared help registry. Clients keep no step list or order of their own. GET is safe to retry and completes nothing. Requires the platform:onboarding:read scope.",
        "operationId": "getPlatformNextSteps",
        "parameters": [
          {
            "$ref": "#/components/parameters/FirstRunToken"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NextSteps"
                }
              }
            },
            "description": "Next steps"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope or entitlement"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "The next one to three first-use steps"
      }
    },
    "$PLATFORM_API/onboarding": {
      "get": {
        "description": "Lists the onboarding applications submitted by utility tenants, for platform review. You can filter by status (not_started, in_progress, submitted, under_review, action_required, approved or rejected; any other value returns 400) and search with q. Results are cursor-paginated. Settlement account details are masked. Test accounts (sandbox tenants) are never listed. Each application carries applicant_name, the utility's name as given at sign-up or invitation, and submitted_at once submitted. Requires the platform:onboarding:read scope.",
        "operationId": "listPlatformOnboarding",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Filter by status",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search legal name, trading name or tenant",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplicationPage"
                }
              }
            },
            "description": "Application page"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List onboarding applications",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:read"
        ]
      }
    },
    "$PLATFORM_API/onboarding/capability-policy": {
      "get": {
        "description": "Returns the global onboarding policy. The response holds the stored requirement templates (by country, account type and plan), the resolved capability_requirements map that says which requirements enable each capability, and the verification_catalog of requirement definitions. Requires the platform:onboarding:read scope.",
        "operationId": "getOnboardingCapabilityPolicy",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "capability_requirements": {
                      "additionalProperties": {
                        "items": {
                          "type": "string"
                        },
                        "type": "array"
                      },
                      "type": "object"
                    },
                    "templates": {
                      "items": {
                        "$ref": "#/components/schemas/CapabilityRequirementTemplate"
                      },
                      "type": "array"
                    },
                    "verification_catalog": {
                      "items": {
                        "$ref": "#/components/schemas/VerificationRequirementDefinition"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "templates",
                    "capability_requirements",
                    "verification_catalog"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Capability requirement policy"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read persisted country, organization type, and plan capability templates",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:read"
        ]
      },
      "put": {
        "description": "Replaces the global onboarding policy in one atomic save. Send templates, or only capability_requirements to build the default template from that map. You can also send verification_catalog to replace the catalog in the same save. Every template must be valid and may reference only requirements in the catalog, otherwise the call returns 400. The response has the same shape as the read. Requires the platform:metadata:write scope.",
        "operationId": "updateOnboardingCapabilityPolicy",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "oneOf": [
                  {
                    "properties": {
                      "templates": {
                        "items": {
                          "$ref": "#/components/schemas/CapabilityRequirementTemplate"
                        },
                        "type": "array"
                      },
                      "verification_catalog": {
                        "items": {
                          "$ref": "#/components/schemas/VerificationRequirementDefinition"
                        },
                        "type": "array"
                      }
                    },
                    "required": [
                      "templates"
                    ],
                    "type": "object"
                  },
                  {
                    "properties": {
                      "capability_requirements": {
                        "additionalProperties": {
                          "items": {
                            "type": "string"
                          },
                          "type": "array"
                        },
                        "type": "object"
                      }
                    },
                    "required": [
                      "capability_requirements"
                    ],
                    "type": "object"
                  }
                ]
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Updated capability requirement policy"
          },
          "400": {
            "description": "Invalid capability",
            "or requirement key": null,
            "selector": null
          },
          "403": {
            "description": "Requires platform:metadata:write"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace persisted country, organization type, and plan capability templates",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:metadata:write"
        ]
      }
    },
    "$PLATFORM_API/onboarding/queue-summary": {
      "get": {
        "description": "Counts of applications per status, how many wait on the platform's review (submitted or under_review) and since when the oldest of those has waited (its submitted_at), for a waiting badge in the navigation. Test accounts are never counted. Requires the platform:onboarding:read scope.",
        "operationId": "getPlatformOnboardingQueueSummary",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "counts": {
                    "in_progress": 5,
                    "submitted": 2
                  },
                  "oldest_waiting_since": "2026-11-20T09:30:00Z",
                  "waiting": 2
                },
                "schema": {
                  "properties": {
                    "counts": {
                      "additionalProperties": {
                        "format": "int64",
                        "type": "integer"
                      },
                      "description": "Applications per status",
                      "type": "object"
                    },
                    "oldest_waiting_since": {
                      "description": "submitted_at of the oldest waiting application; absent when none waits",
                      "format": "date-time",
                      "type": "string"
                    },
                    "waiting": {
                      "description": "Applications submitted or under review",
                      "format": "int64",
                      "type": "integer"
                    }
                  },
                  "required": [
                    "counts",
                    "waiting"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Queue summary"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing platform:onboarding:read"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Applications queue at a glance"
      }
    },
    "$PLATFORM_API/onboarding/{id}": {
      "get": {
        "description": "Returns the reviewer view of one onboarding application. It includes the application fields (settlement account masked), the computed requirements (currently due, pending verification and errors), uploaded documents and the review history. Returns 404 when the application does not exist. Requires the platform:onboarding:read scope.",
        "operationId": "getPlatformOnboarding",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get an application with requirements, documents and review history",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:read"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/approve": {
      "post": {
        "description": "Approves a submitted or under-review application and activates the utility's tenant. If any requirement is still currently due or pending verification, the call returns 409 and lists the outstanding requirements. Any other status also returns 409. Approval clears an earlier rejection reason, records the reviewer and a review event, and returns the updated reviewer view. Requires the platform:onboarding:review scope.",
        "operationId": "approveOnboarding",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          },
          "409": {
            "description": "Not allowed in the current state or requirements outstanding"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Approve an application, activating capabilities and the tenant",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/documents/{document_id}/accept": {
      "post": {
        "description": "Marks a document of the application as accepted and records you as its reviewer and the review time. The application's status does not change. A review event is added, and the updated reviewer view is returned. Returns 409 when the application is already approved or rejected, and 404 when the document does not belong to the application's tenant. Requires the platform:onboarding:review scope.",
        "operationId": "acceptOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "document_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Accept a document",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/documents/{document_id}/expire": {
      "post": {
        "description": "Marks a document as expired, with a required reason that the utility sees in the requirement errors. If the application was submitted or under review, it moves to action_required so the utility can upload a replacement. Returns 400 without a reason, and 409 when the application is already approved or rejected. Requires the platform:onboarding:review scope.",
        "operationId": "expireOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "document_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReasonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Mark a document expired with a reason",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/documents/{document_id}/file": {
      "get": {
        "description": "Streams the stored file of an onboarding document as an attachment. The response uses the document's original content type and file name, with nosniff set. Returns 404 when the application or the document does not exist. Requires the platform:onboarding:read scope.",
        "operationId": "downloadPlatformOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "document_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "File bytes"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download an application document",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:read"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/documents/{document_id}/reject": {
      "post": {
        "description": "Marks a document as rejected, with a required reason that is reported to the utility through the requirement errors. If the application was submitted or under review, it moves to action_required. Returns 400 without a reason, and 409 when the application is already approved or rejected. Requires the platform:onboarding:review scope.",
        "operationId": "rejectOnboardingDocument",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "document_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReasonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject a document with a reason",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/reject": {
      "post": {
        "description": "Rejects the application with a required reason, which is stored on the application and recorded in its review history. Only applications that are submitted, under_review or action_required can be rejected; any other status returns 409. A missing or blank reason returns 400. Requires the platform:onboarding:review scope.",
        "operationId": "rejectOnboarding",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ReasonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Reject an application with a reason",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/request-information": {
      "post": {
        "description": "Sends the utility one message per requirement and moves the application to action_required. Each entry in requests needs a known requirement (a built-in one or a custom manual-review requirement from the catalog) and a non-blank message; otherwise the call returns 400. A new message for the same requirement replaces the earlier one. Allowed only from submitted, under_review or action_required (otherwise 409). Requires the platform:onboarding:review scope.",
        "operationId": "requestOnboardingInformation",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RequestInformation"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Request information per requirement; surfaces as errors and action_required",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/requirements/{key}/review": {
      "post": {
        "description": "Records your decision on the evidence the utility submitted for a custom manual-review requirement. decision is verified, rejected or expired; rejected and expired need a reason of up to 4000 characters and move the application to action_required. The evidence must be awaiting review, otherwise the call returns 409. Unknown requirements, or requirements this application does not need, return 400. Requires the platform:onboarding:review scope.",
        "operationId": "reviewCustomOnboardingRequirement",
        "parameters": [
          {
            "description": "ID of the onboarding application under review.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Key of a custom requirement in the verification catalog that is checked by manual review and applies to this application; built-in requirement keys are refused.",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "pattern": "^custom\\.[a-z0-9][a-z0-9._-]*$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "decision": {
                    "enum": [
                      "verified",
                      "rejected",
                      "expired"
                    ],
                    "type": "string"
                  },
                  "reason": {
                    "description": "Required when decision is rejected or expired",
                    "maxLength": 4000,
                    "type": "string"
                  }
                },
                "required": [
                  "decision"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application with reviewed evidence state"
          },
          "400": {
            "description": "Invalid decision or rejection/expiry without a reason"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "404": {
            "description": "Application not found"
          },
          "409": {
            "description": "Evidence is not awaiting review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Verify, reject or expire submitted evidence for a configured manual requirement",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/onboarding/{id}/start-review": {
      "post": {
        "description": "Moves a submitted application to under_review, so the utility can see that a reviewer is working on it. It also records the reviewer, the review time and a review event. Only submitted applications can be moved; any other status returns 409. Requires the platform:onboarding:review scope.",
        "operationId": "startOnboardingReview",
        "parameters": [
          {
            "description": "Resource identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application"
          },
          "409": {
            "description": "Not allowed in the current state or requirements outstanding"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Move a submitted application to under_review",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:onboarding:review"
        ]
      }
    },
    "$PLATFORM_API/organizations": {
      "get": {
        "description": "Lists organizations registered on the platform, newest first, with cursor pagination (limit defaults to 20, max 100). q matches part of the name, ignoring case. A non-integer limit returns 400. Requires the platform:organizations:read scope.",
        "operationId": "listUtilityOrganizations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/Search"
          },
          {
            "$ref": "#/components/parameters/OrganizationStatus"
          },
          {
            "$ref": "#/components/parameters/UtilityKind"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OrganizationPage"
                }
              }
            },
            "description": "Utilities visible to the platform principal"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List provisioned utility organizations",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:organizations:read"
        ]
      },
      "post": {
        "description": "Creates a utility organization from a name and a utility_kind. The organization starts active, with account-level billing. Registering it does not create a tenant: provision one with POST $PLATFORM_API/tenants. A blank name returns 400, and so does a missing or unknown utility_kind. Requires the platform:organizations:create scope.",
        "operationId": "registerUtilityOrganization",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateOrganization"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            },
            "description": "Utility organization registered"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Register a utility on the platform",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:organizations:create"
        ]
      }
    },
    "$PLATFORM_API/organizations/{id}": {
      "get": {
        "description": "Requires platform:organizations:read.",
        "operationId": "getPlatformOrganization",
        "parameters": [
          {
            "description": "Organization identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Organization"
                }
              }
            },
            "description": "Organization"
          },
          "404": {
            "description": "Unknown organization"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one utility organization",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:organizations:read"
        ]
      }
    },
    "$PLATFORM_API/organizations/{id}/metadata": {
      "get": {
        "description": "Returns the platform-scoped metadata map of an organization. These keys are visible only to platform operators and are separate from any metadata the utility keeps. Returns 404 when the organization does not exist. Requires the platform:metadata:read scope.",
        "operationId": "getPlatformOrganizationMetadata",
        "parameters": [
          {
            "description": "ID of the organization (at most 120 characters) whose metadata to read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a organization",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the given keys into the organization's platform metadata. Keys you leave out are kept, and a key sent with an empty string is deleted. Keys must be 1 to 40 characters with no square brackets or control characters, values at most 500 characters. A resource can hold at most 50 keys after the merge; any violation returns 400 listing the invalid fields. Returns 404 when the organization does not exist. Requires the platform:metadata:write scope.",
        "operationId": "putPlatformOrganizationMetadata",
        "parameters": [
          {
            "description": "ID of the organization (at most 120 characters) whose metadata to update.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:metadata:write"
        ]
      }
    },
    "$PLATFORM_API/overview": {
      "get": {
        "description": "Returns the platform dashboard figures: MRR and ARR in cents, utilities that are active, trialing or past due, the churn rate, the onboarding pipeline by status, meters and connections under management, and 12-month series for new subscriptions and MRR. Requires the platform:overview:read scope. Returns 404 when the installation has no overview source configured.",
        "operationId": "getPlatformOverview",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PlatformOverview"
                }
              }
            },
            "description": "Overview"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "MRR, ARR, active utilities, churn, trial and onboarding pipeline counts, meters and connections under management",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:overview:read"
        ]
      }
    },
    "$PLATFORM_API/payment-connectors": {
      "get": {
        "description": "Lists the payment connectors registered by all tenants, wrapped in connectors. Each connector shows its supported and operational methods, currency, mode (pull or push), status and last heartbeat. Token hashes are never returned. The list is empty when no connector is registered. The service checks the platform:communications:read permission for this read.",
        "operationId": "getPlatformPaymentConnectors",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "connectors": {
                      "items": {
                        "additionalProperties": true,
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Payment connectors across utilities"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Every utility's payment connectors, for the platform console",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:communications:read"
        ]
      }
    },
    "$PLATFORM_API/plans": {
      "get": {
        "description": "Requires `subscriptions:read` in a platform context. Each plan's name, tagline and capability labels are in the caller's language (lang, else Accept-Language, else the plan's default text); default_name and default_tagline keep the default text the plan editor saves. capabilities lists every capability with its label, for the editor.",
        "operationId": "listPlatformPlans",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "$ref": "#/components/parameters/PlanLang"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "capabilities": {
                      "description": "Every plan capability, labelled in the caller's language.",
                      "items": {
                        "$ref": "#/components/schemas/CapabilityLabel"
                      },
                      "type": "array"
                    },
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/Plan"
                      },
                      "type": "array"
                    },
                    "offers": {
                      "description": "Offers listed beside the plans; the custom offer (code custom) when a published plan has a connection limit.",
                      "items": {
                        "$ref": "#/components/schemas/PlanOffer"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Platform plans"
          },
          "403": {
            "description": "Missing subscriptions:read scope or non-platform context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List platform SaaS tiers",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "subscriptions:read"
        ]
      },
      "post": {
        "description": "Requires `plans:write` in a platform context.",
        "operationId": "createPlatformPlan",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plan"
                }
              }
            },
            "description": "Platform plan created"
          },
          "400": {
            "description": "Invalid plan request"
          },
          "403": {
            "description": "Missing plans:write scope or non-platform context"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a platform SaaS tier",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "plans:write"
        ]
      }
    },
    "$PLATFORM_API/plans/{id}": {
      "patch": {
        "description": "Changes the fields sent and leaves the others. name_i18n and tagline_i18n replace the translations when sent; an empty object clears them. Requires `plans:write` in a platform context.",
        "operationId": "updatePlatformPlan",
        "parameters": [
          {
            "description": "Plan ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdatePlanRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Plan"
                }
              }
            },
            "description": "Platform plan updated"
          },
          "400": {
            "description": "Invalid plan request"
          },
          "403": {
            "description": "Missing plans:write scope or non-platform context"
          },
          "404": {
            "description": "Plan not found"
          },
          "409": {
            "description": "Another published plan is already highlighted"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update a platform SaaS tier",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "plans:write"
        ]
      }
    },
    "$PLATFORM_API/search": {
      "get": {
        "description": "Searches utility organizations and platform subscriptions. Lookups run concurrently with a per-request timeout. Sources the caller's scopes exclude are omitted; a source that fails for any other reason is omitted and `partial` becomes true.",
        "operationId": "searchPlatform",
        "parameters": [
          {
            "$ref": "#/components/parameters/SearchQuery"
          },
          {
            "description": "Comma-separated subset of [organization, subscription]. Defaults to all of them; an unknown type is rejected.",
            "in": "query",
            "name": "types",
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/SearchLimit"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SearchResponse"
                }
              }
            },
            "description": "Matching resources, grouped by type in a stable order"
          },
          "400": {
            "description": "Invalid q, types or limit"
          },
          "401": {
            "description": "Authentication required"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Search platform organizations and subscriptions",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:metadata:read",
          "platform:organizations:read",
          "subscriptions:read"
        ]
      }
    },
    "$PLATFORM_API/subscriptions": {
      "get": {
        "description": "Lists tenant subscriptions across the platform with cursor pagination. You can filter by plan_id and by status (scheduled, trialing, active, past_due, suspended or cancelled). Requires the subscriptions:read permission on the platform.",
        "operationId": "listPlatformSubscriptions",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "description": "Subscriptions"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility SaaS subscriptions",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "subscriptions:read"
        ]
      },
      "post": {
        "description": "Subscribes a tenant to a plan. If the plan has trial days, the subscription starts as trialing and its first period ends when the trial ends. Otherwise it starts active with a one-month period from now. tenant_id and plan_id are both required (400 when missing), and an unknown plan returns 404. Requires the platform:subscriptions:create scope.",
        "operationId": "createPlatformSubscription",
        "responses": {
          "201": {
            "description": "Subscription created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Provision a SaaS subscription for a utility",
        "x-roles": [
          "admin",
          "billing",
          "owner"
        ],
        "x-scopes": [
          "platform:subscriptions:create"
        ]
      }
    },
    "$PLATFORM_API/subscriptions/{id}": {
      "get": {
        "description": "Requires subscriptions:read.",
        "operationId": "getPlatformSubscription",
        "parameters": [
          {
            "description": "Subscription identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Subscription"
                }
              }
            },
            "description": "Subscription"
          },
          "404": {
            "description": "Unknown subscription"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get one subscription",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "subscriptions:read"
        ]
      }
    },
    "$PLATFORM_API/subscriptions/{id}/metadata": {
      "get": {
        "description": "Returns the platform-scoped metadata map of a subscription, for operator use only. Returns 404 when the subscription does not exist. Requires the platform:metadata:read scope.",
        "operationId": "getPlatformSubscriptionMetadata",
        "parameters": [
          {
            "description": "ID of the subscription (at most 120 characters) whose metadata to read.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Metadata"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get the metadata of a subscription",
        "x-roles": [
          "admin",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:metadata:read"
        ]
      },
      "put": {
        "description": "Merges the given keys into the subscription's platform metadata. Keys you leave out are kept, and a key sent with an empty string is deleted. Keys must be 1 to 40 characters with no square brackets or control characters, values at most 500 characters, and at most 50 keys may remain after the merge; violations return 400. Returns 404 when the subscription does not exist. Requires the platform:metadata:write scope.",
        "operationId": "putPlatformSubscriptionMetadata",
        "parameters": [
          {
            "description": "ID of the subscription (at most 120 characters) whose metadata to update.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/MetadataPut"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/MetadataEntry"
                }
              }
            },
            "description": "Resulting metadata"
          },
          "400": {
            "description": "invalid_params lists each failing key"
          },
          "404": {
            "description": "Resource not found"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Merge metadata; an empty value deletes the key",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:metadata:write"
        ]
      }
    },
    "$PLATFORM_API/system/info": {
      "get": {
        "description": "Returns installation details that clients can read before signing in. It includes the configured product name, version, build date and commit, and the default currency, locale, timezone and country. It also lists the supported country codes, sorted, and the account types offered. No authentication is required.",
        "operationId": "getPlatformSystemInfo",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SystemInfo"
                }
              }
            },
            "description": "Product and localization defaults"
          }
        },
        "security": [],
        "summary": "Get public installation information"
      }
    },
    "$PLATFORM_API/system/storage-settings": {
      "get": {
        "description": "Returns the effective runtime storage limits and download policy. Requires platform:team:manage.",
        "operationId": "getPlatformStorageSettings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Runtime storage policy"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Get effective file storage policies"
      },
      "put": {
        "description": "Applies limits, allowed upload types, download policy and presigned link settings to subsequent requests without restarting. Requires platform:team:manage.",
        "operationId": "updatePlatformStorageSettings",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "type": "object"
                }
              }
            },
            "description": "Updated runtime storage policy"
          },
          "400": {
            "description": "Invalid policy values"
          },
          "403": {
            "description": "Missing platform scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Update runtime file storage policies"
      }
    },
    "$PLATFORM_API/team/invitations": {
      "get": {
        "description": "Lists invitations to the platform operator team with cursor pagination. Without a status filter, only pending invitations are returned. A pending invitation past its expiry is reported as expired. Requires the platform team read permission.",
        "operationId": "listPlatformTeamInvitations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamInvitationPage"
                }
              }
            },
            "description": "List invitations of the platform team"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List invitations of the platform team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:read"
        ]
      },
      "post": {
        "description": "Invites a person to the platform operator team by e-mail or phone, with the given platform roles. The invitation token is sent by e-mail, or by text message when only a phone is given. It expires after 7 days, and it replaces any pending invitation for the same recipient. Returns 400 without an e-mail or phone or with an unknown role, 403 when a non-owner grants the owner role, and 409 when the person is already a member. Returns 503 when the message cannot be delivered; the invitation is then revoked.",
        "operationId": "createPlatformTeamInvitation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTeamInvitation"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamInvitation"
                }
              }
            },
            "description": "Invite a member to the platform team"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          },
          "503": {
            "description": "The invitation could not be sent: no provider for the target, the public web URL is not configured, or the provider failed."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Invite a member to the platform team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/team/invitations/{id}": {
      "delete": {
        "description": "Cancels a pending invitation to the platform team so its token can no longer be accepted, and records an audit event. Returns 404 when the invitation does not belong to the platform team, and 409 when it is no longer pending. Requires the platform team manage permission.",
        "operationId": "revokePlatformTeamInvitation",
        "responses": {
          "204": {
            "description": "Revoke a pending invitation of the platform team"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a pending invitation of the platform team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/team/members": {
      "get": {
        "description": "Lists the active members of the platform operator team, with their user details, roles, status and join date, using cursor pagination. Requires the platform team read permission.",
        "operationId": "listPlatformTeamMembers",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamMemberPage"
                }
              }
            },
            "description": "List members of the platform team"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List members of the platform team",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:read"
        ]
      }
    },
    "$PLATFORM_API/team/members/{id}": {
      "delete": {
        "description": "Removes a member from the platform team. The member's sessions are ended, including sessions in contexts inherited through this membership, and an audit event is recorded. Only an owner can remove another owner (403 otherwise), and the last owner cannot be removed (409). Returns 404 when the member is not active in the platform team.",
        "operationId": "removePlatformTeamMember",
        "responses": {
          "204": {
            "description": "Remove a member from the platform team (the last owner cannot be removed)"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a member from the platform team (the last owner cannot be removed)",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/team/members/{id}/roles": {
      "patch": {
        "description": "Replaces all of a member's platform roles with the given list. The member's existing sessions are ended so the new permissions apply at the next sign-in. Unknown roles return 400. Only an owner can grant the owner role or demote another owner (403), and the last owner cannot be demoted (409). Returns the updated member.",
        "operationId": "updatePlatformTeamMemberRoles",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateTeamMemberRoles"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TeamMember"
                }
              }
            },
            "description": "Replace a member's roles (the last owner cannot be demoted)"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Replace a member's roles (the last owner cannot be demoted)",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      }
    },
    "$PLATFORM_API/team/members/{id}/sessions": {
      "delete": {
        "description": "Ends every device session the member has in the platform context and returns the count as revoked. The member must sign in again. An audit event is recorded. Only an owner can end an owner's sessions (403 otherwise). Requires the platform team manage permission.",
        "operationId": "revokePlatformMemberSessions",
        "parameters": [
          {
            "description": "Membership ID of the platform team member whose sessions to end.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RevokedCount"
                }
              }
            },
            "description": "End every session of a team member"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "End every session of a team member",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:manage"
        ]
      },
      "get": {
        "description": "Lists the live sessions that a platform team member has in the platform context, wrapped in data. The caller's own current session is flagged. Returns 404 when the member is not active in the platform team. Requires the platform team read permission.",
        "operationId": "getPlatformMemberSessions",
        "parameters": [
          {
            "description": "Membership ID of the platform team member, as returned by the team member list.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/SessionList"
                }
              }
            },
            "description": "List a team member sessions"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List a team member sessions",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:read"
        ]
      }
    },
    "$PLATFORM_API/team/roles": {
      "get": {
        "description": "Lists the roles that can be assigned in the platform operator team, with their definitions, wrapped in data. Use these role keys when inviting members or changing their roles. Requires the platform team read permission.",
        "operationId": "getPlatformTeamRoles",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/RoleCatalog"
                }
              }
            },
            "description": "List the built-in roles of the platform context"
          },
          "400": {
            "description": "Validation failure"
          },
          "401": {
            "description": "Missing or invalid credentials"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the built-in roles of the platform context",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:team:read"
        ]
      }
    },
    "$PLATFORM_API/tenants": {
      "get": {
        "description": "Requires platform:organizations:read.",
        "operationId": "listPlatformTenants",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Restrict to one organization",
            "in": "query",
            "name": "owner_organization_id",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Search tenant name or slug",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Filter by tenant status",
            "in": "query",
            "name": "status",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/Tenant"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Tenants"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility tenants",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:organizations:read"
        ]
      },
      "post": {
        "description": "Creates a live tenant (utility workspace) owned by an active organization. The slug may contain only lowercase letters, digits and hyphens, and must not start or end with a hyphen. Country, locale, currency and timezone default from the installation's country settings when omitted. The new tenant starts active, in the unverified workspace state, and must still complete onboarding. Returns 400 for invalid input or an inactive owner, 404 for an unknown organization, 409 for a duplicate, and 429 when the owner's account limit or plan limit is reached.",
        "operationId": "provisionUtilityTenant",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreateTenant"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Tenant"
                }
              }
            },
            "description": "Utility tenant provisioned"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Provision a tenant for a utility",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:tenants:create"
        ]
      }
    },
    "$PLATFORM_API/tenants/{id}/usage": {
      "get": {
        "description": "Requires platform:overview:read. Connections counts active and suspended connections. A limit of 0 means the plan sets none.",
        "operationId": "getPlatformTenantUsage",
        "parameters": [
          {
            "description": "Tenant identifier",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantUsage"
                }
              }
            },
            "description": "Usage"
          },
          "404": {
            "description": "Unknown tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Connection, meter, customer and user counts for a tenant against plan limits",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:overview:read"
        ]
      }
    },
    "$PLATFORM_API/tenants/{tenant_id}/branding": {
      "get": {
        "description": "Requires platform:branding:write.",
        "operationId": "getPlatformTenantBranding",
        "parameters": [
          {
            "description": "ID of the tenant (utility workspace) whose branding to read.",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Utility brand with sources"
          },
          "403": {
            "description": "Missing platform:branding:write"
          },
          "404": {
            "description": "Unknown utility"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "A utility's brand, for the platform owner",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:write"
        ]
      },
      "patch": {
        "description": "Requires platform:branding:write. Audited in the utility's log as branding.updated with by=platform.",
        "operationId": "updatePlatformTenantBranding",
        "parameters": [
          {
            "description": "ID of the tenant (utility workspace) whose branding to change; the body must be a JSON object of at most 64 KB.",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TenantBrandingPatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Updated utility brand"
          },
          "400": {
            "description": "A value is invalid"
          },
          "403": {
            "description": "Missing platform:branding:write"
          },
          "404": {
            "description": "Unknown utility"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Correct a utility's brand",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:write"
        ]
      }
    },
    "$PLATFORM_API/tenants/{tenant_id}/branding/assets/{kind}": {
      "delete": {
        "description": "Requires platform:branding:write. Audited in the utility's log as branding.asset_removed with by=platform.",
        "operationId": "deletePlatformTenantBrandingAsset",
        "parameters": [
          {
            "description": "ID of the tenant (utility workspace) whose brand file to remove.",
            "in": "path",
            "name": "tenant_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Brand file to remove: logo, logo_dark or icon; any other value returns 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TenantBrandingAdmin"
                }
              }
            },
            "description": "Updated utility brand"
          },
          "403": {
            "description": "Missing platform:branding:write"
          },
          "404": {
            "description": "Unknown utility"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove a utility's uploaded brand file, such as an abusive logo",
        "x-roles": [
          "admin",
          "owner"
        ],
        "x-scopes": [
          "platform:branding:write"
        ]
      }
    },
    "$PLATFORM_API/utilities": {
      "get": {
        "description": "Requires platform:overview:read. Paged rather than part of /overview because each row reads several modules.",
        "operationId": "listPlatformUtilities",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Search tenant name or slug",
            "in": "query",
            "name": "q",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Restrict to one organization",
            "in": "query",
            "name": "owner_organization_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/UtilityRow"
                      },
                      "type": "array"
                    },
                    "has_more": {
                      "type": "boolean"
                    },
                    "next_cursor": {
                      "type": "string"
                    }
                  },
                  "type": "object"
                }
              }
            },
            "description": "Utility rows"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Per-utility rows with organization, plan, subscription, onboarding and usage against limits",
        "x-roles": [
          "admin",
          "analyst",
          "billing",
          "owner",
          "support"
        ],
        "x-scopes": [
          "platform:overview:read"
        ]
      }
    },
    "$PLATFORM_API/utility-invitations": {
      "get": {
        "description": "Lists invitations newest first with state (sent, opened, accepted, expired, revoked), expiry, utility, masked owner contact, setup_mode and handover.state. Filter by state and tenant_id. Requires the platform:onboarding:read scope.",
        "operationId": "listUtilityInvitations",
        "parameters": [
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          },
          {
            "description": "Only invitations in this state",
            "in": "query",
            "name": "state",
            "schema": {
              "enum": [
                "sent",
                "opened",
                "accepted",
                "expired",
                "revoked"
              ],
              "type": "string"
            }
          },
          {
            "description": "Only invitations for this utility",
            "in": "query",
            "name": "tenant_id",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitationList"
                }
              }
            },
            "description": "Invitations"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List utility invitations with their state"
      },
      "post": {
        "description": "Creates one invitation and sends the one-time link through the configured delivery connectors. The fields are the utility name, country and one owner e-mail or phone, with an optional server plan, allowed offer and personal note. With setup_mode platform_managed the server first registers the utility in the set-up-by-the-platform state; the owner gets access only after accepting the invitation and then the handover. The response never contains the token. Requires the platform:onboarding:write scope; the platform principal acts on an explicit utility target and never signs in as or impersonates the owner.",
        "operationId": "createUtilityInvitation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UtilityInvitationCreate"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitation"
                }
              }
            },
            "description": "Invitation created and sent"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid field, unknown plan or offer, or a pending invitation for this contact"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Invite a utility owner, or start setting a utility up on its behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/bulk": {
      "post": {
        "description": "Confirms a dry run with an idempotency key: valid rows are revalidated, created and sent; invalid and duplicate rows are not. Repeating the same key returns the same result without sending again; another key on a confirmed dry run, or a dry run older than a day, returns 409. Each row reports created or errors and the invitation ID, never a token. Requires the platform:onboarding:write scope; the platform principal acts on an explicit utility target and never signs in as or impersonates the owner.",
        "operationId": "confirmUtilityInvitations",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UtilityInvitationConfirmRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitationBulkResult"
                }
              }
            },
            "description": "Per-row result"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing idempotency key"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No such dry run"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Already confirmed with another key, or stale"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send the valid rows of a dry run"
      }
    },
    "$PLATFORM_API/utility-invitations/bulk/dry-run": {
      "post": {
        "description": "Validates CSV text with the header utility_name,country_code,owner_contact (plan_id optional) and returns a dry_run_id with every row's number, normalized utility data, masked contact and all its errors. Nothing is created or sent. Requires the platform:onboarding:write scope; the platform principal acts on an explicit utility target and never signs in as or impersonates the owner.",
        "operationId": "dryRunUtilityInvitations",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UtilityInvitationDryRunRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitationBulkResult"
                }
              }
            },
            "description": "Dry-run result"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The CSV cannot be read"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Check a CSV of invitations without sending anything"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}": {
      "get": {
        "description": "Returns the invitation with the full owner contact, delivery history (time, channel, outcome; never the link), setup_mode, handover state and the checklist steps the platform completed. Requires the platform:onboarding:read scope.",
        "operationId": "getUtilityInvitation",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitation"
                }
              }
            },
            "description": "Invitation"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No such invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read one utility invitation"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/resend": {
      "post": {
        "description": "Invalidates the previous token, sends a new one-time link, resets the expiry from now and keeps the delivery history. Accepted and revoked invitations return 409. Requires the platform:onboarding:write scope; the platform principal acts on an explicit utility target and never signs in as or impersonates the owner.",
        "operationId": "resendUtilityInvitation",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitation"
                }
              }
            },
            "description": "Invitation"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No such invitation"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Accepted or revoked"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Send a new link and invalidate the old one"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/revoke": {
      "post": {
        "description": "Revokes a sent or opened invitation and invalidates its token. Other states return 409. An on-behalf invitation keeps its last handover state. Requires the platform:onboarding:write scope; the platform principal acts on an explicit utility target and never signs in as or impersonates the owner.",
        "operationId": "revokeUtilityInvitation",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitation"
                }
              }
            },
            "description": "Invitation"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No such invitation"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not pending"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revoke a pending invitation"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/customers/import": {
      "post": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). Requires platform:onboarding:read for the template and platform:onboarding:write otherwise. Creates each valid row of the dry run through the customer service, once per idempotency key (body idempotency_key or the Idempotency-Key header): the same key returns the first answer and creates nothing more; another key returns 409. A dry run with no valid rows returns 400; a stale one (over 24 hours) returns 409. A confirm that creates at least one customer completes the utility_real customer_import step.",
        "operationId": "confirmOnBehalfCustomerImport",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerImportConfirmRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerImportResult"
                }
              }
            },
            "description": "The confirmation, with the created customer per row"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing key, or no valid rows"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Dry run not found for this utility"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Already confirmed with another key, or stale"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Confirm a customer import dry run"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/customers/import/dry-run": {
      "post": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). Requires platform:onboarding:read for the template and platform:onboarding:write otherwise. Parses and validates the CSV (at most 2000 rows and 2 MiB) and returns every row with its normalized data and errors by field; rows that repeat a phone or e-mail of an earlier row are errors. Nothing is written except the dry run itself, which can be confirmed for 24 hours.",
        "operationId": "dryRunOnBehalfCustomerImport",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CustomerImportDryRunRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/CustomerImportResult"
                }
              }
            },
            "description": "The dry run"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unreadable CSV, unknown column, no rows or too many rows"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Validate a customer CSV without writing anything"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/customers/import/template": {
      "get": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). Requires platform:onboarding:read for the template and platform:onboarding:write otherwise. The CSV header the import reads: display_name (required), customer_type (individual or business, default individual), category (residential, commercial, industrial, institutional or government, default residential), phone, email, tax_number.",
        "operationId": "getOnBehalfCustomerImportTemplate",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "text/csv": {
                "schema": {
                  "type": "string"
                }
              }
            },
            "description": "The CSV template"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Download the customer import CSV template"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/onboarding": {
      "get": {
        "description": "The platform operator acts on the utility the platform is setting up, by explicit invitation target, with a temporary onboarding capability that exists only for these requests and ends when the owner accepts the handover (403 afterwards). Every successful change appends a tenant audit event with the operator's ID, a display-name snapshot, the action, target and changed field names (never values, documents or secrets). The request and response are those of the utility's own route of the same path. Requires platform:onboarding:read.",
        "operationId": "getOnBehalfOnboarding",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "The application, with requirements.currently_due, verification_requirements, verification_catalog and current_terms_version (the value to send back in terms.version)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation, or not a setup action"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Read the managed utility's onboarding application"
      },
      "patch": {
        "description": "The platform operator acts on the utility the platform is setting up, by explicit invitation target, with a temporary onboarding capability that exists only for these requests and ends when the owner accepts the handover (403 afterwards). Every successful change appends a tenant audit event with the operator's ID, a display-name snapshot, the action, target and changed field names (never values, documents or secrets). The request and response are those of the utility's own route of the same path. Requires platform:onboarding:write.",
        "operationId": "updateOnBehalfOnboarding",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UpdateOnboarding"
              }
            }
          },
          "description": "Same body and validation as PATCH $BUSINESS_API/onboarding. Every field the submit requires is settable here: business_profile (legal_name, trading_name, nuit, registration_number, address, licence_reference, phone, support_contact), representative (name, role, id_document_number, date_of_birth YYYY-MM-DD, contact e-mail or phone) and terms {accepted: true, version: current_terms_version}; optional collection_channels and settlement_account. A nil field is left unchanged, an empty string clears it; invalid values answer 400 with invalid_params per field.",
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "The application, with requirements.currently_due, verification_requirements, verification_catalog and current_terms_version (the value to send back in terms.version)"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid field values (invalid_params per field), or the application is not editable"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation, or not a setup action"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Fill company details on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/onboarding/documents": {
      "get": {
        "description": "Runs the utility's own route of the same path (GET $BUSINESS_API/onboarding/documents) for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). File contents are not included. Requires platform:onboarding:read.",
        "operationId": "listOnBehalfOnboardingDocuments",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingDocumentList"
                }
              }
            },
            "description": "Documents"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the managed utility's onboarding documents"
      },
      "post": {
        "description": "Runs the utility's own upload route (a multipart form with type and file; PDF, JPEG or PNG up to 10 MiB) for the utility the platform is setting up, as the operator. A success appends a tenant audit event with the operator's ID, name snapshot and the changed field name document (never the contents). Access ends when the owner accepts the handover (403 afterwards). Requires platform:onboarding:write.",
        "operationId": "uploadOnBehalfOnboardingDocument",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "multipart/form-data": {
              "schema": {
                "$ref": "#/components/schemas/OnboardingDocumentUpload"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingDocument"
                }
              }
            },
            "description": "Stored document"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unknown type or missing file"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Upload an onboarding document on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/onboarding/documents/{documentID}": {
      "delete": {
        "description": "Runs the utility's own route (DELETE $BUSINESS_API/onboarding/documents/{id}) for the utility the platform is setting up, as the operator, so a wrong upload can be replaced. A success appends a tenant audit event with the operator's ID and name snapshot. Access ends when the owner accepts the handover (403 afterwards). Requires platform:onboarding:write.",
        "operationId": "deleteOnBehalfOnboardingDocument",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Document ID",
            "in": "path",
            "name": "documentID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "Removed"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation, or no such document"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The application is submitted or under review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Remove an onboarding document on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/onboarding/requirements/{key}": {
      "post": {
        "description": "Runs the utility's own route (POST $BUSINESS_API/onboarding/requirements/{key}) for the utility the platform is setting up, as the operator, so configured manual requirements (verification_catalog entries with checked_by manual_review) can be completed before submit. A success appends a tenant audit event with the operator's ID, name snapshot and the changed field name value. Access ends when the owner accepts the handover (403 afterwards). Requires platform:onboarding:write.",
        "operationId": "submitOnBehalfCustomOnboardingRequirement",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Key of a manual-review requirement from the verification catalog (custom.<name>)",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "pattern": "^custom\\.[a-z0-9][a-z0-9._-]*$",
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "value": {
                    "maxLength": 4000,
                    "minLength": 1,
                    "type": "string"
                  }
                },
                "required": [
                  "value"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "Application with the submitted evidence state"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not a manual requirement, or not required for this utility"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The requirement is already verified, or the application is submitted or under review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit evidence for a configured manual requirement on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/onboarding/submit": {
      "post": {
        "description": "The platform operator acts on the utility the platform is setting up, by explicit invitation target, with a temporary onboarding capability that exists only for these requests and ends when the owner accepts the handover (403 afterwards). Every successful change appends a tenant audit event with the operator's ID, a display-name snapshot, the action, target and changed field names (never values, documents or secrets). The request and response are those of the utility's own route of the same path. Completes company_details and documents for the platform. Requires platform:onboarding:write.",
        "operationId": "submitOnBehalfOnboarding",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/OnboardingApplication"
                }
              }
            },
            "description": "The application, with requirements.currently_due, verification_requirements, verification_catalog and current_terms_version (the value to send back in terms.version)"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation, or not a setup action"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "allOf": [
                    {
                      "$ref": "#/components/schemas/ProblemDetails"
                    },
                    {
                      "properties": {
                        "code": {
                          "enum": [
                            "REQUIREMENTS_OUTSTANDING",
                            "APPLICATION_STATE",
                            "APPLICATION_CHANGED"
                          ],
                          "type": "string"
                        }
                      },
                      "type": "object"
                    }
                  ]
                }
              }
            },
            "description": "Not submittable. The problem's code says why: REQUIREMENTS_OUTSTANDING (invalid_params name every currently_due requirement, each with code outstanding), APPLICATION_STATE (the application's status does not allow a submit, for example it is already submitted or approved) or APPLICATION_CHANGED (it changed concurrently; reload and retry)."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit the documents on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/service-areas": {
      "get": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). A create appends a tenant audit event with the operator's ID, name snapshot and changed field names. Requires platform:onboarding:read.",
        "operationId": "listOnBehalfServiceAreas",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {},
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The utility route's response"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the managed utility's service areas"
      },
      "post": {
        "description": "The platform operator acts on the utility the platform is setting up, by explicit invitation target, with a temporary onboarding capability that exists only for these requests and ends when the owner accepts the handover (403 afterwards). Every successful change appends a tenant audit event with the operator's ID, a display-name snapshot, the action, target and changed field names (never values, documents or secrets). The request and response are those of the utility's own route of the same path. Completes service_areas for the platform. Requires platform:onboarding:write.",
        "operationId": "createOnBehalfServiceArea",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "description": "Same body as the utility route",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {},
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The utility route's response"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation, or not a setup action"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Add a service area on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/tariff-templates": {
      "get": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). The tariffs of the seed dataset for the utility's country, at the dataset's latest prices, as starting points, so a tariff never starts from a blank form and no tariff values live in clients. available is false with reason no_template_for_country or country_unset when there is none. Requires platform:onboarding:read.",
        "operationId": "getOnBehalfTariffTemplates",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/TariffTemplateCatalogue"
                }
              }
            },
            "description": "The templates"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Tariff templates for the utility's country"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/tariff-templates/{templateID}/apply": {
      "post": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). Creates the template's tariff through the billing service, optionally with another code or name and an effective date (default now), and activates it when activate is true. A template applied and activated in the real account completes the utility_real tariffs step. Returns the created tariff. Requires platform:onboarding:write.",
        "operationId": "applyOnBehalfTariffTemplate",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Template ID from the list",
            "in": "path",
            "name": "templateID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/TariffTemplateApply"
              }
            }
          },
          "required": false
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityTariff"
                }
              }
            },
            "description": "The created tariff"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid code, name or tariff"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "No such template for the utility's country, or not an on-behalf invitation"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "A tariff with this code exists, or it cannot be activated now"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a tariff from a template"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/tariffs": {
      "get": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). A create appends a tenant audit event with the operator's ID, name snapshot and changed field names. Requires platform:onboarding:read.",
        "operationId": "listOnBehalfTariffs",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "$ref": "#/components/parameters/PageLimit"
          },
          {
            "$ref": "#/components/parameters/PageAfter"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {},
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The utility route's response"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "List the managed utility's tariffs"
      },
      "post": {
        "description": "Runs the utility's own route of the same path for the utility the platform is setting up, as the operator, by explicit invitation target; access ends when the owner accepts the handover (403 afterwards). A create appends a tenant audit event with the operator's ID, name snapshot and changed field names. Requires platform:onboarding:write.",
        "operationId": "createOnBehalfTariff",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "additionalProperties": true,
                "description": "Same body as the utility route",
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {},
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The utility route's response"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Create a tariff on the utility's behalf"
      }
    },
    "$PLATFORM_API/utility-invitations/{id}/setup/tariffs/{tariffID}/activate": {
      "post": {
        "description": "The platform operator acts on the utility the platform is setting up, by explicit invitation target, with a temporary onboarding capability that exists only for these requests and ends when the owner accepts the handover (403 afterwards). Every successful change appends a tenant audit event with the operator's ID, a display-name snapshot, the action, target and changed field names (never values, documents or secrets). The request and response are those of the utility's own route of the same path. Completes tariffs for the platform. Requires platform:onboarding:write.",
        "operationId": "activateOnBehalfTariff",
        "parameters": [
          {
            "description": "Invitation ID",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Tariff ID",
            "in": "path",
            "name": "tariffID",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {},
                "schema": {
                  "additionalProperties": true,
                  "type": "object"
                }
              }
            },
            "description": "The utility route's response"
          },
          "401": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not signed in"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing scope, or the owner has accepted handover"
          },
          "404": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Not an on-behalf invitation, or not a setup action"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Activate a tariff on the utility's behalf"
      }
    },
    "$PRIVATE_API/collectors/registrations": {
      "post": {
        "description": "Exchanges a single-use enrollment token, sent as the bearer token, for a registered collector instance. The instance is bound to the PEM-encoded Ed25519 or RSA public key in the body. instance_id is required (up to 120 characters), version may be up to 60 characters, and up to 32 protocols may be listed. The token is consumed, and later sessions must be opened by signing with the matching private key. Returns 401 when the token is unknown, used, expired or revoked, or when the collector is suspended or revoked.",
        "operationId": "registerCollector",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "instance_id": {
                    "type": "string"
                  },
                  "name": {
                    "type": "string"
                  },
                  "protocols": {
                    "items": {
                      "type": "string"
                    },
                    "type": "array"
                  },
                  "public_key": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  }
                },
                "required": [
                  "instance_id",
                  "public_key"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Conflict or created"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Bootstrap a collector instance. Authorization: Bearer <enrollment token>."
      }
    },
    "$PRIVATE_API/collectors/sessions": {
      "post": {
        "description": "Opens a runtime session for a registered instance without a bearer token. The caller signs the session challenge for its collector ID, instance ID and timestamp with its registered private key. The timestamp must be RFC 3339 and within five minutes of server time, and the signature must be base64. On success the call returns 201 with a session token that is valid for one hour, plus the heartbeat interval (30 seconds) and the maximum reading batch size (500). The first session activates a newly registered collector. Returns 401 for an unknown instance, a bad signature or a revoked key.",
        "operationId": "openCollectorSession",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "collector_id": {
                    "type": "string"
                  },
                  "instance_id": {
                    "type": "string"
                  },
                  "signature": {
                    "type": "string"
                  },
                  "timestamp": {
                    "format": "date-time",
                    "type": "string"
                  }
                },
                "required": [
                  "collector_id",
                  "instance_id",
                  "timestamp",
                  "signature"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "description": "Conflict or created"
          }
        },
        "security": [],
        "summary": "Open a runtime session with an Ed25519 or RSA signature over collector id, instance id and timestamp"
      }
    },
    "$PRIVATE_API/collectors/sessions/{id}": {
      "delete": {
        "description": "Revokes the caller's runtime session so its token stops working at once. A collector can close only the session it is currently authenticated with; closing any other session returns 403. Returns 204 on success and 404 when the session does not exist.",
        "operationId": "closeCollectorSession",
        "parameters": [
          {
            "description": "ID of the session to close; it must be the session of the bearer token used for this request.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "No content"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Close the calling session"
      }
    },
    "$PRIVATE_API/collectors/{id}/assignments": {
      "get": {
        "description": "Returns the meter assignments of this collector that changed after since_revision, in pages of up to 500. Each assignment has its meter, device, configuration, status and revision. When has_more is true, revision is the last assignment returned: call again with it as since_revision. Otherwise revision is the collector's current assignment revision, which you can store for the next sync. Requires a collector session for this collector.",
        "operationId": "syncCollectorAssignments",
        "parameters": [
          {
            "description": "ID of the collector that owns the session making the call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Return only assignments changed after this revision; a non-negative integer, defaulting to 0 for a full sync (a negative or non-integer value returns 400).",
            "in": "query",
            "name": "since_revision",
            "required": false,
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Revision-based assignment sync"
      }
    },
    "$PRIVATE_API/collectors/{id}/commands/acquire": {
      "post": {
        "description": "Long-polls for queued meter commands and leases them to the calling instance. max_commands defaults to 1 (max 100), and wait_seconds is capped at 8. Only commands for meters still assigned to this collector are granted. Each granted command carries an attempt_id and a lease_token valid for two minutes; renew it while working and send both when completing. Leases are compare-and-swap, so concurrent instances never receive the same command. An empty commands list means nothing was available before the wait ended.",
        "operationId": "acquireMeterCommands",
        "parameters": [
          {
            "description": "ID of the collector that owns the session making the call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "instance_id": {
                    "type": "string"
                  },
                  "max_commands": {
                    "type": "integer"
                  },
                  "wait_seconds": {
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Long-poll for commands; each is leased to the calling instance"
      }
    },
    "$PRIVATE_API/collectors/{id}/commands/{command_id}/complete": {
      "post": {
        "description": "Closes a leased attempt with status succeeded, failed or deferred (deferred re-queues the command for one minute later). result may be up to 8 KB of JSON. A succeeded completion of a read command can include a reading. The reading and the completion are then committed in one transaction, and a rejected reading turns the command into failed. Returns 409 when the lease is stale, expired or superseded.",
        "operationId": "completeMeterCommand",
        "parameters": [
          {
            "description": "ID of the collector that holds the lease.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the leased command to complete, as returned by acquire.",
            "in": "path",
            "name": "command_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "attempt_id": {
                    "type": "string"
                  },
                  "lease_token": {
                    "type": "string"
                  },
                  "reading": {
                    "type": "object"
                  },
                  "reason": {
                    "type": "string"
                  },
                  "result": {
                    "type": "object"
                  },
                  "status": {
                    "enum": [
                      "succeeded",
                      "failed",
                      "deferred"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "attempt_id",
                  "lease_token",
                  "status"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Complete an attempt, atomically with an embedded reading; a stale token answers 409"
      }
    },
    "$PRIVATE_API/collectors/{id}/commands/{command_id}/renew": {
      "post": {
        "description": "Extends a live command lease by extend_seconds from now, capped at 10 minutes, and returns the new lease_expires_at. attempt_id, lease_token and a positive extend_seconds are required (400 otherwise). Returns 409 when the attempt is expired, superseded or does not match the lease token.",
        "operationId": "renewMeterCommandLease",
        "parameters": [
          {
            "description": "ID of the collector that holds the lease.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "ID of the leased command whose lease to extend.",
            "in": "path",
            "name": "command_id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "attempt_id": {
                    "type": "string"
                  },
                  "extend_seconds": {
                    "type": "integer"
                  },
                  "lease_token": {
                    "type": "string"
                  }
                },
                "required": [
                  "attempt_id",
                  "lease_token",
                  "extend_seconds"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Extend a live lease; a stale token answers 409"
      }
    },
    "$PRIVATE_API/collectors/{id}/events": {
      "post": {
        "description": "Records a batch of 1 to 500 device alarms or diagnostic events for meters assigned to this collector. Each event needs an id (up to 120 characters), a type (up to 64 characters, stored lowercase) and an RFC 3339 recorded_at no more than five minutes in the future; severity defaults to medium. Events of the same type on the same meter update one alarm instead of adding new ones. Invalid entries are listed under rejected with a reason. If every entry is for an unassigned meter, the call returns 403.",
        "operationId": "ingestCollectorEvents",
        "parameters": [
          {
            "description": "ID of the collector that owns the session making the call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "events": {
                    "items": {
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "events"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Ingest device alarms into meter_alarms"
      }
    },
    "$PRIVATE_API/collectors/{id}/heartbeat": {
      "post": {
        "description": "Reports that the session's instance is alive and updates the last-seen time of the instance, session and collector, plus the instance version when you send one. The body is optional. instance_id, if sent, must match the session (400 otherwise). The response gives the collector's status, its current assignment revision and the server time. When the assignment revision changes, sync assignments.",
        "operationId": "collectorHeartbeat",
        "parameters": [
          {
            "description": "ID of the collector that owns the session making the call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "instance_id": {
                    "type": "string"
                  },
                  "version": {
                    "type": "string"
                  }
                },
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Report a running instance and receive the assignment revision"
      }
    },
    "$PRIVATE_API/collectors/{id}/readings": {
      "post": {
        "description": "Each observation is checked for assignment and validity, then submitted as a meter reading, and the response sorts every entry into accepted, rejected or duplicates. The batch holds 1 to 500 readings. Readings needing review are accepted with a flagged status, and invalid ones are rejected with a reason. Observation IDs make the call idempotent, and any Idempotency-Key header is echoed back.",
        "operationId": "ingestCollectorReadings",
        "parameters": [
          {
            "description": "ID of the collector that owns the session making the call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "readings": {
                    "items": {
                      "properties": {
                        "id": {
                          "type": "string"
                        },
                        "meter_id": {
                          "type": "string"
                        },
                        "recorded_at": {
                          "format": "date-time",
                          "type": "string"
                        },
                        "unit": {
                          "enum": [
                            "m3",
                            "liters",
                            "gal"
                          ],
                          "type": "string"
                        },
                        "value": {
                          "description": "decimal string",
                          "type": "string"
                        }
                      },
                      "required": [
                        "id",
                        "meter_id",
                        "value",
                        "unit",
                        "recorded_at"
                      ],
                      "type": "object"
                    },
                    "type": "array"
                  }
                },
                "required": [
                  "readings"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "OK"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Ingest a batch of observations. Readings are decimal strings. A replay of an observation id returns it under duplicates with its existing reading id. Answers 403 when every entry is for an unassigned meter."
      }
    },
    "$PRIVATE_API/integrations/{id}/health": {
      "post": {
        "description": "Lets an integration connector report the health of an integration in its own tenant. The health value is unknown, healthy, degraded or unavailable, and the report time is stored with it. The integration must be active and the caller must hold the private:integrations:health permission for it, otherwise the call returns 403. Returns 204 on success, 400 for an unknown health value, and 404 when the integration does not exist.",
        "operationId": "recordIntegrationHealth",
        "parameters": [
          {
            "description": "ID of the integration in the caller's tenant whose health is being reported.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "health": {
                    "enum": [
                      "unknown",
                      "healthy",
                      "degraded",
                      "unavailable"
                    ],
                    "type": "string"
                  }
                },
                "required": [
                  "health"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Integration health recorded"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record connector health for an authorized utility integration"
      }
    },
    "$PRIVATE_API/measurements": {
      "post": {
        "description": "Requires a tenant-bound connector carrying the private:network:measurements:ingest scope. The body tenant_id must match the connector tenant.",
        "operationId": "ingestMeasurement",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/Measurement"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Measurement accepted for idempotent processing"
          },
          "401": {
            "description": "Connector authentication required"
          },
          "403": {
            "description": "Connector scope or tenant does not authorize measurement ingestion"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Ingest a normalized device measurement"
      }
    },
    "$PRIVATE_API/meter-events": {
      "post": {
        "description": "The authenticated utility integration is recorded as source provenance; duplicate events are idempotent.",
        "operationId": "submitRemoteMeterEvent",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoteReadingSubmission"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Reading"
                }
              }
            },
            "description": "Reading accepted for validation or review"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit one normalized remote meter reading event"
      }
    },
    "$PRIVATE_API/notification-deliveries/acquire": {
      "post": {
        "description": "Requires a tenant-bound connector with the private:notification-deliveries:acquire scope. The connector tenant determines the delivery queue; X-Tenant-ID cannot change it.",
        "operationId": "acquireNotificationDelivery",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "lease_seconds": {
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "type": "object"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Delivery lease granted"
          },
          "400": {
            "description": "No eligible delivery is available"
          },
          "401": {
            "description": "Connector authentication required"
          },
          "403": {
            "description": "Connector scope does not authorize delivery acquisition"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Acquire a durable lease for a notification delivery"
      }
    },
    "$PRIVATE_API/notification-deliveries/{id}/complete": {
      "post": {
        "description": "Requires the lease-owning tenant-bound connector with the private:notification-deliveries:complete scope.",
        "operationId": "completeNotificationDelivery",
        "parameters": [
          {
            "description": "Identifier of the notification delivery the calling connector leased through the acquire call; the delivery must belong to the tenant of the connector's credentials (or the X-Tenant-ID header when the credentials carry no tenant).",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CompleteNotificationDelivery"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Delivery outcome recorded"
          },
          "400": {
            "description": "Delivery outcome or lease is invalid or outside the connector tenant"
          },
          "401": {
            "description": "Connector authentication required"
          },
          "403": {
            "description": "Connector scope does not authorize delivery completion"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record an idempotent delivery result"
      }
    },
    "$PRIVATE_API/notification-deliveries/{id}/renew": {
      "post": {
        "description": "Requires the lease-owning tenant-bound connector with the private:notification-deliveries:renew scope.",
        "operationId": "renewNotificationDeliveryLease",
        "parameters": [
          {
            "description": "Identifier of the notification delivery whose lease the calling connector holds, as returned by the acquire call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "description": "Delivery lease renewed"
          },
          "400": {
            "description": "Delivery lease is invalid or outside the connector tenant"
          },
          "401": {
            "description": "Connector authentication required"
          },
          "403": {
            "description": "Connector scope does not authorize lease renewal"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Renew an active delivery lease"
      }
    },
    "$PRIVATE_API/payment-confirmations": {
      "post": {
        "description": "Provider-specific callbacks are verified at the adapter boundary and normalized before this operation.",
        "operationId": "recordProviderPaymentConfirmation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PaymentConfirmation"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "description": "Confirmation accepted for idempotent posting and reconciliation"
          },
          "403": {
            "description": "CAPABILITY_INACTIVE: the payments capability is not active because the utility's onboarding is not approved. RFC 7807 Problem Details with code CAPABILITY_INACTIVE and a detail naming the capability."
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Record a verified external payment confirmation"
      }
    },
    "$PRIVATE_API/reading-batches": {
      "post": {
        "description": "Events are independently idempotent and each result reports its own ingestion outcome.",
        "operationId": "submitRemoteReadingBatch",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/RemoteReadingBatch"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "results": {
                      "items": {
                        "properties": {
                          "error": {
                            "type": "string"
                          },
                          "event_id": {
                            "type": "string"
                          },
                          "reading": {
                            "$ref": "#/components/schemas/Reading"
                          },
                          "status": {
                            "type": "string"
                          }
                        },
                        "required": [
                          "event_id",
                          "status"
                        ],
                        "type": "object"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "results"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Per-event ingestion results"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Submit a retry-safe batch of normalized remote readings"
      }
    },
    "$PRIVATE_API/reading-requests/lease": {
      "post": {
        "description": "Claims up to `limit` open reading requests for the integration source behind the caller's credentials and returns them in `data`, earliest due first. `limit` is required and must be between 1 and 100, otherwise the call fails with 400. Each returned request moves to `assigned` with a five-minute lease and its attempt count goes up by one; requests whose lease has lapsed are handed out again, and requests already past their due time are marked `expired` and not returned. The caller must be a connector authenticated within a tenant, and the source must be an active private integration with the lease scope, otherwise the call fails with 401 or 403.",
        "operationId": "leaseRemoteReadingRequests",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "limit": {
                    "maximum": 100,
                    "minimum": 1,
                    "type": "integer"
                  }
                },
                "required": [
                  "limit"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "description": "Leased reading requests with retry deadlines"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Lease due requests for the authenticated integration source"
      }
    },
    "$PRIVATE_API/reading-requests/{id}/failure": {
      "post": {
        "description": "Closes a leased reading request as `failed` and stores the given `reason`, which is trimmed and must be 1 to 500 characters (400 otherwise). Only the integration source that holds the request can report it: a request of another tenant or another source answers 404, and the source must be authorized for the failure scope (403 otherwise). The request must still be in the `assigned` state; on success the lease is cleared, the completion time is set and the response is 204 with no body.",
        "operationId": "failRemoteReadingRequest",
        "parameters": [
          {
            "description": "Identifier of the reading request (prefixed `rrq_`) that this integration source received from the lease call.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "properties": {
                  "reason": {
                    "maxLength": 500,
                    "type": "string"
                  }
                },
                "required": [
                  "reason"
                ],
                "type": "object"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Request marked as failed"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Report a failed remote acquisition attempt"
      }
    },
    "$PRIVATE_API/telemetry": {
      "post": {
        "description": "Requires a tenant-bound connector with the private:telemetry:write scope. The authenticated principal tenant selects the sensor namespace; tenant headers do not override it.",
        "operationId": "ingestTelemetry",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/IngestRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "202": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/IngestResult"
                }
              }
            },
            "description": "OK"
          },
          "400": {
            "description": "RFC 7807 problem for invalid input"
          },
          "401": {
            "description": "Authenticated connector with a tenant is required"
          },
          "403": {
            "description": "RFC 7807 problem when the scope is missing or the resource belongs to another tenant"
          }
        },
        "security": [
          {
            "bearerAuth": []
          }
        ],
        "summary": "Ingest a SCADA telemetry batch, tolerant of out-of-order and duplicate samples"
      }
    },
    "$PUBLIC_API/areas/search": {
      "get": {
        "description": "Answers \"who serves this place?\" without sign-in: matches the text against the active service areas of approved, active utilities and returns one listing per matching area, with the utility's name, its slug for public brand files and the area's name. No customer data or counts are returned. q must be 2 to 100 characters after trimming, or the response is 400.",
        "operationId": "searchPublicAreas",
        "parameters": [
          {
            "description": "Place name to look for, 2 to 100 characters; matched against service area names.",
            "in": "query",
            "name": "q",
            "required": true,
            "schema": {
              "maxLength": 100,
              "minLength": 2,
              "type": "string"
            }
          },
          {
            "description": "Maximum number of listings, default 5. Values above 20 are reduced to 20; zero, negative or non-numeric values return 400.",
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "default": 5,
              "maximum": 20,
              "minimum": 1,
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicAreaSearchResponse"
                }
              }
            },
            "description": "Matching area listings"
          },
          "400": {
            "description": "q missing or out of length, or limit invalid (RFC 7807)"
          }
        },
        "security": [],
        "summary": "Find the utilities that serve a place"
      }
    },
    "$PUBLIC_API/branding": {
      "get": {
        "description": "The commercial name, contacts, links, colours and logo files. Configuration (branding) sets the defaults and the platform owner can override each value. Sends an ETag and Cache-Control public, max-age=60, and answers If-None-Match with 304. Clients cache the last brand and never block start-up on it. With tenant=<slug> it returns that utility's effective brand: per field, the utility's runtime value, its static value (branding.tenants), its business profile, then the platform brand.",
        "operationId": "getBranding",
        "parameters": [
          {
            "description": "One or more ETag values from a previous response, comma separated, weak (`W/`) tags and `*` accepted; when one matches the current brand document the server answers 304 with no body.",
            "in": "header",
            "name": "If-None-Match",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "A utility's slug",
            "in": "query",
            "name": "tenant",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/Branding"
                    },
                    {
                      "$ref": "#/components/schemas/TenantBranding"
                    }
                  ]
                }
              }
            },
            "description": "Brand",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              },
              "ETag": {
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "304": {
            "description": "The brand has not changed since the given ETag"
          },
          "404": {
            "description": "No utility has this slug"
          }
        },
        "security": [],
        "summary": "The product brand clients show before and after sign-in"
      }
    },
    "$PUBLIC_API/branding/assets/{kind}": {
      "get": {
        "description": "Served with its content type. When the v query matches the current file hash the response is cached for a year (immutable); the asset URLs in the brand carry it. SVG files are served sanitised, without scripts, event handlers or external references.",
        "operationId": "getBrandingAsset",
        "parameters": [
          {
            "description": "Which platform brand file to return: `logo`, `logo_dark` or `icon`; any other value answers 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          },
          {
            "description": "File version hash, as carried in the asset URLs of the branding document; when it equals the current file's hash the response is cached for a year as immutable, otherwise for 60 seconds, and the file served is always the current one.",
            "in": "query",
            "name": "v",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/webp": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/x-icon": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "File"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "No file is set for this kind"
          }
        },
        "security": [],
        "summary": "A brand file (logo, dark logo or icon)"
      }
    },
    "$PUBLIC_API/branding/tenants/{slug}/assets/{kind}": {
      "get": {
        "description": "Same caching as the platform files. Only the utility's own files are served; a utility never inherits the platform's.",
        "operationId": "getTenantBrandingAsset",
        "parameters": [
          {
            "description": "Public slug of the tenant (utility workspace) whose brand file is requested; an unknown slug answers 404.",
            "in": "path",
            "name": "slug",
            "required": true,
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "Which tenant brand file to return: `logo`, `logo_dark` or `icon`; any other value, or a file the tenant has not set, answers 404.",
            "in": "path",
            "name": "kind",
            "required": true,
            "schema": {
              "enum": [
                "logo",
                "logo_dark",
                "icon"
              ],
              "type": "string"
            }
          },
          {
            "description": "File version hash, as carried in the tenant's asset URLs; when it equals the current file's hash the response is cached for a year as immutable, otherwise for 60 seconds, and the file served is always the current one.",
            "in": "query",
            "name": "v",
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/webp": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/x-icon": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "File"
          },
          "304": {
            "description": "Not modified"
          },
          "404": {
            "description": "Unknown utility or no file"
          }
        },
        "security": [],
        "summary": "A utility's brand file"
      }
    },
    "$PUBLIC_API/challenge": {
      "get": {
        "description": "Issues a short-lived SHA-256 proof-of-work challenge when the server is configured with security.challenge.provider=builtin. Returns 404 otherwise. Served with Cache-Control: no-store and rate-limited per IP.",
        "operationId": "getChallenge",
        "parameters": [
          {
            "description": "The form the challenge protects. The solved challenge is bound to this scope and is accepted only by the request of that form.",
            "in": "query",
            "name": "scope",
            "required": true,
            "schema": {
              "enum": [
                "identity.signup",
                "identity.login",
                "identity.password_reset",
                "identity.verification_code",
                "connection.estimate",
                "connection.request",
                "intake.contact",
                "intake.docs_feedback"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "algorithm": {
                      "example": "SHA-256",
                      "type": "string"
                    },
                    "challenge": {
                      "type": "string"
                    },
                    "maxnumber": {
                      "type": "integer"
                    },
                    "salt": {
                      "type": "string"
                    },
                    "signature": {
                      "type": "string"
                    }
                  },
                  "required": [
                    "algorithm",
                    "challenge",
                    "maxnumber",
                    "salt",
                    "signature"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Challenge issued"
          },
          "400": {
            "description": "Missing or invalid challenge scope"
          },
          "404": {
            "description": "Challenge issuance not active for the configured provider"
          },
          "429": {
            "description": "Rate limit exceeded"
          }
        },
        "security": [],
        "summary": "Issue a proof-of-work bot challenge when the builtin provider is active"
      }
    },
    "$PUBLIC_API/client-settings": {
      "get": {
        "description": "The largest file an upload may carry (storage.uploads.max_file_bytes) and how long before an access token expires to renew it (security.token_refresh_ahead), so no client repeats them in its own code. Clients that cannot read it keep working: the server enforces the limit, and a 401 still triggers a refresh.",
        "operationId": "getClientSettings",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ClientSettings"
                }
              }
            },
            "description": "Client settings"
          }
        },
        "security": [],
        "summary": "Rules the server enforces that clients need before a request"
      }
    },
    "$PUBLIC_API/connectors": {
      "get": {
        "description": "Lists the connectors this installation has enabled (for example payment, messaging and meter connectors), for an integrations directory. Each entry is the connector's public descriptor: key, kind, display name, description and capabilities, plus a mark URL when the connector has a mark image. Connectors are registered at runtime, so the list differs between installations; disabled and development-only connectors are left out. Sorted by kind, then key. No sign-in is needed; responses may be cached for 5 minutes.",
        "operationId": "getPublicConnectors",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicConnectorList"
                }
              }
            },
            "description": "Enabled connectors",
            "headers": {
              "Cache-Control": {
                "description": "public, max-age=300",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "Connectors enabled on this installation"
      }
    },
    "$PUBLIC_API/connectors/{key}/mark": {
      "get": {
        "description": "Returns the raw mark image registered for a connector, with the content type it was registered with (for example image/svg+xml or image/png). Use the mark URL from the connector list rather than building it. A key with no registered mark returns 404. No sign-in is needed; responses may be cached for 5 minutes.",
        "operationId": "getPublicConnectorMark",
        "parameters": [
          {
            "description": "Connector key as returned by the connector list (case-insensitive).",
            "in": "path",
            "name": "key",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "image/png": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/svg+xml": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              },
              "image/webp": {
                "schema": {
                  "format": "binary",
                  "type": "string"
                }
              }
            },
            "description": "Mark image bytes",
            "headers": {
              "Cache-Control": {
                "description": "public, max-age=300",
                "schema": {
                  "type": "string"
                }
              }
            }
          },
          "404": {
            "description": "No mark registered for this connector key"
          }
        },
        "security": [],
        "summary": "A connector's mark image"
      }
    },
    "$PUBLIC_API/contact-requests": {
      "post": {
        "description": "Stores a contact form submission for the platform team and notifies them. topic, name (up to 120 characters), organization (up to 160), email (up to 254, a plain address) and message (up to 2000) are required; phone is up to 40 characters, connections must not be negative, and locale is pt (default) or en. The body is at most 4096 bytes (413 PAYLOAD_TOO_LARGE). When the installation enables the bot challenge, an anonymous UI request must carry challenge_token (scope intake.contact): a missing token returns 403 CHALLENGE_REQUIRED and a rejected one 403 CHALLENGE_FAILED; a signed-in caller skips the challenge. At most 5 requests per IP address and 3 per e-mail address are accepted per hour; beyond that the response is 429 RATE_LIMITED with Retry-After. A request whose hidden website field is filled is answered 201 but not stored.",
        "operationId": "createPublicContactRequest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePublicContactRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicContactRequestReceipt"
                }
              }
            },
            "description": "Contact request received"
          },
          "400": {
            "description": "Invalid JSON body or a field failed validation (RFC 7807)"
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "413": {
            "description": "Body larger than 4096 bytes (PAYLOAD_TOO_LARGE)"
          },
          "429": {
            "description": "Too many requests from this address or for this e-mail (RATE_LIMITED); Retry-After says how many seconds to wait"
          }
        },
        "security": [],
        "summary": "Send a contact request to the platform team"
      }
    },
    "$PUBLIC_API/docs-feedback": {
      "post": {
        "description": "Records an anonymous helpful or unhelpful vote on a documentation page, with an optional comment. path must start with /, be at most 256 characters and contain no \"..\", \"?\" or \"#\"; helpful is required; comment is at most 500 characters; locale is pt (default) or en. The body is at most 4096 bytes (413 PAYLOAD_TOO_LARGE). When the installation uses its built-in bot challenge, an anonymous UI request must carry challenge_token (scope intake.docs_feedback): a missing token returns 403 CHALLENGE_REQUIRED and a rejected one 403 CHALLENGE_FAILED; a signed-in caller, or an installation using an external challenge provider, is not asked for a token. At most 20 votes per IP address are accepted per hour; beyond that the response is 429 RATE_LIMITED with Retry-After.",
        "operationId": "createPublicDocsFeedback",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/CreatePublicDocsFeedback"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicDocsFeedbackReceipt"
                }
              }
            },
            "description": "Feedback recorded"
          },
          "400": {
            "description": "Invalid JSON body or a field failed validation (RFC 7807)"
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "413": {
            "description": "Body larger than 4096 bytes (PAYLOAD_TOO_LARGE)"
          },
          "429": {
            "description": "Too many votes from this address (RATE_LIMITED); Retry-After says how many seconds to wait"
          }
        },
        "security": [],
        "summary": "Rate a documentation page as helpful or not"
      }
    },
    "$PUBLIC_API/estimates": {
      "post": {
        "description": "Priced from the utility's configured connection fee (tariff charge components with accounting_role connection_fee). Without a configured price the answer has no amount and says the utility will quote (priced false).",
        "operationId": "estimateConnection",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/ConnectionEstimateRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ConnectionEstimate"
                }
              }
            },
            "description": "Estimate"
          },
          "400": {
            "description": "Locality or tenant_id is required",
            "or the connection type is unknown": null
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          }
        },
        "security": [],
        "summary": "Estimate the price of a new connection without an account"
      }
    },
    "$PUBLIC_API/first-run/abandon": {
      "post": {
        "description": "Records an explicit exit from the selected resident journey with the anonymous timing token, the journey ID (resident_link or resident_connection) and the step ID. A token bound to a signed-in identity is refused. Repeats are idempotent.",
        "operationId": "abandonPublicFirstRun",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/FirstRunAbandonRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "204": {
            "description": "Exit recorded"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Invalid or expired token, or unknown journey or step"
          },
          "403": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The token is bound to an identity"
          }
        },
        "security": [],
        "summary": "Record an explicit exit before sign-in"
      }
    },
    "$PUBLIC_API/next-steps": {
      "get": {
        "description": "Returns the resident entry before sign-in: exactly two doors (link an existing account, request a new connection) and the public utility lookup and request-status actions, each with localized text and a help article ID, plus a signed timing token that holds no user, contact, account, tenant, IP or device identifier. Nothing here is a checklist step; a journey starts only when the resident picks a door.",
        "operationId": "getPublicNextSteps",
        "parameters": [
          {
            "description": "Only resident is supported",
            "in": "query",
            "name": "audience",
            "required": true,
            "schema": {
              "enum": [
                "resident"
              ],
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/NextSteps"
                }
              }
            },
            "description": "Resident entry"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Unsupported audience"
          }
        },
        "security": [],
        "summary": "The anonymous resident entry"
      }
    },
    "$PUBLIC_API/payment-instructions": {
      "get": {
        "description": "Returns, without sign-in, the payment method keys the platform accepts for its own invoices (taken from the enabled payment connectors at runtime) and the label and value pairs the operator configured, such as account details. instructions is empty when none are configured. Responses may be cached for 5 minutes.",
        "operationId": "getPublicPaymentInstructions",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicPaymentInstructions"
                }
              }
            },
            "description": "Accepted methods and payment instructions",
            "headers": {
              "Cache-Control": {
                "description": "public, max-age=300",
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "How platform invoices can be paid"
      }
    },
    "$PUBLIC_API/plans": {
      "get": {
        "description": "Published plans in display order, with no internal fields, and the custom offer past the largest plan. Name, tagline, capability labels and offer text are in the caller's language: lang, else Accept-Language, else the plan's default text; name_i18n and tagline_i18n carry every translation. Sends Cache-Control public, max-age=300 and Vary Accept-Language.",
        "operationId": "getPublicPlans",
        "parameters": [
          {
            "$ref": "#/components/parameters/PlanLang"
          },
          {
            "$ref": "#/components/parameters/AcceptLanguage"
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "properties": {
                    "data": {
                      "items": {
                        "$ref": "#/components/schemas/PublicPlan"
                      },
                      "type": "array"
                    },
                    "offers": {
                      "description": "Offers listed beside the plans; the custom offer (code custom) when a published plan has a connection limit.",
                      "items": {
                        "$ref": "#/components/schemas/PlanOffer"
                      },
                      "type": "array"
                    }
                  },
                  "required": [
                    "data",
                    "offers"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "Published plans",
            "headers": {
              "Cache-Control": {
                "schema": {
                  "type": "string"
                }
              }
            }
          }
        },
        "security": [],
        "summary": "The published plans and the offers beside them, for the public site"
      }
    },
    "$PUBLIC_API/service-requests": {
      "post": {
        "description": "Verifies the phone code from POST $AUTH_API/phone-codes, finds or creates the person's consumer identity (no password) and files the request with the utility. The answer shows only the request's progress, never personal data.",
        "operationId": "createPublicServiceRequest",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/PublicServiceRequestInput"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicServiceRequest"
                }
              }
            },
            "description": "Request filed"
          },
          "400": {
            "description": "Missing fields, or SERVICE_REQUEST_INVALID_CODE when the phone code is wrong or expired"
          },
          "403": {
            "description": "Bot challenge required or failed (CHALLENGE_REQUIRED / CHALLENGE_FAILED)"
          },
          "409": {
            "description": "SERVICE_REQUEST_ADDRESS_CONNECTED; the address already has a connection. The holder is never named."
          },
          "429": {
            "description": "SERVICE_REQUEST_LIMIT when the person already has the maximum open requests, or SERVICE_REQUEST_CODE_LOCKED after too many wrong codes, with a Retry-After header and params.retry_after_seconds"
          },
          "503": {
            "description": "SERVICE_REQUESTS_UNAVAILABLE; phone verification or storage is not configured"
          }
        },
        "security": [],
        "summary": "Request a new connection with a verified phone, without an account"
      }
    },
    "$PUBLIC_API/service-requests/{id}": {
      "get": {
        "description": "Shows status and estimate only; no phone, name, address or decline reason.",
        "operationId": "getPublicServiceRequest",
        "parameters": [
          {
            "description": "Identifier returned when the service request was created without an account; anyone holding it sees only the status, timestamps and, once priced, the estimate range, never the requester's contact details or address.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "pattern": "^sqr_",
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/PublicServiceRequest"
                }
              }
            },
            "description": "Request progress"
          },
          "404": {
            "description": "No such request"
          }
        },
        "security": [],
        "summary": "Follow a service request's progress by its id"
      }
    },
    "$PUBLIC_API/status": {
      "get": {
        "description": "Answers {\"status\":\"ok\"} while the server is up, for apps that show whether they can reach it (the desktop app's online state). It reports nothing about dependencies or the version: the health and readiness probes (/livez, /readyz, /healthz) are served on the internal metrics listener only.",
        "operationId": "getPublicStatus",
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "example": {
                  "status": "ok"
                },
                "schema": {
                  "properties": {
                    "status": {
                      "enum": [
                        "ok"
                      ],
                      "type": "string"
                    }
                  },
                  "required": [
                    "status"
                  ],
                  "type": "object"
                }
              }
            },
            "description": "The server is up"
          }
        },
        "security": [],
        "summary": "Whether the server answers"
      }
    },
    "$PUBLIC_API/utility-invitations/accept": {
      "post": {
        "description": "Consumes a valid token once, with the owner's display name (for a new account) and chosen password. For an invitation the utility name, country and plan come from the record and the response's session is the owner's normal utility session. For an on-behalf invitation the owner becomes a member but the utility stays closed until they accept the handover: the response carries handover.state pending_owner_acceptance and the handover summary, and the same session can call only the handover routes. An existing person must give their current password. Replays, expired and revoked tokens return 410.",
        "operationId": "acceptUtilityInvitation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UtilityInvitationAccept"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitationAcceptResult"
                }
              }
            },
            "description": "Accepted"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Missing name, weak password, or a password that does not match the existing account"
          },
          "409": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "The contact is already used"
          },
          "410": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Expired, revoked or used"
          }
        },
        "security": [],
        "summary": "Accept an invitation and create the owner's own credentials"
      }
    },
    "$PUBLIC_API/utility-invitations/open": {
      "post": {
        "description": "Resolves the one-time token from the invitation landing page and records the invitation as opened. Returns the utility name, country, setup mode, masked owner contact and expiry so the page can be prefilled. Expired, revoked or used tokens return 410 without saying whether any account exists.",
        "operationId": "openUtilityInvitation",
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/UtilityInvitationToken"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/UtilityInvitationPreview"
                }
              }
            },
            "description": "Invitation preview"
          },
          "400": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Malformed body"
          },
          "410": {
            "content": {
              "application/problem+json": {
                "schema": {
                  "$ref": "#/components/schemas/ProblemDetails"
                }
              }
            },
            "description": "Expired, revoked or used"
          }
        },
        "security": [],
        "summary": "Resolve an invitation link"
      }
    },
    "/scim/v2/ResourceTypes": {
      "get": {
        "description": "Returns a SCIM ListResponse with a single resource type, `User`, served at `/Users` with the core User schema. The call needs no bearer token and returns the same static document for every tenant, so directory clients can discover what the server supports before provisioning.",
        "operationId": "scimListResourceTypes",
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMResourceTypeList"
                }
              }
            },
            "description": "SCIM resource type list"
          }
        },
        "security": [],
        "summary": "List public SCIM resource types"
      }
    },
    "/scim/v2/Schemas": {
      "get": {
        "description": "Returns a SCIM ListResponse with the core User schema and the attributes this server models: `userName` (required, unique), `displayName`, `externalId` (unique) and `active`. The document is static and needs no bearer token; attributes outside this list, such as enterprise extensions, are accepted on writes but not stored.",
        "operationId": "scimListSchemas",
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMSchemaList"
                }
              }
            },
            "description": "SCIM schema list"
          }
        },
        "security": [],
        "summary": "List public SCIM schemas"
      }
    },
    "/scim/v2/ServiceProviderConfig": {
      "get": {
        "description": "Returns the static capability document that directory clients read before syncing: PATCH and filtering are supported (at most 200 results per page), while bulk operations, sorting, ETags and password changes are not. The only authentication scheme is an OAuth bearer token, a dedicated token issued per tenant. No token is needed to read this document.",
        "operationId": "scimGetServiceProviderConfig",
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMServiceProviderConfig"
                }
              }
            },
            "description": "Supported SCIM capabilities"
          }
        },
        "security": [],
        "summary": "Get public SCIM service provider capabilities"
      }
    },
    "/scim/v2/Users": {
      "get": {
        "description": "Lists the members of the tenant bound to the bearer token, including suspended ones, as a SCIM ListResponse with `totalResults`, `startIndex` and `itemsPerPage`. The optional `filter` takes RFC 7644 expressions on `id`, `userName`, `externalId`, `displayName` and `active` (operators such as eq, ne, co, sw, ew and pr, combined with and/or); a filter that cannot be parsed answers 400 with scimType `invalidFilter`. A missing or invalid token answers 401. Each user's `id` is the tenant membership identifier, and `meta.location` points to its `/scim/v2/Users/{id}` URL.",
        "operationId": "scimListUsers",
        "parameters": [
          {
            "description": "RFC 7644 filter expression",
            "in": "query",
            "name": "filter",
            "schema": {
              "type": "string"
            }
          },
          {
            "description": "1-based position of the first result to return; missing, non-numeric or values below 1 are treated as 1.",
            "in": "query",
            "name": "startIndex",
            "schema": {
              "type": "integer"
            }
          },
          {
            "description": "Maximum number of users to return on this page; defaults to 100 when missing or not a number, is capped at 200, and 0 returns only the total.",
            "in": "query",
            "name": "count",
            "schema": {
              "type": "integer"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMListResponse"
                }
              }
            },
            "description": "ListResponse"
          },
          "400": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "invalidFilter"
          },
          "401": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid token"
          }
        },
        "security": [
          {
            "scimTokenAuth": []
          }
        ],
        "summary": "SCIM 2.0 user search within the token's tenant"
      },
      "post": {
        "description": "Adds a member to the tenant bound to the bearer token and returns the SCIM user with 201 and a Location header. The email, taken from the primary `emails` value or from `userName`, must be valid and belong to the tenant's verified SSO domain, otherwise 400 `invalidValue`. A new person gets a verified account with no usable password; an existing active account is attached to the tenant instead. Roles come from the SSO connection's default roles, `active: false` creates the membership suspended, and an address already a member here or bound elsewhere answers 409 `uniqueness`.",
        "operationId": "scimCreateUser",
        "requestBody": {
          "content": {
            "application/scim+json": {
              "schema": {
                "$ref": "#/components/schemas/SCIMUser"
              }
            }
          },
          "required": true
        },
        "responses": {
          "201": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMUser"
                }
              }
            },
            "description": "Created SCIM user",
            "headers": {
              "Location": {
                "schema": {
                  "format": "uri-reference",
                  "type": "string"
                }
              }
            }
          },
          "400": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid SCIM user"
          },
          "401": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid or missing SCIM bearer token"
          },
          "409": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Username or external ID conflict"
          }
        },
        "security": [
          {
            "scimTokenAuth": []
          }
        ],
        "summary": "Provision a user in the token's tenant"
      }
    },
    "/scim/v2/Users/{id}": {
      "delete": {
        "description": "Removes the member from the tenant bound to the bearer token, revoking every session of that membership first so access ends immediately, and answers 204. The person's account itself is kept, and an audit entry is written. Removing the last owner of the tenant answers 409, and an unknown id or one from another tenant answers 404.",
        "operationId": "scimDeleteUser",
        "parameters": [
          {
            "description": "SCIM user id, the tenant membership identifier to remove.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "204": {
            "description": "User deprovisioned and access revoked"
          },
          "401": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid or missing SCIM bearer token"
          },
          "404": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Not found in this tenant"
          },
          "409": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Cannot remove the last tenant owner"
          }
        },
        "security": [
          {
            "scimTokenAuth": []
          }
        ],
        "summary": "Deprovision a user in the token's tenant"
      },
      "get": {
        "description": "Returns one member of the tenant bound to the bearer token as a SCIM user, with the full name split into given and family names and `active` true only when both the membership and the account are active. An id that does not exist or belongs to another tenant answers 404, so a token can never read outside its tenant.",
        "operationId": "scimGetUser",
        "parameters": [
          {
            "description": "SCIM user id, which is the tenant membership identifier returned by create or list, not a global account id.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMUser"
                }
              }
            },
            "description": "User"
          },
          "401": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid or missing SCIM bearer token"
          },
          "404": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Not found in this tenant"
          }
        },
        "security": [
          {
            "scimTokenAuth": []
          }
        ],
        "summary": "SCIM 2.0 user by id, within the token's tenant"
      },
      "patch": {
        "description": "Applies an RFC 7644 PatchOp to the member: the body must list the PatchOp schema and at least one operation, each with op `add`, `replace` or `remove`. Supported paths are `active`, `userName`, `emails`, `externalId`, `displayName` and `name.formatted`/`givenName`/`familyName`; `id` and `meta` are read only, `active` and `userName` cannot be removed, and unknown attributes are ignored so a sync run is not aborted. The result is then saved with the same rules as a full replace, including session revocation when `active` becomes false.",
        "operationId": "scimPatchUser",
        "parameters": [
          {
            "description": "SCIM user id, the tenant membership identifier; an id from another tenant answers 404.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/scim+json": {
              "schema": {
                "$ref": "#/components/schemas/SCIMPatchRequest"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMUser"
                }
              }
            },
            "description": "Updated SCIM user"
          },
          "400": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid PatchOp request"
          },
          "401": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid or missing SCIM bearer token"
          },
          "404": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Not found in this tenant"
          },
          "409": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Username or external ID conflict"
          }
        },
        "security": [
          {
            "scimTokenAuth": []
          }
        ],
        "summary": "Apply SCIM PatchOp operations to a user in the token's tenant"
      },
      "put": {
        "description": "Replaces the member's directory attributes with the given SCIM user: `userName` is required, and `id`, if present, must match the path (400 `mutability` otherwise). The email and name change only when the account belongs to this tenant alone; changing `userName` for an account shared with other contexts answers 400, and a new email must be on the verified domain. `externalId` is updated, and `active: false` suspends the membership and revokes all its sessions, while deactivating the last owner answers 409.",
        "operationId": "scimReplaceUser",
        "parameters": [
          {
            "description": "SCIM user id, the tenant membership identifier; an id from another tenant answers 404.",
            "in": "path",
            "name": "id",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/scim+json": {
              "schema": {
                "$ref": "#/components/schemas/SCIMUser"
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMUser"
                }
              }
            },
            "description": "Updated SCIM user"
          },
          "400": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid SCIM user or immutable attribute change"
          },
          "401": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Invalid or missing SCIM bearer token"
          },
          "404": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Not found in this tenant"
          },
          "409": {
            "content": {
              "application/scim+json": {
                "schema": {
                  "$ref": "#/components/schemas/SCIMError"
                }
              }
            },
            "description": "Username or external ID conflict"
          }
        },
        "security": [
          {
            "scimTokenAuth": []
          }
        ],
        "summary": "Replace a SCIM user in the token's tenant"
      }
    }
  },
  "servers": [
    {
      "url": "/"
    }
  ]
}