openapi: 3.0.3
info:
  contact:
    email: ixo@ixo.world
    name: IXO Team
  description: >
    Versioning: the major version is carried in the URL path (`/v1`). Retiring

    an endpoint is announced with `Deprecation` (RFC 9745) and `Sunset`

    (RFC 8594) response headers at least 180 days ahead; the full policy is at

    https://docs.ixo.world/api-reference/versioning. Every error response uses

    the envelope in `components/schemas/Error`.


    The Emerging Household Energy API is designed to facilitate seamless communication between the dMRV system and the
    registry system. It enables the registry system to retrieve accurate and timely data from the dMRV system,
    supporting efficient monitoring, reporting, and verification processes. By ensuring reliable data exchange and
    integration, the API plays a critical role in maintaining data integrity and streamlining workflows between these
    interconnected systems.
  license:
    name: Apache License 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0
  title: Emerging Platform API
  version: 1.0.0
  x-versioning:
    scheme: URL path major version
    policy: https://docs.ixo.world/api-reference/versioning
    deprecationHeaders:
      - Deprecation (RFC 9745)
      - Sunset (RFC 8594)
    minimumNoticeDays: 180
servers:
  - description: Development
    url: https://dev.api.emerging.eco/emerging-platform/v1
tags:
  - name: Household Information
    description: Endpoints related to household statistics and density profiles
  - name: Device Monitoring
    description: Endpoints for monitoring device status and activity
  - name: Fuel Management
    description: Endpoints for tracking fuel usage and consumption
  - name: Carbon Credits
    description: Endpoints for managing carbon credit lifecycle
  - name: Claims Management
    description: Endpoints for verifying and tracking various claims
  - name: System Health
    description: Server health and documentation endpoints
paths:
  /households/stats:
    get:
      description: Retrieve household statistics, including the number of serviced households and density profiles.
      operationId: getHouseholdStats
      responses:
        '200':
          content:
            application/json:
              example:
                total_households: 1500
                density:
                  low: 700
                  medium: 500
                  high: 300
              schema:
                $ref: '#/components/schemas/HouseholdStats'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get household statistics
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Household Information
  /households/stove-stacking:
    get:
      description: Analyze usage patterns combining multiple fuel types (e.g., LPG + Biomass).
      operationId: getStoveStackingData
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/StoveStacking'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get stove stacking data
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Household Information
  /devices/status:
    get:
      description: Monitor real-time status and activity logs of connected devices.
      operationId: getDeviceStatus
      responses:
        '200':
          content:
            application/json:
              example:
                device_id: device-456
                status: inactive
                last_active: '2024-01-01T08:30:00Z'
              schema:
                $ref: '#/components/schemas/DeviceStatus'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get device status and activity
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Device Monitoring
  /fuel-usage:
    get:
      description: Retrieve data on fuel usage aggregated by household, region, or time period.
      operationId: getFuelUsage
      responses:
        '200':
          content:
            application/json:
              example:
                household_id: household-010
                fuel_consumed: 42.3
                region: East Region
              schema:
                $ref: '#/components/schemas/FuelUsage'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get fuel usage metrics
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Fuel Management
  /credits/issued:
    get:
      description: Retrieve the number of credits issued per project and time period.
      operationId: getIssuedCredits
      parameters:
        - description: Unique identifier of the project.
          explode: true
          in: query
          name: project_id
          required: true
          schema:
            type: string
          style: form
        - description: Time period for which credits were issued.
          explode: true
          in: query
          name: time_period
          required: true
          schema:
            type: string
          style: form
      responses:
        '200':
          content:
            application/json:
              example:
                project_id: project-789
                time_period: 2023-Q4
                credits: 1200
              schema:
                $ref: '#/components/schemas/CreditsIssued'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get issued credits
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Carbon Credits
  /credits/cancelled:
    get:
      description: Retrieve records of credits that have been invalidated.
      operationId: getCancelledCredits
      responses:
        '200':
          content:
            application/json:
              example:
                credit_id: credit-001
                cancellation_date: '2024-01-05'
              schema:
                $ref: '#/components/schemas/CreditsCancelled'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get cancelled credits
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Carbon Credits
  /credits/transferred:
    get:
      description: View records of credits transferred to ITMOs.
      operationId: getTransferredCredits
      responses:
        '200':
          content:
            application/json:
              example:
                sender: entity-abc
                recipient: entity-xyz
                amount: 500
                transfer_date: '2024-01-10'
              schema:
                $ref: '#/components/schemas/CreditsTransferred'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get transferred credits
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Carbon Credits
  /credits/retired:
    get:
      description: Retrieve information about retired credits and their associated emission reductions.
      operationId: getRetiredCredits
      responses:
        '200':
          content:
            application/json:
              example:
                credit_id: credit-789
                retirement_date: '2024-01-15'
                emission_reductions: 350
              schema:
                $ref: '#/components/schemas/CreditsRetired'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get retired credits
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Carbon Credits
  /claims/fuel-purchase:
    get:
      description: Retrieve verified claims of purchased fuel units.
      operationId: getFuelPurchaseClaims
      responses:
        '200':
          content:
            application/json:
              example:
                fuel_id: fuel-123
                amount: 100.5
                purchase_date: '2024-01-20'
              schema:
                $ref: '#/components/schemas/FuelPurchaseClaim'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: View fuel purchase claims
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Claims Management
  /claims/fuel-delivery:
    get:
      description: Retrieve details of completed fuel deliveries.
      operationId: getFuelDeliveryClaims
      responses:
        '200':
          content:
            application/json:
              example:
                delivery_id: delivery-456
                delivery_date: '2024-01-25'
                delivered_quantity: 250
              schema:
                $ref: '#/components/schemas/FuelDeliveryClaim'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: View fuel delivery claims
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Claims Management
  /claims/emission-reduction:
    get:
      description: Retrieve records of Certified Emission Reductions (CERs) achieved.
      operationId: getEmissionReductionClaims
      responses:
        '200':
          content:
            application/json:
              example:
                project_id: project-789
                period: 2023-Q4
                reductions: 300
              schema:
                $ref: '#/components/schemas/EmissionReductionClaim'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: View emission reduction claims
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Claims Management
  /claims/household-onboarding:
    get:
      description: Retrieve records of household onboarding claims.
      operationId: getHouseholdOnboardingClaims
      responses:
        '200':
          content:
            application/json:
              example:
                household_id: household-123
                onboarding_date: '2024-01-01'
              schema:
                $ref: '#/components/schemas/HouseholdOnboardingClaim'
          description: Successful response
          headers:
            Deprecation:
              description: >-
                Present only once this operation is deprecated: an HTTP date, or an @-prefixed Unix timestamp, marking
                when it became deprecated. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
            Sunset:
              description: >-
                Present only once a retirement date is set: the HTTP date after which this operation may stop
                responding. At least 180 days of notice. See https://docs.ixo.world/api-reference/versioning
              required: false
              schema:
                type: string
        '400':
          description: The request was malformed, or a parameter failed validation.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: The bearer token is missing, expired or not valid for this resource.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: The request was well formed but the server failed to handle it. Safe to retry with backoff.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        default:
          description: Any other failure. Branch on the HTTP status code; the body is always this envelope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      summary: Get household onboarding claims
      x-eov-operation-handler: controllers/DefaultController
      tags:
        - Claims Management
security:
  - bearerAuth: []
components:
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      description: |
        API key issued through Mission Control, sent as `Authorization: Bearer YOUR_API_KEY`.
        See https://docs.ixo.world/platforms/Emerging/emerging-api for how keys are issued and scoped.
  schemas:
    HouseholdStats:
      example:
        total_households: 1500
        density:
          low: 700
          medium: 500
          high: 300
      properties:
        total_households:
          description: Total number of serviced households.
          type: integer
        density:
          $ref: '#/components/schemas/HouseholdStats_density'
    StoveStacking:
      example:
        fuel_type: LPG + Biomass
        percentage: 65.5
      properties:
        fuel_type:
          description: Type of fuel used (e.g., LPG + Biomass).
          type: string
        percentage:
          description: Percentage of households using this combination.
          format: float
          type: number
    DeviceStatus:
      example:
        device_id: device-456
        status: inactive
        last_active: '2024-01-01T08:30:00Z'
      properties:
        device_id:
          description: Unique identifier of the device.
          type: string
        status:
          description: Current operational status of the device.
          type: string
        last_active:
          description: Timestamp of the last recorded activity.
          format: date-time
          type: string
    FuelUsage:
      example:
        household_id: household-010
        fuel_consumed: 42.3
        region: East Region
      properties:
        household_id:
          description: Unique identifier of the household.
          type: string
        fuel_consumed:
          description: Total fuel consumed in the specified period.
          type: number
        region:
          description: Geographic region of the household.
          type: string
    CreditsIssued:
      example:
        project_id: project-789
        time_period: 2023-Q4
        credits: 1200
      properties:
        project_id:
          description: Unique identifier of the project.
          type: string
        time_period:
          description: Time period for which credits were issued.
          type: string
        credits:
          description: Number of credits issued.
          type: integer
    CreditsCancelled:
      example:
        credit_id: credit-001
        cancellation_date: '2024-01-05'
      properties:
        credit_id:
          description: Unique identifier of the invalidated credit.
          type: string
        cancellation_date:
          description: Date of credit cancellation.
          format: date
          type: string
    CreditsTransferred:
      example:
        sender: entity-abc
        recipient: entity-xyz
        amount: 500
        transfer_date: '2024-01-10'
      properties:
        sender:
          description: Entity transferring the credits.
          type: string
        recipient:
          description: Entity receiving the credits.
          type: string
        amount:
          description: Number of credits transferred.
          type: integer
        transfer_date:
          description: Date of credit transfer.
          format: date
          type: string
    CreditsRetired:
      example:
        credit_id: credit-789
        retirement_date: '2024-01-15'
        emission_reductions: 350
      properties:
        credit_id:
          description: Unique identifier of the retired credit.
          type: string
        retirement_date:
          description: Date of credit retirement.
          format: date
          type: string
        emission_reductions:
          description: Amount of emission reductions associated with the retired credit.
          type: integer
    FuelPurchaseClaim:
      example:
        fuel_id: fuel-123
        amount: 100.5
        purchase_date: '2024-01-20'
      properties:
        fuel_id:
          description: Unique identifier of the fuel purchase
          type: string
        amount:
          description: Amount of fuel purchased
          format: float
          type: number
        purchase_date:
          description: Date when the fuel was purchased
          format: date
          type: string
    FuelDeliveryClaim:
      example:
        delivery_id: delivery-456
        delivery_date: '2024-01-25'
        delivered_quantity: 250
      properties:
        delivery_id:
          description: Unique identifier of the delivery
          type: string
        delivery_date:
          description: Date when the fuel was delivered
          format: date
          type: string
        delivered_quantity:
          description: Quantity of fuel delivered
          format: float
          type: number
    EmissionReductionClaim:
      example:
        project_id: project-789
        period: 2023-Q4
        reductions: 300
      properties:
        project_id:
          description: Unique identifier of the project
          type: string
        period:
          description: Time period for which emissions were reduced
          type: string
        reductions:
          description: Amount of emissions reduced
          type: integer
    Error:
      type: object
      description: >-
        Error envelope returned for 4xx and 5xx responses. `message` is the only field guaranteed to be present; branch
        on the HTTP status code and treat `message` as human-readable text, not as a stable machine-readable identifier.
      example:
        message: project_id is required
      properties:
        message:
          description: Human-readable description of what went wrong.
          type: string
      required:
        - message
    HouseholdStats_density:
      properties:
        low:
          description: Number of low-density households.
          type: integer
        medium:
          description: Number of medium-density households.
          type: integer
        high:
          description: Number of high-density households.
          type: integer
    HouseholdOnboardingClaim:
      type: object
      properties:
        household_id:
          type: string
          description: Unique identifier of the household.
        onboarding_date:
          type: string
          format: date
          description: Date of onboarding.
      required:
        - household_id
        - onboarding_date