Documentation

# Header method
x-api-key: YOUR_API_KEY

# Authorization header
Authorization: Bearer YOUR_API_KEY

# Query parameter
?api_key=YOUR_API_KEY

curl -X POST https://www.retrogradeobservatory.com/api/luminacoord/v1/vortex \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "startDate": "2025-01-15",
    "startTime": "14:30",
    "timezone": "UTC-5",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "calendars": ["Individuality", "Capacity", "Flexibility"],
    "format": "standard",
    "partner_id": "test_partner"
  }'

curl -X POST https://www.retrogradeobservatory.com/api/luminacoord/v1/vortex \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "startDate": "1990-05-20",
    "startTime": "08:00",
    "endDate": "2025-01-15",
    "endTime": "14:30",
    "timezone": "UTC-5",
    "latitude": 40.7128,
    "longitude": -74.0060,
    "calendars": ["7F7F7F", "FF0000", "0000FF"],
    "format": "standard",
    "partner_id": "test_partner"
  }'

curl -X POST https://www.retrogradeobservatory.com/api/luminacoord/v1/vortex \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "startDate": "2025-01-15",
    "startTime": "19:30",
    "timezone": "UTC+05:30",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "calendars": ["Stability", "Context"],
    "partner_id": "test_partner"
  }'

{
  "success": true,
  "api_version": "1.0",
  "temporal_station": 23.456,
  "temporal_shift": "N/A (single date scenario)",
  "elements": {
    "Individuality": {
      "element_name": "Individuality",
      "calendar_code": "7F7F7F",
      "temporal_station": 23.456
    },
    "Capacity": {
      "element_name": "Capacity",
      "calendar_code": "FF0000",
      "temporal_station": 18.742
    }
  },
  "request_parameters": {
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "timezone": "UTC-5",
    "date": "2025-01-15",
    "time": "14:30"
  }
}

{
  "success": true,
  "api_version": "1.0",
  "temporal_station": "See elements for start/end values",
  "temporal_shift": 12.789,
  "elements": {
    "Individuality": {
      "element_name": "Individuality",
      "calendar_code": "7F7F7F",
      "temporal_station": {
        "start": 15.234,
        "end": 23.456
      },
      "temporal_shift": 12.789
    },
    "Capacity": {
      "element_name": "Capacity",
      "calendar_code": "FF0000",
      "temporal_station": {
        "start": 12.567,
        "end": 18.742
      },
      "temporal_shift": 8.345
    }
  },
  "request_parameters": {
    "location": {
      "latitude": 40.7128,
      "longitude": -74.0060
    },
    "timezone": "UTC-5",
    "date": "1990-05-20",
    "time": "08:00",
    "end_date": "2025-01-15",
    "end_time": "14:30"
  }
}

const fetchLuminaCoordinate = async (requestData) => {
  try {
    const response = await fetch('/api/luminacoord/v1/vortex', {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': process.env.REACT_APP_API_KEY
      },
      body: JSON.stringify(requestData)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(error.error || 'API request failed');
    }

    return await response.json();
  } catch (error) {
    console.error('Lumina Coordinate API error:', error);
    throw error;
  }
};

// Usage
const coordinateData = await fetchLuminaCoordinate({
  startDate: '2025-01-15',
  startTime: '14:30',
  timezone: 'UTC-5',
  latitude: 40.7128,
  longitude: -74.0060,
  calendars: ['Individuality', 'Capacity'],
  partner_id: 'my-app'
});

import fetch from 'node-fetch';

class LuminaCoordinateClient {
  constructor(apiKey, baseUrl = 'https://www.retrogradeobservatory.com') {
    this.apiKey = apiKey;
    this.baseUrl = baseUrl;
  }

  async calculateTemporalStation(requestData) {
    const response = await fetch(`${this.baseUrl}/api/luminacoord/v1/vortex`, {
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-api-key': this.apiKey
      },
      body: JSON.stringify(requestData)
    });

    if (!response.ok) {
      const error = await response.json();
      throw new Error(`API Error: ${error.error}`);
    }

    return await response.json();
  }
}

// Usage
const client = new LuminaCoordinateClient('YOUR_API_KEY');
const result = await client.calculateTemporalStation({
  startDate: '2025-01-15',
  startTime: '14:30',
  timezone: 'UTC-5',
  latitude: 40.7128,
  longitude: -74.0060,
  calendars: ['Individuality'],
  partner_id: 'my-service'
});

{
  "success": false,
  "error": "Missing API key",
  "api_version": "1.0",
  "endpoint": "/api/luminacoord/v1/vortex",
  "timestamp": "2025-01-15T14:30:00.000Z"
}

{
  "success": false,
  "error": "Insufficient permissions",
  "required_permission": "lumina-coordinate",
  "current_permissions": ["calculate", "lumina-ai", "lumina-map"],
  "api_version": "1.0",
  "endpoint": "/api/luminacoord/v1/vortex",
  "timestamp": "2025-01-15T14:30:00.000Z"
}

{
  "success": false,
  "error": "startTime must be in HH:MM format",
  "api_version": "1.0",
  "endpoint": "/api/luminacoord/v1/vortex",
  "timestamp": "2025-01-15T14:30:00.000Z"
}

# Production
https://os.retrogradeobservatory.com/api/bms/v1

# Development
http://localhost:3005/api/bms/v1

# Check API Health
curl https://os.retrogradeobservatory.com/api/bms/v1/health

# Get Current Signal
curl https://os.retrogradeobservatory.com/api/bms/v1/signal

# Get Signal for Specific Calendar
curl "https://os.retrogradeobservatory.com/api/bms/v1/signal?calendarId=crimson-forge&tier=standard"

# Get All 9 Calendar Signals
curl "https://os.retrogradeobservatory.com/api/bms/v1/signals?tier=minimal"

{
  "success": true,
  "version": "v1",
  "timestamp": "2025-12-04T12:00:00.000Z",
  "data": {
    "calendarId": "crimson-forge",
    "aspect": "Capacity",
    "colorHex": "#FF0000",
    "density": 1.2,
    "brightness": 0.85,
    "visibility": 0.92,
    "rhythmScale": 1.15,
    "spatialX": 0.65,
    "spatialY": 0.48,
    "spatialZ": 0.72,
    "cohesiveness": 0.78,
    "wobbleScale": 0.35,
    "interactionDepth": 0.68,
    "spatialExtent": 1.25,
    "responsiveness": 0.62,
    "verticalBias": 0.18,
    "rotationalVelocity": 1.35,
    "magneticPull": 0.52,
    "auraRadius": 1.85,
    "harmonyGlow": 1.42,
    "formSolidity": 1.12,
    "stageModifier": 1.0
  },
  "meta": {
    "tier": "standard",
    "calendarId": "crimson-forge",
    "aspect": "Capacity",
    "requestId": "550e8400-e29b-41d4-a716-446655440000"
  }
}

curl -X POST "https://os.retrogradeobservatory.com/api/bms/v1/signal" \
  -H "Content-Type: application/json" \
  -d '{
    "calendarId": "twin-spiral",
    "date": "2025-12-04",
    "time": "14:30",
    "latitude": 28.6139,
    "longitude": 77.2090,
    "timezone": "Asia/Kolkata"
  }'

{
  "bmsSignal": {
    "signal_id": "uuid",
    "archetype_id": "CRIMSON_FORGE",
    "aspect": "Capacity",
    "state": "balanced",
    "mode": "MODERATE",
    "stage": "ESTABLISHED",

    "physics": {
      "mass": 0.8,
      "scale": 1.2,
      "drag": 0.3,
      "restitution": 0.6
    },

    "render": {
      "shader": "standard",
      "opacity": 0.85,
      "wireframe": false,
      "glow": 1.2,
      "roughness": 0.4
    },

    "animation": {
      "type": "orbit",
      "speed": 1.1,
      "velocity": 0.8,
      "frequency": 2.0
    },

    "interaction": {
      "hover_effect": "glow",
      "click_effect": "pulse",
      "excitability": 0.7
    },

    "normalized_vals": {
      "A": 0.65,
      "C": 0.42,
      "Y": 0.78
    }
  }
}

# Rate Limit Headers in Response
X-RateLimit-Limit: 60
X-RateLimit-Remaining: 58
X-RateLimit-Window: 60

# When Rate Limited (HTTP 429)
{
  "success": false,
  "version": "v1",
  "error": {
    "code": "RATE_LIMITED",
    "message": "Rate limit exceeded. Try again in 45 seconds.",
    "retryAfter": 45
  }
}

const BASE_URL = 'https://os.retrogradeobservatory.com/api/bms/v1';

// Get current signal
async function getBMSSignal(calendarId = null, tier = 'standard') {
  const params = new URLSearchParams({ tier });
  if (calendarId) params.append('calendarId', calendarId);

  const response = await fetch(`${BASE_URL}/signal?${params}`);
  const data = await response.json();

  if (!data.success) {
    throw new Error(data.error.message);
  }

  return data.data;
}

// Get all 9 calendar signals
async function getAllSignals(tier = 'minimal') {
  const response = await fetch(`${BASE_URL}/signals?tier=${tier}`);
  const data = await response.json();
  return data.data;
}

// Generate signal for specific date/location
async function generateSignal(params) {
  const response = await fetch(`${BASE_URL}/signal`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({
      calendarId: params.calendarId,
      date: params.date,
      time: params.time,
      latitude: params.latitude,
      longitude: params.longitude,
      timezone: params.timezone
    })
  });
  const data = await response.json();
  return data.data;
}

// Usage
const signal = await getBMSSignal('crimson-forge', 'standard');
console.log(`Capacity brightness: ${signal.brightness}`);

import requests
from typing import Optional, Dict, Any

BASE_URL = "https://os.retrogradeobservatory.com/api/bms/v1"

def get_bms_signal(
    calendar_id: Optional[str] = None,
    tier: str = "standard"
) -> Dict[str, Any]:
    """Get BMS signal for current or specified calendar."""
    params = {"tier": tier}
    if calendar_id:
        params["calendarId"] = calendar_id

    response = requests.get(f"{BASE_URL}/signal", params=params)
    data = response.json()

    if not data["success"]:
        raise Exception(data["error"]["message"])

    return data["data"]

def get_all_signals(tier: str = "minimal") -> Dict[str, Any]:
    """Get BMS signals for all 9 calendars."""
    response = requests.get(f"{BASE_URL}/signals", params={"tier": tier})
    data = response.json()
    return data["data"]

def generate_signal(
    calendar_id: str,
    date: str,
    time: str,
    latitude: float,
    longitude: float,
    timezone: str
) -> Dict[str, Any]:
    """Generate BMS signal for specific date/time/location."""
    response = requests.post(
        f"{BASE_URL}/signal",
        json={
            "calendarId": calendar_id,
            "date": date,
            "time": time,
            "latitude": latitude,
            "longitude": longitude,
            "timezone": timezone
        }
    )
    return response.json()["data"]

# Usage
signal = get_bms_signal("crimson-forge", "full")
print(f"Capacity brightness: {signal['brightness']}")

import { useState, useEffect } from 'react';

const BASE_URL = 'https://os.retrogradeobservatory.com/api/bms/v1';

export function useBMSSignal(calendarId, tier = 'standard') {
  const [signal, setSignal] = useState(null);
  const [loading, setLoading] = useState(true);
  const [error, setError] = useState(null);

  useEffect(() => {
    const fetchSignal = async () => {
      try {
        setLoading(true);
        const params = new URLSearchParams({ tier });
        if (calendarId) params.append('calendarId', calendarId);

        const response = await fetch(`${BASE_URL}/signal?${params}`);
        const data = await response.json();

        if (!data.success) throw new Error(data.error.message);
        setSignal(data.data);
      } catch (err) {
        setError(err.message);
      } finally {
        setLoading(false);
      }
    };

    fetchSignal();
    const interval = setInterval(fetchSignal, 30000); // Refresh every 30s
    return () => clearInterval(interval);
  }, [calendarId, tier]);

  return { signal, loading, error };
}

// Usage in component
function MyComponent() {
  const { signal, loading, error } = useBMSSignal('crimson-forge');

  if (loading) return <div>Loading...</div>;
  if (error) return <div>Error: {error}</div>;

  return (
    <div style={{ backgroundColor: signal.colorHex }}>
      <h2>{signal.aspect}</h2>
      <p>Brightness: {signal.brightness}</p>
    </div>
  );
}

Header: X-BMS-API-Key: your-api-key-here