{
  "openapi": "3.0.3",
  "info": {
    "contact": {
      "email": "ixo@ixo.world",
      "name": "IXO Team"
    },
    "description": "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.\n",
    "license": {
      "name": "Apache License 2.0",
      "url": "http://www.apache.org/licenses/LICENSE-2.0"
    },
    "title": "Emerging Platform API",
    "version": "1.0.0"
  },
  "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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"
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "$ref": "#/components/responses/Unauthorized"
          },
          "default": {
            "$ref": "#/components/responses/UnexpectedError"
          }
        },
        "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`.\nSee https://docs.ixo.world/platforms/Emerging/emerging-api for how keys are issued and scoped.\n"
      }
    },
    "responses": {
      "BadRequest": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Bad request"
      },
      "Unauthorized": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Unauthorized"
      },
      "UnexpectedError": {
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/Error"
            }
          }
        },
        "description": "Any other error. Clients should treat an unenumerated 4xx or 5xx as this envelope and branch on the HTTP status code."
      }
    },
    "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"
        ]
      }
    }
  }
}