FluxCore Dynamics Logo
FluxCore Dynamics

FluxCore Dynamics Documentation

Everything you need to master photonic design

DocumentationREST API Reference

Quick Start

5-minute quickstartAccount setupYour first design

REST API Reference

Complete API documentation for integrating FluxCore into your workflows

v1.0
20 min readLast updated: January 2025API, Integration, Development

Base URL

https://api.fluxcore.io/v1

All API endpoints are relative to this base URL. The API uses HTTPS exclusively.

Authentication

API Key Authentication

All API requests require authentication using an API key. Include your API key in the Authorization header.

# Using Bearer token
curl https://api.fluxcore.io/v1/circuits \
  -H "Authorization: Bearer YOUR_API_KEY"

# Or using X-API-Key header
curl https://api.fluxcore.io/v1/circuits \
  -H "X-API-Key: YOUR_API_KEY"

Security Notice

Never expose your API key in client-side code. Use environment variables and server-side requests for production applications.

OAuth 2.0 (Enterprise)

Enterprise customers can use OAuth 2.0 for user-authenticated API access. This enables building applications that act on behalf of users.

# OAuth 2.0 Authorization Code Flow
POST https://api.fluxcore.io/oauth/token
Content-Type: application/x-www-form-urlencoded

grant_type=authorization_code
&code=AUTHORIZATION_CODE
&client_id=YOUR_CLIENT_ID
&client_secret=YOUR_CLIENT_SECRET
&redirect_uri=https://your-app.com/callback

# Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs...",
  "token_type": "Bearer",
  "expires_in": 3600,
  "refresh_token": "dGhpcyBpcyBhIHJlZnJlc2ggdG9rZW4..."
}

API Endpoints

Circuits

GET
/circuits

List all circuits in your workspace.

curl https://api.fluxcore.io/v1/circuits \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "data": [
    {
      "id": "cir_abc123",
      "name": "Ring Resonator Filter",
      "created_at": "2025-01-15T10:30:00Z",
      "updated_at": "2025-01-15T14:22:00Z",
      "component_count": 12,
      "status": "draft"
    }
  ],
  "pagination": {
    "total": 42,
    "page": 1,
    "per_page": 20,
    "has_more": true
  }
}

Query Parameters

ParameterTypeDescription
pageintegerPage number (default: 1)
per_pageintegerItems per page (max: 100)
statusstringFilter by status: draft, active, archived
POST
/circuits

Create a new circuit design.

curl -X POST https://api.fluxcore.io/v1/circuits \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "MZI Switch",
    "description": "2x2 Mach-Zehnder interferometer switch",
    "wavelength": 1550e-9,
    "material_system": "silicon",
    "template": "mzi_2x2"
  }'

# Response
{
  "id": "cir_xyz789",
  "name": "MZI Switch",
  "description": "2x2 Mach-Zehnder interferometer switch",
  "created_at": "2025-01-15T16:45:00Z",
  "status": "draft",
  "settings": {
    "wavelength": 1550e-9,
    "material_system": "silicon"
  },
  "components": [],
  "connections": []
}
GET
/circuits/:id

Retrieve a specific circuit with all components and connections.

curl https://api.fluxcore.io/v1/circuits/cir_abc123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response
{
  "id": "cir_abc123",
  "name": "Ring Resonator Filter",
  "components": [
    {
      "id": "comp_1",
      "type": "ring_resonator",
      "position": {"x": 100, "y": 200},
      "parameters": {
        "radius": 10.0,
        "gap": 0.2,
        "width": 0.45
      }
    },
    {
      "id": "comp_2",
      "type": "waveguide",
      "position": {"x": 0, "y": 200},
      "parameters": {
        "length": 100,
        "width": 0.45
      }
    }
  ],
  "connections": [
    {
      "from": {"component": "comp_2", "port": "out"},
      "to": {"component": "comp_1", "port": "in"}
    }
  ]
}

Simulations

POST
/circuits/:id/simulate

Run FDTD simulation on a circuit.

curl -X POST https://api.fluxcore.io/v1/circuits/cir_abc123/simulate \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "type": "fdtd",
    "wavelength_range": {
      "start": 1500e-9,
      "end": 1600e-9,
      "points": 101
    },
    "resolution": "high",
    "compute_fields": true
  }'

# Response (async job)
{
  "job_id": "sim_job_123",
  "status": "queued",
  "estimated_time": 45,
  "created_at": "2025-01-15T17:00:00Z"
}
GET
/simulations/:job_id

Get simulation job status and results.

curl https://api.fluxcore.io/v1/simulations/sim_job_123 \
  -H "Authorization: Bearer YOUR_API_KEY"

# Response (completed)
{
  "job_id": "sim_job_123",
  "status": "completed",
  "completed_at": "2025-01-15T17:01:30Z",
  "results": {
    "s_parameters": {
      "S21": [...],
      "S11": [...],
      "wavelengths": [...]
    },
    "metrics": {
      "insertion_loss": 0.45,
      "extinction_ratio": 25.3,
      "bandwidth_3dB": 1.2e-9
    },
    "field_data_url": "https://storage.fluxcore.io/fields/sim_job_123.h5"
  }
}

AI Features

POST
/ai/sketch-to-circuit

Convert a hand-drawn sketch to a circuit design.

curl -X POST https://api.fluxcore.io/v1/ai/sketch-to-circuit \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: multipart/form-data" \
  -F "image=@sketch.jpg" \
  -F 'options={"wavelength": 1550e-9, "material": "silicon"}'

# Response
{
  "circuit_id": "cir_generated_456",
  "components": [...],
  "connections": [...],
  "confidence": 0.94,
  "recognition_details": {
    "components_found": 5,
    "connections_inferred": 4,
    "annotations_read": ["input", "output", "10um"]
  }
}
POST
/ai/predict-performance

Get AI-powered performance predictions without full simulation.

curl -X POST https://api.fluxcore.io/v1/ai/predict-performance \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"circuit_id": "cir_abc123"}'

# Response
{
  "predictions": {
    "insertion_loss": {"value": 0.5, "confidence": 0.92, "unit": "dB"},
    "bandwidth": {"value": 1.5, "confidence": 0.88, "unit": "nm"},
    "extinction_ratio": {"value": 22, "confidence": 0.85, "unit": "dB"}
  },
  "optimization_suggestions": [
    {
      "component": "comp_1",
      "parameter": "gap",
      "suggestion": "Reduce gap from 0.2um to 0.15um for better coupling",
      "predicted_improvement": {"insertion_loss": -0.1}
    }
  ]
}

Error Handling

Error Response Format

All errors follow a consistent format with error code, message, and optional details.

{
  "error": {
    "code": "validation_error",
    "message": "Invalid circuit configuration",
    "details": {
      "field": "components[0].parameters.radius",
      "reason": "Radius must be greater than minimum bend radius (5um)"
    }
  },
  "request_id": "req_abc123"
}

HTTP Status Codes

CodeMeaning
200Success
201Created
400Bad Request - Invalid parameters
401Unauthorized - Invalid or missing API key
403Forbidden - Insufficient permissions
404Not Found - Resource doesn't exist
429Rate Limited - Too many requests
500Server Error - Contact support

Rate Limits

API requests are rate limited based on your subscription tier.

TierRequests/minSimulation jobs/day
Free6010
Professional300100
Enterprise1000Unlimited

Rate limit headers are included in all responses: X-RateLimit-Limit,X-RateLimit-Remaining, X-RateLimit-Reset

Next Steps

SDK & Libraries

Related Guides