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:

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

### Error Responses

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

## Table of Contents

- [Users API](#users-api) - User management and authentication
- [Organizations API](organizations.md) - Complete organization management
- [Proposals API](proposals.md) - Symbiosis proposals and negotiations
- [Sites API](#sites-api) - Physical location management
- [Resources API](resources.md) - Resource flow management
- [Matching API](matching.md) - Resource matching and optimization
- [Geospatial API](#geospatial-api) - Location-based services
- [Analytics API](#analytics-api) - Platform analytics
- [AI API](#ai-api) - AI-powered insights
- [Graph API](#graph-api) - Graph database queries
- [Authentication API](#authentication-api) - User authentication
- [WebSocket API](#websocket-api) - Real-time updates

---

## Users API

### Get Current User

Get information about the currently authenticated user.

**Endpoint:** `GET /api/v1/auth/me`

**Response:**
```json
{
  "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:**
```json
[
  {
    "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:**
```json
{
  "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:**
```json
{
  "data": [
    {
      "id": "uuid",
      "name": "Suggested Organization Name",
      "sector": "Manufacturing",
      "subtype": "business"
    }
  ]
}
```

### Get Sector Statistics

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

**Response:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "email": "user@example.com",
  "password": "password"
}
```

**Response:**
```json
{
  "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:

```json
{
  "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.*