LUX API Endpoints

The LUX API provides endpoints for daylight simulation and server health monitoring.

Quick Start

1. Join the beta program to obtain an API token
2. Call the API endpoints using Bearer authentication

Pricing

Commercial (Hosted): Using https://api-lux.upskiller.xyz/v1 requires an API token and is subject to usage fees.

Free (Self-Hosted): Deploy locally at no cost. See deployment guide.

Endpoints

Health Check

GET /

Check server health and availability.

Request

GET https://api-lux.upskiller.xyz/v2/

Response

{
  "status": "ok",
  "service": "lux-api",
  "version": "1.0.0"
}

No authentication required for health check endpoint.

curl

curl https://api-lux.upskiller.xyz/v2/

Python

import requests

response = requests.get("https://api-lux.upskiller.xyz/v2/")
print(response.json())

Node.js

const fetch = require('node-fetch');

fetch('https://api-lux.upskiller.xyz/v2/')
  .then((response) => response.json())
  .then((data) => console.log(data));

C#

using System.Net.Http;
using System.Threading.Tasks;

var client = new HttpClient();
var response = await client.GetAsync("https://api-lux.upskiller.xyz/v2/");
var content = await response.Content.ReadAsStringAsync();
Console.WriteLine(content);

---

Calculate Horizon Angle

POST /horizon

Calculate the horizon angle - the angle measured upward from horizontal to the highest obstruction point.

Authentication Required: Include Authorization: Bearer YOUR_API_TOKEN header.

Request Body

{
  "x": 0.0,
  "y": 3.0,
  "z": 0.0,
  "rad_x": 0.0,
  "rad_y": 0.0,
  "mesh": [
    [10.0, 0.0, -5.0],
    [10.0, 5.0, -5.0],
    [10.0, 0.0, 5.0]
  ]
}

Response

{
  "status": "success",
  "data": {
    "obstruction_angle_degrees": 11.31,
    "obstruction_angle_radians": 0.1974,
    "highest_point": {
      "x": 10.0,
      "y": 5.0,
      "z": -5.0
    },
    "projected_point_count": 6
  }
}

See API Reference for complete parameter specifications.

---

Calculate Zenith Angle

POST /zenith

Calculate the zenith angle - the angle measured downward from vertical to the lowest overhead obstruction point.

Authentication Required: Include Authorization: Bearer YOUR_API_TOKEN header.

Request Body

Same parameters as /horizon endpoint.

Response

{
  "status": "success",
  "data": {
    "obstruction_angle_degrees": 51.34,
    "obstruction_angle_radians": 0.8961,
    "highest_point": {
      "x": 5.0,
      "y": 7.0,
      "z": -2.0
    },
    "projected_point_count": 6
  }
}

See API Reference for complete parameter specifications.

---

Calculate Both Angles

POST /obstruction

Calculate both horizon and zenith angles in a single request.

Authentication Required: Include Authorization: Bearer YOUR_API_TOKEN header.

Request Body

Same parameters as individual angle endpoints.

Response

{
  "status": "success",
  "data": {
    "horizon": {
      "obstruction_angle_degrees": 11.31,
      "obstruction_angle_radians": 0.1974,
      "highest_point": {...},
      "projected_point_count": 6
    },
    "zenith": {
      "obstruction_angle_degrees": 78.69,
      "obstruction_angle_radians": 1.3734,
      "highest_point": {...},
      "projected_point_count": 6
    }
  }
}

See API Reference for complete parameter specifications.

---

Execute Daylight Simulation

POST /run

Executes daylight simulation from room geometry and obstruction mesh.

Authentication Required: Include Authorization: Bearer YOUR_API_TOKEN header.

Request Body

{
  "model_type": "df_default" | "da_default" | "df_custom" | "da_custom",
  "parameters": {
    "height_roof_over_floor": 2.7,
    "floor_height_above_terrain": 3.0,
    "room_polygon": [[0, 0], [5, 0], [5, 4], [0, 4]],
    "windows": {
      "window_id": {
        "x1": -0.6, "y1": 0.0, "z1": 0.9,
        "x2": 0.6, "y2": 0.0, "z2": 2.4,
        "window_frame_ratio": 0.15
      }
    }
  },
  "mesh": [
    [10, 0, 0],
    [10, 0, 5],
    [10, 10, 5],
    [10, 10, 0]
  ]
}

Response

JSON object containing simulation results with base64-encoded numpy array and shape information.

See Parameters for complete parameter specifications and API Reference for detailed documentation.

Example Requests

curl

curl -X POST https://api-lux.upskiller.xyz/v2/run \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -d '{
    "model_type": "df_default",
    "parameters": {
      "height_roof_over_floor": 2.7,
      "floor_height_above_terrain": 3.0,
      "room_polygon": [[0, 0], [5, 0], [5, 4], [0, 4]],
      "windows": {
        "main_window": {
          "x1": -0.6, "y1": 0.0, "z1": 0.9,
          "x2": 0.6, "y2": 0.0, "z2": 2.4,
          "window_frame_ratio": 0.15
        }
      }
    },
    "mesh": [
      [10, 0, 0],
      [10, 0, 5],
      [10, 10, 5],
      [10, 10, 0]
    ]
  }'

Python

import requests

url = "https://api-lux.upskiller.xyz/v2/run"
headers = {
    "Authorization": "Bearer YOUR_API_TOKEN"
}
payload = {
    "model_type": "df_default",
    "parameters": {
        "height_roof_over_floor": 2.7,
        "floor_height_above_terrain": 3.0,
        "room_polygon": [[0, 0], [5, 0], [5, 4], [0, 4]],
        "windows": {
            "main_window": {
                "x1": -0.6, "y1": 0.0, "z1": 0.9,
                "x2": 0.6, "y2": 0.0, "z2": 2.4,
                "window_frame_ratio": 0.15
            }
        }
    },
    "mesh": [
        [10, 0, 0],
        [10, 0, 5],
        [10, 10, 5],
        [10, 10, 0]
    ]
}

response = requests.post(url, headers=headers, json=payload)

if response.status_code == 200:
    result = response.json()
    print(f"Simulation complete. Result shape: {result['shape']}")
else:
    print(f"Error: {response.json()}")

Node.js

const fetch = require('node-fetch');

const url = 'https://api-lux.upskiller.xyz/v2/run';
const payload = {
  model_type: 'df_default',
  parameters: {
    height_roof_over_floor: 2.7,
    floor_height_above_terrain: 3.0,
    room_polygon: [
      [0, 0],
      [5, 0],
      [5, 4],
      [0, 4],
    ],
    windows: {
      main_window: {
        x1: -0.6,
        y1: 0.0,
        z1: 0.9,
        x2: 0.6,
        y2: 0.0,
        z2: 2.4,
        window_frame_ratio: 0.15,
      },
    },
  },
  mesh: [
    [10, 0, 0],
    [10, 0, 5],
    [10, 10, 5],
    [10, 10, 0],
  ],
};

fetch(url, {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    Authorization: 'Bearer YOUR_API_TOKEN',
  },
  body: JSON.stringify(payload),
})
  .then((response) => response.json())
  .then((data) => console.log(`Status: ${data.status}`));

C#

using System;
using System.Net.Http;
using System.Text;
using System.Text.Json;
using System.Threading.Tasks;

var client = new HttpClient();
client.DefaultRequestHeaders.Add("Authorization", "Bearer YOUR_API_TOKEN");
var url = "https://api-lux.upskiller.xyz/v2/run";

var payload = new {
    model_type = "df_default",
    parameters = new {
        height_roof_over_floor = 2.7,
        floor_height_above_terrain = 3.0,
        room_polygon = new[] { new[] { 0, 0 }, new[] { 5, 0 }, new[] { 5, 4 }, new[] { 0, 4 } },
        windows = new {
            main_window = new {
                x1 = -0.6, y1 = 0.0, z1 = 0.9,
                x2 = 0.6, y2 = 0.0, z2 = 2.4,
                window_frame_ratio = 0.15
            }
        }
    },
    mesh = new[] {
        new[] { 10, 0, 0 },
        new[] { 10, 0, 5 },
        new[] { 10, 10, 5 },
        new[] { 10, 10, 0 }
    }
};

var json = JsonSerializer.Serialize(payload);
var content = new StringContent(json, Encoding.UTF8, "application/json");
var response = await client.PostAsync(url, content);

if (response.IsSuccessStatusCode) {
    var result = await response.Content.ReadAsStringAsync();
    Console.WriteLine(result);
}

See complete schema: Request Schema

Error Responses

All endpoints return JSON errors with appropriate status codes:

{
  "error": "Error message description"
}

See Response Format for detailed error documentation.

Rate Limits

Hosted API has no enforced rate limits currently. Subject to change as service scales.

Next Steps

API Reference - Complete parameter documentation

Authentication - Detailed authentication guide