turash/bugulma/backend/API_REFERENCE.md

API Reference

Base URL

http://localhost:8080

Data Model Terminology

Organization: The unified entity representing all types of organizations (businesses, cultural institutions, government buildings, healthcare facilities, etc.). In the API and database, we use:

• organization_id - Identifier for any organization
• owner_organization_id - Organization that owns a site/resource

Note: Some backend field names still use legacy business_id and owner_business_id - these will be refactored to organization_id and owner_organization_id for consistency.

Endpoints

Health & Status

Health Check

GET /health

Response:

{
  "status": "healthy",
  "database": "connected",
  "graph_db": "enabled|disabled",
  "api_version": "v1"
}

Platform Statistics

GET /api/stats

Response:

{
  "total_organizations": 42,
  "total_sites": 15,
  "platform_status": "active",
  "api_version": "v1",
  "graph_enabled": true
}

---

Organizations

List Organizations

GET /api/organizations

Get Organization by ID

GET /api/organizations/:id

Get Organizations by Subtype

GET /api/organizations/subtype/:subtype

Subtypes: commercial, cultural, government, religious, educational, infrastructure, healthcare, other

Get Organizations by Sector

GET /api/organizations/sector/:sector

Get Organizations by Certification

GET /api/organizations/certification/:cert

Example: /api/organizations/certification/ISO9001

Get Nearby Organizations

GET /api/organizations/nearby?lat=52.52&lng=13.40&radius=10

Query Parameters:

• lat (required): Latitude
• lng (required): Longitude
• radius (required): Radius in kilometers

Create Organization

POST /api/organizations
Content-Type: application/json

Request Body:

{
  "name": "Berlin Recycling GmbH",
  "sector": "waste_management",
  "subtype": "commercial",
  "description": "Industrial waste recycling facility",
  "logoUrl": "https://example.com/logo.png",
  "website": "https://example.com",
  "address": "Alexanderplatz 1, Berlin",
  "latitude": 52.5200,
  "longitude": 13.4050,

  "legalForm": "GmbH",
  "primaryContactEmail": "info@example.com",
  "primaryContactPhone": "+49 30 12345678",
  "industrialSector": "38",
  "companySize": 50,
  "yearsOperation": 15,
  "supplyChainRole": "manufacturer",

  "certifications": ["ISO9001", "ISO14001"],
  "businessFocus": ["waste_recycling", "circular_economy"],
  "strategicVision": "Leading sustainable waste management",
  "driversBarriers": "Cost reduction, regulatory compliance",
  "readinessMaturity": 4,
  "trustScore": 0.85,

  "technicalExpertise": ["waste_processing", "material_recovery"],
  "availableTechnology": ["sorting_equipment", "compactors"],
  "managementSystems": ["ERP", "WMS"],

  "sellsProducts": [
    {
      "name": "Recycled PET",
      "category": "plastics",
      "unit_price": 1200.50,
      "moq": 1000,
      "certifications": ["REACH"]
    }
  ],
  "offersServices": [
    {
      "type": "maintenance",
      "domain": "compressors",
      "on_site": true,
      "hourly_rate": 85.0,
      "service_area_km": 50,
      "certifications": ["ISO50001"]
    }
  ],
  "needsServices": [
    {
      "type": "consulting",
      "urgency": "medium",
      "budget": 5000.0
    }
  ],

  "yearBuilt": "2005",
  "verified": false,
  "notes": "Expanding operations",
  "sources": ["company_website", "public_registry"],

  "trustNetwork": ["org-id-1", "org-id-2"],
  "existingSymbioticRelationships": ["org-id-3"]
}

All fields are optional except name, sector, and subtype.

Update Organization

PUT /api/organizations/:id
Content-Type: application/json

Same body as Create.

Delete Organization

DELETE /api/organizations/:id

---

Sites

List Sites

GET /api/sites

Get Site by ID

GET /api/sites/:id

Get Nearby Sites

GET /api/sites/nearby?lat=52.52&lng=13.40&radius=5

Create Site

POST /api/sites
Content-Type: application/json

Request Body:

{
  "name": "Main Processing Plant",
  "address": "Industriestraße 10, Berlin",
  "latitude": 52.5100,
  "longitude": 13.3900,
  "site_type": "industrial_site",
  "floor_area_m2": 5000,
  "ownership": "owned",
  "owner_organization_id": "org-uuid",
  "available_utilities": ["electricity", "water", "gas"],
  "parking_spaces": 20,
  "loading_docks": 4,
  "crane_capacity_tonnes": 10.0,
  "energy_rating": "B"
}

Update Site

PUT /api/sites/:id

Delete Site

DELETE /api/sites/:id

---

Resource Flows

Get Resource Flow by ID

GET /api/resources/:id

Get Resource Flows by Site

GET /api/resources/site/:siteId

Get Resource Flows by Organization

GET /api/resources/organization/:organizationId

Create Resource Flow

POST /api/resources
Content-Type: application/json

Request Body:

{
  "organization_id": "org-uuid",
  "site_id": "site-uuid",
  "direction": "output",
  "type": "heat",
  "quality": {
    "temperature_celsius": 85.0,
    "pressure_bar": 2.5,
    "purity_percent": 95.0
  },
  "quantity": {
    "value": 1000.0,
    "unit": "kWh",
    "frequency": "hourly"
  },
  "time_profile": {
    "availability": "24/7",
    "seasonal_variation": false
  },
  "economic_data": {
    "cost_per_unit": 0.08,
    "currency": "EUR"
  },
  "constraints": {
    "min_volume": 500.0,
    "max_distance_km": 10.0
  },
  "service_details": {
    "type": "maintenance",
    "domain": "HVAC"
  },
  "precision_level": "measured",
  "source_type": "declared"
}

Delete Resource Flow

DELETE /api/resources/:id

---

Matching Engine

Find Matches

POST /api/matching/find-matches
Content-Type: application/json

Request Body:

{
  "resource_type": "heat",
  "max_distance_km": 10.0,
  "min_compatibility": 0.6,
  "min_economic_score": 0.5,
  "min_overall_score": 0.65
}

Response:

{
  "criteria": {
    "resource_type": "heat",
    "max_distance_km": 10.0,
    "min_compatibility": 0.6,
    "min_economic_score": 0.5,
    "min_overall_score": 0.65,
    "include_multi_party": false
  },
  "matches": [
    {
      "id": "match-uuid",
      "source_flow_id": "flow-uuid-1",
      "target_flow_id": "flow-uuid-2",
      "compatibility_score": 0.85,
      "economic_score": 0.75,
      "overall_score": 0.80,
      "distance_km": 3.2
    }
  ],
  "count": 1
}

Create Match

POST /api/matching/create
Content-Type: application/json

Status: Not yet implemented (returns 501)

Update Match Status

PUT /api/matching/status/:matchId

Status: Not yet implemented (returns 501)

---

Field Types & Enums

Organization Subtype

• commercial
• cultural
• government
• religious
• educational
• infrastructure
• healthcare
• other

Legal Form

• LLC
• corporation
• partnership
• sole_proprietorship
• GmbH
• UG
• AG

Supply Chain Role

• manufacturer
• supplier
• distributor
• consumer

Site Type

• industrial_site
• commercial_building
• office_space
• warehouse
• cultural_site
• religious_site
• government_building
• educational_facility
• healthcare_facility
• infrastructure
• mixed_use

Site Ownership

• owned
• leased
• shared
• public

Resource Direction

• input (needed)
• output (available)

Resource Type

• heat
• electricity
• water
• materials
• waste
• services

Precision Level

• estimated
• modeled
• measured

Source Type

• declared
• verified
• metered

---

Error Responses

400 Bad Request

{
  "error": "Validation error message"
}

404 Not Found

{
  "error": "Organization not found"
}

500 Internal Server Error

{
  "error": "Internal server error message"
}

501 Not Implemented

{
  "message": "Feature to be implemented"
}

---

Authentication

Status: Not yet implemented

All write operations (POST, PUT, DELETE) currently work without authentication. In production, these will require JWT authentication:

Authorization: Bearer <jwt_token>

---

Examples

Create a Complete Organization

curl -X POST http://localhost:8080/api/organizations \
  -H "Content-Type: application/json" \
  -d '{
    "name": "EcoTech Innovations",
    "sector": "manufacturing",
    "subtype": "commercial",
    "description": "Sustainable technology manufacturer",
    "address": "Tech Park 5, Berlin",
    "latitude": 52.5200,
    "longitude": 13.4050,
    "legalForm": "GmbH",
    "primaryContactEmail": "contact@ecotech.de",
    "companySize": 100,
    "yearsOperation": 8,
    "supplyChainRole": "manufacturer",
    "certifications": ["ISO14001", "ISO50001"],
    "readinessMaturity": 4,
    "trustScore": 0.9,
    "sellsProducts": [
      {
        "name": "Solar Panel",
        "category": "renewable_energy",
        "unit_price": 250.0,
        "moq": 10
      }
    ]
  }'

Find Heat Matches Nearby

curl -X POST http://localhost:8080/api/matching/find-matches \
  -H "Content-Type: application/json" \
  -d '{
    "resource_type": "heat",
    "max_distance_km": 5,
    "min_compatibility": 0.7,
    "min_overall_score": 0.75
  }'

Search Organizations by Certification

curl http://localhost:8080/api/organizations/certification/ISO14001