Quick Start Guide - Struct API Documentation

Welcome to Struct

This guide will help you create your first 3D simulation using Struct APIs. In just a few minutes, you’ll be generating immersive simulations from simple text prompts.

Step 1: Get Your API Key

Sign up at https://api.vects.ai/auth/register
Verify your email and complete the onboarding process
Generate an API key from your dashboard
Copy and save your API key securely

Keep your API key secure and never expose it in client-side code. Use environment variables or secure key management systems.

Step 2: Create Your First Simulation

Let’s create a simple urban intersection simulation:

curl -X POST "https://api.vects.ai/api/v1/simulations/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "Create a busy downtown intersection with pedestrians crossing, cars waiting at traffic lights, and a food truck on the corner"
  }'

const response = await fetch('https://api.vects.ai/api/v1/simulations/', {
  method: 'POST',
  headers: {
    'Authorization': 'Api-Key YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    prompt: "Create a busy downtown intersection with pedestrians crossing, cars waiting at traffic lights, and a food truck on the corner"
  })
});

const simulation = await response.json();
console.log('Simulation ID:', simulation.simulation_id);

import requests

url = "https://api.vects.ai/api/v1/simulations/"
headers = {
    "Authorization": "Api-Key YOUR_API_KEY",
    "Content-Type": "application/json"
}
data = {
    "prompt": "Create a busy downtown intersection with pedestrians crossing, cars waiting at traffic lights, and a food truck on the corner"
}

response = requests.post(url, headers=headers, json=data)
simulation = response.json()
print(f"Simulation ID: {simulation['simulation_id']}")

Response:

{
  "simulation_id": "sim_abc123def456",
  "status": "queued",
  "created_at": "2024-01-15T10:30:00Z",
  "estimated_completion_time": "2024-01-15T10:35:00Z",
  "prompt": "Create a busy downtown intersection with pedestrians crossing, cars waiting at traffic lights, and a food truck on the corner"
}

Step 3: Check Simulation Status

Monitor your simulation’s progress:

curl -X GET "https://api.vects.ai/api/v1/simulations/sim_abc123def456/status/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

async function checkStatus(simulationId) {
  const response = await fetch(`https://api.vects.ai/api/v1/simulations/${simulationId}/status/`, {
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });
  
  const status = await response.json();
  console.log(`Status: ${status.status} (${status.progress.percentage}%)`);
  return status;
}

// Poll every 10 seconds
const pollStatus = setInterval(async () => {
  const status = await checkStatus('sim_abc123def456');
  if (status.status === 'completed') {
    clearInterval(pollStatus);
    console.log('Simulation complete!');
  }
}, 10000);

import time

def check_status(simulation_id):
    url = f"https://api.vects.ai/api/v1/simulations/{simulation_id}/status/"
    headers = {"Authorization": "Api-Key YOUR_API_KEY"}
    
    response = requests.get(url, headers=headers)
    return response.json()

# Poll until complete
simulation_id = "sim_abc123def456"
while True:
    status = check_status(simulation_id)
    print(f"Status: {status['status']} ({status['progress']['percentage']}%)")
    
    if status['status'] == 'completed':
        print("Simulation complete!")
        break
    
    time.sleep(10)

Step 4: Retrieve Your Results

Once complete, get your simulation data:

curl -X GET "https://api.vects.ai/api/v1/simulations/sim_abc123def456/" \
  -H "Authorization: Api-Key YOUR_API_KEY"

async function getResults(simulationId) {
  const response = await fetch(`https://api.vects.ai/api/v1/simulations/${simulationId}/`, {
    headers: {
      'Authorization': 'Api-Key YOUR_API_KEY'
    }
  });
  
  const results = await response.json();
  
  console.log(`Simulation: ${results.metadata.prompt}`);
  console.log(`Agents: ${results.actors.length}`);
  console.log(`Features: ${results.features.length}`);
  
  return results;
}

const results = await getResults('sim_abc123def456');

def get_results(simulation_id):
    url = f"https://api.vects.ai/api/v1/simulations/{simulation_id}/"
    headers = {"Authorization": "Api-Key YOUR_API_KEY"}
    
    response = requests.get(url, headers=headers)
    return response.json()

results = get_results("sim_abc123def456")
print(f"Simulation: {results['metadata']['prompt']}")
print(f"Agents: {len(results['actors'])}")
print(f"Features: {len(results['features'])}")

Step 5: Try Risk Analysis

Add risk assessment to your simulation:

curl -X POST "https://api.vects.ai/risk-assessment/" \
  -H "Authorization: Api-Key YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "routePoints": [
      {"lat": 37.7749, "lng": -122.4194},
      {"lat": 37.7849, "lng": -122.4094}
    ]
  }'

Response:

{
  "riskPoints": [
    {
      "lat": 37.7749,
      "lng": -122.4194,
      "weight": 0.2,
      "riskLevel": "low"
    },
    {
      "lat": 37.7849,
      "lng": -122.4094,
      "weight": 0.7,
      "riskLevel": "high"
    }
  ],
  "summary": {
    "overallRisk": "medium",
    "averageRisk": 0.45
  }
}

Step 6: Explore Real-time MARL

Connect to the WebSocket for real-time urban mobility simulation:

const ws = new WebSocket('ws://api.vects.ai:8001/ws/marl_state');

ws.onopen = function() {
  console.log('Connected to MARL WebSocket');
  
  // Request initial agents
  ws.send(JSON.stringify({
    type: 'request_initial_agents',
    payload: {
      focus_latitude: 37.7749,
      focus_longitude: -122.4194
    }
  }));
};

ws.onmessage = function(event) {
  const message = JSON.parse(event.data);
  
  switch(message.type) {
    case 'add_agent':
      console.log('New agent:', message.payload.id);
      // Add agent to your 3D scene
      break;
    case 'initial_population_complete':
      console.log(`Loaded ${message.payload.count} agents`);
      break;
  }
};

Common Use Cases

Emergency Response Planning

const emergencySimulation = {
  prompt: "Simulate a building evacuation during a fire emergency with multiple exit routes and emergency responders",
  scenario_type: "emergency_response",
  settings: {
    max_agents: 300,
    simulation_duration: 600,
    environment_type: "indoor"
  }
};

Urban Planning

const urbanPlanningSimulation = {
  prompt: "Model pedestrian and vehicle traffic around a new subway station entrance during rush hour",
  scenario_type: "urban_planning",
  settings: {
    max_agents: 800,
    simulation_duration: 3600,
    environment_type: "mixed"
  }
};

Security Assessment

const securitySimulation = {
  prompt: "Analyze crowd flow and security coverage at a large outdoor event with multiple entry points",
  scenario_type: "security_assessment",
  settings: {
    max_agents: 1000,
    simulation_duration: 7200,
    environment_type: "outdoor"
  }
};

Next Steps

Authentication

Learn about API keys, tokens, and rate limits

Text to 3D Simulation

Explore advanced simulation generation options

Risk Analysis

Add comprehensive risk assessment to your applications

MARL WebSocket

Build real-time urban mobility applications

Integration Examples

React Application

import React, { useState, useEffect } from 'react';

function StructSimulation() {
  const [simulation, setSimulation] = useState(null);
  const [status, setStatus] = useState('idle');

  const createSimulation = async () => {
    setStatus('creating');
    
    const response = await fetch('https://api.vects.ai/api/v1/simulations/', {
      method: 'POST',
      headers: {
        'Authorization': `Api-Key ${process.env.REACT_APP_Struct_API_KEY}`,
        'Content-Type': 'application/json'
      },
      body: JSON.stringify({
        prompt: "Create a busy city intersection with traffic and pedestrians"
      })
    });
    
    const sim = await response.json();
    setSimulation(sim);
    setStatus('processing');
    
    // Poll for completion
    pollStatus(sim.simulation_id);
  };

  const pollStatus = async (simulationId) => {
    const response = await fetch(`https://api.vects.ai/api/v1/simulations/${simulationId}/status/`);
    const statusData = await response.json();
    
    if (statusData.status === 'completed') {
      setStatus('completed');
    } else {
      setTimeout(() => pollStatus(simulationId), 5000);
    }
  };

  return (
    <div>
      <h1>Struct Simulation</h1>
      <button onClick={createSimulation} disabled={status !== 'idle'}>
        Create Simulation
      </button>
      <p>Status: {status}</p>
      {simulation && <p>ID: {simulation.simulation_id}</p>}
    </div>
  );
}

Unity C# Integration

using UnityEngine;
using System.Collections;
using UnityEngine.Networking;

public class StructIntegration : MonoBehaviour 
{
    private string apiKey = "YOUR_API_KEY";
    private string baseUrl = "https://api.vects.ai/api/v1";
    
    public void CreateSimulation() 
    {
        StartCoroutine(CreateSimulationCoroutine());
    }
    
    IEnumerator CreateSimulationCoroutine() 
    {
        string json = JsonUtility.ToJson(new {
            prompt = "Create a busy intersection with cars and pedestrians"
        });
        
        using (UnityWebRequest request = UnityWebRequest.Post($"{baseUrl}/simulations/", json, "application/json")) 
        {
            request.SetRequestHeader("Authorization", $"Api-Key {apiKey}");
            
            yield return request.SendWebRequest();
            
            if (request.result == UnityWebRequest.Result.Success) 
            {
                var response = JsonUtility.FromJson<SimulationResponse>(request.downloadHandler.text);
                Debug.Log($"Simulation created: {response.simulation_id}");
                
                StartCoroutine(PollStatus(response.simulation_id));
            }
        }
    }
}

Troubleshooting

Common Issues

401 Unauthorized

Check that your API key is correct
Ensure you’re including the “Api-Key” prefix
Verify your account is active

429 Rate Limited

You’ve exceeded your plan’s rate limits
Wait before making more requests
Consider upgrading your plan

Simulation Taking Too Long

Complex prompts take longer to process
Check the estimated completion time
Use webhooks instead of polling for efficiency

Getting Help

Documentation: Browse our comprehensive API docs
Support: Email support@vects.ai
Community: Join our Discord community
Status: Check api.vects.ai/status for service status

What’s Next?

You’ve successfully created your first Struct simulation! Here are some ideas for what to explore next:

Experiment with different prompts - Try emergency scenarios, urban planning, or security assessments
Add risk analysis - Enhance your simulations with comprehensive threat assessment
Build real-time applications - Use the MARL WebSocket for dynamic simulations
Integrate with your stack - Add Struct to your existing applications
Explore advanced features - Custom settings, webhooks, and export formats

Ready to build the future of spatial intelligence? Let’s get started! 🚀

​Welcome to Struct

​Step 1: Get Your API Key

​Step 2: Create Your First Simulation

​Step 3: Check Simulation Status

​Step 4: Retrieve Your Results

​Step 5: Try Risk Analysis

​Step 6: Explore Real-time MARL

​Common Use Cases

​Emergency Response Planning

​Urban Planning

​Security Assessment

​Next Steps

Authentication

Text to 3D Simulation

Risk Analysis

MARL WebSocket

​Integration Examples

​React Application

​Unity C# Integration

​Troubleshooting

​Common Issues

​Getting Help

​What’s Next?

Welcome to Struct

Step 1: Get Your API Key

Step 2: Create Your First Simulation

Step 3: Check Simulation Status

Step 4: Retrieve Your Results

Step 5: Try Risk Analysis

Step 6: Explore Real-time MARL

Common Use Cases

Emergency Response Planning

Urban Planning

Security Assessment

Next Steps

Integration Examples

React Application

Unity C# Integration

Troubleshooting

Common Issues

Getting Help

What’s Next?