API Documentation

The Infoton API provides programmatic access to the Thermodynamic Controllability Calculator. Compute the controllability metric 𝓜 for any reactor configuration using the full 12-module derivation — from Landauer energy through infoton particle physics.

Version

Current API version: v1. All endpoints are stable and backward-compatible.

Authentication

All requests require a Bearer token in the Authorization header. API keys are available from your Dashboard.

Header

Authorization: Bearer inf_prod_sk_7Xm9kL2pQ4vR8nT1wF6jB3hY...

Keep Keys Secret

Never expose API keys in client-side code or public repositories. Use environment variables and server-side requests.

Base URL

https://api.infoton.ai/v1

All endpoints are relative to this base. HTTPS is required for all requests.

Rate Limits

Plan	Requests / Minute	Requests / Month	Max Batch Size
Research ($50/mo)	—	0 (web calculator only)	—
Commercial ($2,500/mo)	10	50	500 configs
Government	Custom	Custom	Up to 10,000

Rate limit headers are included in every response: X-RateLimit-Remaining, X-RateLimit-Reset.

Research Plan

Research licenses provide access to the web-based calculator only. API access requires a Commercial or Government license.

Controllability

Compute the controllability metric 𝓜 for a single reactor configuration. The engine runs the full 12-module derivation: Landauer energy, Braginskii spatial grid, bit rate, Landauer floor, three-tier overhead, controllability metric, Carnot correction, infoton particle physics, and information confinement.

POST /controllability

Request Body

Parameter	Type	Required	Description
`temperature`	number	Yes	Operating temperature in Kelvin (1 – 10¹²)
`power_output_w`	number	Yes	Thermal power output in Watts (1 – 10³⁰)
`confinement_m`	number	No	Confinement dimension in meters. Default: 6
`magnetic_field_t`	number	No	Magnetic field strength in Tesla (0 – 100). Determines grid resolution via gyroradius.
`energy_confinement_s`	number	No	Energy confinement time in seconds (0 – 10¹⁶)
`update_frequency_hz`	number	No	Control update frequency in Hz (1 – 10¹⁵). Default: 10⁶
`T_blanket`	number	No	Blanket / coolant temperature in K (100 – 10,000). Used for Carnot correction.
`T_cold`	number	No	Cold reservoir temperature in K. Default: 300
`turbine_eff`	number	No	Turbine efficiency factor (0 – 1). Applied to Carnot electrical output.
`regime`	string	No	Grid resolution basis: `"ion"`, `"electron"`, or `"multi"` (default). Selects gyroradius scale.

Legacy Parameters

For backward compatibility, you can also pass grid_resolution_m, ops_per_cell, and overhead_factor directly. These override the engine's physics-based derivation.

Example Request

curl

curl -X POST https://api.infoton.ai/v1/controllability \
  -H "Authorization: Bearer inf_prod_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "temperature": 1.5e8,
    "power_output_w": 5e8,
    "confinement_m": 6,
    "magnetic_field_t": 5.3,
    "energy_confinement_s": 3.7,
    "update_frequency_hz": 1e6,
    "T_blanket": 1000,
    "turbine_eff": 0.40,
    "regime": "ion"
  }'

Response Fields

Field	Type	Description
Core Result
`metric`	number	Controllability metric 𝓜 (conservative, α=10³)
`status`	string	Verdict: `"controllable"`, `"economically_impossible"`, `"practically_impossible"`, or `"thermodynamically_impossible"`
`computation_ms`	number	Server computation time in milliseconds
Landauer Energy (Module 3)
`E_bit`	number	Landauer energy per bit operation (J): k_BT ln 2
Spatial Grid (Module 4)
`rho_e`	number	Electron gyroradius (m)
`rho_i`	number	Ion gyroradius (m)
`dx`	number	Grid resolution (m)
`cellsPerDim`	number	Grid cells per dimension
`N_cells`	number	Total grid cells (3D)
Bit Rate (Module 5)
`ops_total`	number	Binary operations per cell per update
`N_dot`	number	Total bit rate (bits/s)
Landauer Floor (Module 6)
`P_landauer`	number	Theoretical minimum dissipation (W)
Three-Tier Overhead (Module 7)
`P_control_conservative`	number	Control power at α = 10³ (W)
`P_control_realistic`	number	Control power at α = 10⁶ (W)
`P_control_current`	number	Control power at α = 10⁹ (W)
Controllability vs Thermal (Module 8)
`M_conservative`	number	𝓜 at α = 10³ (conservative)
`M_realistic`	number	𝓜 at α = 10⁶ (realistic)
`M_current`	number	𝓜 at α = 10⁹ (current technology)
`verdict_conservative`	object	`{ status, class, code }` — see status values below
Carnot Correction vs Electrical (Module 9)
`eta_carnot`	number	Carnot efficiency
`P_electrical`	number	Usable electrical output (W)
`M_electrical`	number	𝓜 vs electrical output at α = 10³
`M_electrical_realistic`	number	𝓜 vs electrical at α = 10⁶
`M_electrical_current`	number	𝓜 vs electrical at α = 10⁹
Infoton Particle Physics (Module 10)
`m_infoton`	number	Infoton mass m(T) (kg): k_BT ln 2 / c²
`v_infoton`	number	Infoton thermal velocity (m/s)
`rho_infoton`	number	Infoton gyroradius (m)
Information Confinement (Module 11)
`tau_info`	number	Information confinement time (s)
`tau_ratio`	number	τ_E / τ_info ratio

Example Response

200 OK

{
  "metric": 5.92e-5,
  "status": "controllable",
  "E_bit": 2.87e-15,
  "rho_e": 3.19e-5,
  "rho_i": 2.88e-3,
  "dx": 2.88e-3,
  "N_cells": 9.01e9,
  "N_dot": 1.35e18,
  "P_landauer": 3.87e3,
  "P_control_conservative": 3.87e6,
  "P_control_realistic": 3.87e9,
  "P_control_current": 3.87e12,
  "M_conservative": 5.92e-5,
  "M_realistic": 5.92e-2,
  "M_current": 5.92e1,
  "verdict_conservative": {
    "status": "CONTROLLABLE",
    "class": "safe",
    "code": "ok"
  },
  "eta_carnot": 0.998,
  "P_electrical": 1.99e8,
  "M_electrical": 1.48e-4,
  "m_infoton": 3.19e-32,
  "v_infoton": 2.51e8,
  "tau_info": 1.15e-11,
  "tau_ratio": 3.23e11,
  "computation_ms": 2
}

Batch Analysis

Submit multiple configurations in a single request. Small batches (≤50 configs) return results synchronously. Larger batches return a job ID for polling.

POST /batch

Request Body

json

{
  "configurations": [
    {
      "name": "ITER",
      "temperature": 1.5e8,
      "power_output_w": 5e8,
      "confinement_m": 6,
      "magnetic_field_t": 5.3,
      "energy_confinement_s": 3.7,
      "T_blanket": 1000,
      "turbine_eff": 0.40
    },
    // ... up to 500 configurations (Commercial)
  ]
}

Batches ≤50 configurations return results synchronously. For batches over 50, the API returns a job_id. Poll GET /batch/{job_id} for results.

GET /batch/{job_id}

GET /batch

List all batch jobs for the authenticated user.

Presets

Manage saved reactor configurations.

GET /presets

POST /presets

GET /presets/{preset_id}

DELETE /presets/{preset_id}

Reports

Generate and retrieve CSV reports programmatically. Each report contains the full 12-module derivation trace.

POST /reports

GET /reports

GET /reports/{report_id}

GET /reports/{report_id}/download

DELETE /reports/{report_id}

Generate a Report

Request

curl -X POST https://api.infoton.ai/v1/reports \
  -H "Authorization: Bearer inf_prod_sk_..." \
  -H "Content-Type: application/json" \
  -d '{
    "type": "single",
    "title": "ITER Analysis",
    "configuration": {
      "temperature": 1.5e8,
      "power_output_w": 5e8,
      "confinement_m": 6,
      "magnetic_field_t": 5.3,
      "energy_confinement_s": 3.7,
      "T_blanket": 1000,
      "turbine_eff": 0.40
    }
  }'

Parameter Reference

Parameter	Unit	Range	Default	Notes
`temperature`	K	1 – 10¹²	—	Required. Fission ~600 K, Fusion ~10⁸ K
`power_output_w`	W	1 – 10³⁰	—	Required. Thermal output
`confinement_m`	m	10⁻⁶ – 10⁹	6	Characteristic confinement length
`magnetic_field_t`	T	0 – 100	—	Determines gyroradius → grid resolution
`energy_confinement_s`	s	0 – 10¹⁶	—	For τ_E / τ_info confinement ratio
`update_frequency_hz`	Hz	1 – 10¹⁵	10⁶	MHz for ion scale, GHz for electron
`T_blanket`	K	100 – 10,000	—	Hot reservoir for Carnot correction
`T_cold`	K	1 – 5,000	300	Cold reservoir temperature
`turbine_eff`	—	0 – 1	—	Applied to Carnot electrical output
`regime`	—	—	"multi"	`"ion"`, `"electron"`, or `"multi"`

Legacy Override Parameters

These bypass the physics-based derivation. Useful when you want to specify exact values rather than have the engine derive them from plasma parameters.

Parameter	Range	Notes
`grid_resolution_m`	10⁻¹² – 10³	Overrides gyroradius-derived grid spacing
`ops_per_cell`	1 – 10¹⁰	Overrides Braginskii state variable count
`overhead_factor`	1 – 10¹²	Overrides three-tier α, recomputes 𝓜

Response Format

All responses are JSON. The engine returns the full 12-module derivation. The status field maps to one of four verdict levels based on 𝓜 (conservative, α = 10³):

𝓜 Range	Status	Verdict
𝓜 < 0.01	`"controllable"`	CONTROLLABLE
0.01 ≤ 𝓜 < 0.1	`"economically_impossible"`	ECONOMICALLY IMPOSSIBLE
0.1 ≤ 𝓜 < 1	`"practically_impossible"`	PRACTICALLY IMPOSSIBLE
𝓜 ≥ 1	`"thermodynamically_impossible"`	THERMODYNAMICALLY IMPOSSIBLE

The verdict_conservative object includes status (display string), class ("safe", "warn", or "critical"), and code ("ok", "economic", "practical", or "thermo").

Error Codes

Status	Code	Description
400	invalid_parameters	Missing required parameter or value out of range.
401	unauthorized	Missing or invalid API key.
403	forbidden	Your plan does not include API access (e.g. Research tier).
404	not_found	The requested resource does not exist.
429	rate_limited	Too many requests. Check `X-RateLimit-Reset` header.
500	internal_error	Server error. Contact January@infoton.ai if persistent.

Error Response Format

400 Bad Request

{
  "error": {
    "code": "invalid_parameters",
    "message": "Parameter temperature out of range: -500 (valid: 1–1000000000000)"
  }
}

Code Examples

Python

python

import requests

response = requests.post(
    "https://api.infoton.ai/v1/controllability",
    headers={"Authorization": f"Bearer {API_KEY}"},
    json={
        "temperature": 1.5e8,
        "power_output_w": 5e8,
        "confinement_m": 6,
        "magnetic_field_t": 5.3,
        "energy_confinement_s": 3.7,
        "T_blanket": 1000,
        "turbine_eff": 0.40,
    }
)

data = response.json()
print(f"𝓜 = {data['metric']} — {data['status']}")
print(f"Landauer floor: {data['P_landauer']:.2e} W")
print(f"Infoton mass:   {data['m_infoton']:.2e} kg")

JavaScript

javascript

const response = await fetch("https://api.infoton.ai/v1/controllability", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${API_KEY}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    temperature: 1.5e8,
    power_output_w: 5e8,
    confinement_m: 6,
    magnetic_field_t: 5.3,
    energy_confinement_s: 3.7,
    T_blanket: 1000,
    turbine_eff: 0.40,
  }),
});

const data = await response.json();
console.log(`𝓜 = ${data.metric} — ${data.status}`);
console.log(`Three-tier: ${data.P_control_conservative.toExponential(2)} W (α=1e3)`);
console.log(`Infoton: ${data.m_infoton.toExponential(2)} kg`);