turash/docs/api/README.md

Turash API Documentation

This document provides comprehensive API documentation for the Turash Industrial Symbiosis Platform.

Base URL

https://api.turash.com/api/v1

Authentication

Currently, authentication is not fully implemented. All endpoints are publicly accessible.

Future Implementation:

• JWT-based authentication
• API key authentication for integrations
• Role-based access control (RBAC)

API Overview

Core Domains

• Users - User management and authentication
• Organizations - Business entities and their profiles
• Sites - Physical locations and facilities
• Resources - Resource flows (waste, energy, materials)
• Proposals - Symbiosis proposals and negotiations
• Matching - Resource matching and optimization
• Geospatial - Location-based queries and analysis
• Analytics - Platform analytics and insights
• AI - AI-powered recommendations and insights
• Graph - Graph database queries and traversals

Response Format

All API responses follow this structure:

{
  "data": {},
  "message": "Optional success message",
  "error": "Error message if applicable"
}

Error Responses

{
  "error": "Detailed error message",
  "code": "ERROR_CODE",
  "details": {}
}

Table of Contents

• Users API - User management and authentication
• Organizations API - Complete organization management
• Proposals API - Symbiosis proposals and negotiations
• Sites API - Physical location management
• Resources API - Resource flow management
• Matching API - Resource matching and optimization
• Geospatial API - Location-based services
• Analytics API - Platform analytics
• AI API - AI-powered insights
• Graph API - Graph database queries
• Authentication API - User authentication
• WebSocket API - Real-time updates

---

Users API

Get Current User

Get information about the currently authenticated user.

Endpoint: GET /api/v1/auth/me

Response:

{
  "id": "user-123",
  "email": "user@company.com",
  "name": "John Doe",
  "role": "user"
}

Get User Organizations

Get all organizations associated with the current user.

Endpoint: GET /api/v1/users/me/organizations

Response:

[
  {
    "ID": "org-123",
    "Name": "ABC Manufacturing",
    "Subtype": "commercial",
    "Sector": "Manufacturing",
    "Description": "Leading manufacturer of industrial equipment",
    "Latitude": 52.5200,
    "Longitude": 13.4050
  }
]

Note: Currently returns all organizations. Future versions will implement proper user-organization relationships.

Organizations API

List Organizations

Get all organizations with optional filtering.

Endpoint: GET /api/v1/organizations

Query Parameters:

• limit (integer, optional): Maximum number of results (default: 50)
• offset (integer, optional): Pagination offset (default: 0)
• sector (string, optional): Filter by sector
• subtype (string, optional): Filter by organization subtype
• verified (boolean, optional): Filter by verification status

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "Organization Name",
      "subtype": "business",
      "sector": "Manufacturing",
      "description": "Company description",
      "logoUrl": "https://...",
      "galleryImages": ["url1", "url2"],
      "website": "https://...",
      "address": "Full address",
      "latitude": 55.7558,
      "longitude": 37.6176,
      "legalForm": "LLC",
      "industrialSector": "C20",
      "companySize": 150,
      "yearsOperation": 10,
      "supplyChainRole": "manufacturer",
      "certifications": ["ISO9001", "ISO14001"],
      "businessFocus": ["sustainability", "innovation"],
      "technicalExpertise": ["process_optimization", "waste_management"],
      "availableTechnology": ["heat_recovery", "recycling"],
      "managementSystems": ["ERP", "MES"],
      "sellsProducts": [
        {
          "name": "Product Name",
          "category": "Industrial Waste",
          "description": "Product description",
          "quantity": 1000,
          "unit": "kg/month",
          "pricePerUnit": 0.50
        }
      ],
      "offersServices": [
        {
          "name": "Waste Treatment",
          "category": "Environmental Services",
          "description": "Waste treatment services",
          "capacity": 5000,
          "unit": "kg/day"
        }
      ],
      "needsServices": [
        {
          "category": "Transportation",
          "description": "Need logistics support",
          "urgency": "high"
        }
      ],
      "readinessMaturity": 4,
      "trustScore": 0.85,
      "verified": true,
      "createdAt": "2025-01-01T00:00:00Z",
      "updatedAt": "2025-01-01T00:00:00Z"
    }
  ],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Get Organization by ID

Endpoint: GET /api/v1/organizations/{id}

Response: Single organization object (same format as above)

Search Organizations

Full-text search across organization data.

Endpoint: GET /api/v1/organizations/search

Query Parameters:

• q (string, required): Search query
• sector (string, optional): Filter by sector
• limit (integer, optional): Max results (default: 20)

Response: Array of matching organizations

Search Suggestions

Get autocomplete suggestions for organization search.

Endpoint: GET /api/v1/organizations/suggestions

Query Parameters:

• q (string, required): Partial search query

Response:

{
  "data": [
    {
      "id": "uuid",
      "name": "Suggested Organization Name",
      "sector": "Manufacturing",
      "subtype": "business"
    }
  ]
}

Get Sector Statistics

Endpoint: GET /api/v1/organizations/sectors/stats

Response:

{
  "data": {
    "totalOrganizations": 1250,
    "sectors": {
      "Manufacturing": {
        "count": 450,
        "percentage": 36.0,
        "subtypes": {
          "business": 380,
          "facility": 70
        }
      }
    },
    "subtypes": {
      "business": 980,
      "facility": 200,
      "cultural": 50,
      "other": 20
    }
  }
}

Get Similar Organizations

Endpoint: GET /api/v1/organizations/{id}/similar

Response: Array of similar organizations based on sector, location, and capabilities

Get Organization Proposals

Endpoint: GET /api/v1/organizations/{id}/proposals

Response: Array of resource exchange proposals for the organization

Get Organization Resources

Endpoint: GET /api/v1/organizations/{id}/resources

Response: Array of resource flows associated with the organization

Get Direct Matches

Endpoint: GET /api/v1/organizations/{id}/matching/direct

Response: Direct resource matching opportunities for the organization

Create Organization

Endpoint: POST /api/v1/organizations

Request Body: See CreateOrganizationRequest structure above

Response: Created organization object

Update Organization

Endpoint: PUT /api/v1/organizations/{id}

Request Body: Same as create, all fields optional

Response: Updated organization object

Delete Organization

Endpoint: DELETE /api/v1/organizations/{id}

Response:

{
  "message": "Organization deleted successfully"
}

Upload Logo

Endpoint: POST /api/v1/organizations/{id}/logo

Content-Type: multipart/form-data

Form Fields:

• image: Image file (JPEG, PNG)

Response:

{
  "data": {
    "url": "https://api.turash.com/static/images/logos/uuid.jpg",
    "path": "/logos/uuid.jpg"
  },
  "message": "Logo uploaded successfully"
}

Upload Gallery Image

Endpoint: POST /api/v1/organizations/{id}/gallery

Content-Type: multipart/form-data

Form Fields:

• image: Image file (JPEG, PNG)

Response:

{
  "data": {
    "url": "https://api.turash.com/static/images/gallery/uuid.jpg",
    "galleryImages": ["url1", "url2", "url3"]
  },
  "message": "Gallery image uploaded successfully"
}

Delete Gallery Image

Endpoint: DELETE /api/v1/organizations/{id}/gallery?url={imageUrl}

Response:

{
  "data": {
    "galleryImages": ["url1", "url2"]
  },
  "message": "Gallery image deleted successfully"
}

---

Sites API

List Sites

Endpoint: GET /api/v1/sites

Query Parameters:

• limit, offset: Pagination
• heritage: Filter heritage sites only

Response: Array of site objects

Get Heritage Sites

Endpoint: GET /api/v1/sites/heritage

Response: Array of heritage/cultural sites

Get Site by ID

Endpoint: GET /api/v1/sites/{id}

Response: Single site object

Create Site

Endpoint: POST /api/v1/sites

Update Site

Endpoint: PUT /api/v1/sites/{id}

Delete Site

Endpoint: DELETE /api/v1/sites/{id}

---

Resources API

Get Resource by ID

Endpoint: GET /api/v1/resources/{id}

Get Resources by Site

Endpoint: GET /api/v1/resources/site/{siteId}

Get Resources by Organization

Endpoint: GET /api/v1/resources/organization/{organizationId}

Create Resource Flow

Endpoint: POST /api/v1/resources

Update Resource Flow

Endpoint: PUT /api/v1/resources/{id}

Delete Resource Flow

Endpoint: DELETE /api/v1/resources/{id}

---

Matching API

Find Matches

Endpoint: POST /api/v1/matching/find

Request Body:

{
  "resource": {
    "type": "waste_heat",
    "direction": "supply",
    "site_id": "uuid",
    "temperature_range": {
      "min_celsius": 60,
      "max_celsius": 120
    },
    "quantity_range": {
      "min_amount": 100,
      "max_amount": 1000,
      "unit": "kW"
    }
  },
  "constraints": {
    "max_distance_km": 50,
    "min_economic_value": 1000,
    "precision_preference": ["exact", "approximate"],
    "max_results": 10
  }
}

Get Top Matches

Endpoint: GET /api/v1/matching/top

Create Match from Query

Endpoint: POST /api/v1/matching/create-from-query

Get Match Details

Endpoint: GET /api/v1/matching/{matchId}

Update Match Status

Endpoint: PUT /api/v1/matching/{matchId}/status

---

Geospatial API

Spatial Analysis

Endpoint: GET /api/v1/geospatial/analysis

Distance Calculations

Endpoint: GET /api/v1/geospatial/distance

Proximity Search

Endpoint: GET /api/v1/geospatial/proximity

---

Analytics API

Platform Statistics

Endpoint: GET /api/v1/analytics/statistics

Sector Analytics

Endpoint: GET /api/v1/analytics/sectors

Matching Analytics

Endpoint: GET /api/v1/analytics/matching

---

AI API

AI Recommendations

Endpoint: GET /api/v1/ai/recommendations

AI Insights

Endpoint: GET /api/v1/ai/insights

AI Analysis

Endpoint: POST /api/v1/ai/analyze

---

Graph API

Organization Network

Endpoint: GET /api/graph/organizations/{organizationId}/network

Shortest Path

Endpoint: GET /api/graph/shortest-path

Spatial Proximity

Endpoint: GET /api/graph/spatial-proximity

Matching Opportunities

Endpoint: GET /api/graph/matching-opportunities

Graph Statistics

Endpoint: GET /api/graph/statistics

---

Authentication API

Login

Endpoint: POST /api/v1/auth/login

Request Body:

{
  "email": "user@example.com",
  "password": "password"
}

Response:

{
  "data": {
    "token": "jwt_token_here",
    "user": {
      "id": "uuid",
      "email": "user@example.com",
      "role": "admin"
    }
  }
}

Get Current User

Endpoint: GET /api/v1/auth/me

Response: Current user information

---

WebSocket API

Real-time Updates

Endpoint: ws://api.turash.com/api/v1/ws

Events:

• match_created: New resource match found
• organization_updated: Organization profile updated
• resource_flow_changed: Resource flow modified
• proposal_status_changed: Proposal status updated

---

Data Types

Organization Subtypes

• business: Commercial companies
• facility: Industrial facilities
• cultural: Cultural institutions
• religious: Religious organizations
• government: Government entities
• infrastructure: Infrastructure providers
• other: Other organization types

Resource Types

• waste_heat: Thermal waste heat
• excess_electricity: Surplus electricity
• industrial_waste: Manufacturing waste
• water_waste: Wastewater
• byproducts: Production byproducts
• materials: Recyclable materials

Resource Directions

• supply: Resource available for exchange
• demand: Resource needed

Match Status

• pending: Initial match, not reviewed
• interested: Organizations expressed interest
• negotiating: Active negotiation
• agreed: Terms agreed upon
• completed: Exchange completed
• cancelled: Match cancelled

---

Rate Limiting

• Public endpoints: 100 requests per minute per IP
• Authenticated endpoints: 1000 requests per minute per user
• File uploads: 10 uploads per minute per user

Pagination

All list endpoints support pagination:

{
  "data": [...],
  "pagination": {
    "total": 1250,
    "limit": 50,
    "offset": 0,
    "hasMore": true
  }
}

Error Codes

• VALIDATION_ERROR: Invalid request data
• NOT_FOUND: Resource not found
• UNAUTHORIZED: Authentication required
• FORBIDDEN: Insufficient permissions
• RATE_LIMITED: Too many requests
• INTERNAL_ERROR: Server error

---

This documentation is auto-generated from the codebase and reflects the current API implementation.