API Reference

v1 · REST · JSON · HTTPS only

The Criticality Engine API provides programmatic access to percolation screening, curve generation, and run history. All requests are POST to a single endpoint with a JSON body specifying the action.

Base URL

https://criticalityengine.com/api/index.php

API access requires a Team plan subscription. API Keys can be generated from your account settings.

Authentication

All API requests must include your API key in the X-Api-Key header. API keys start with arxe_ and are shown only once at creation time.

Request headers

Content-Type: application/json
X-Api-Key: arxe_your_api_key_here

cURL example

curl -X POST https://criticalityengine.com/api/index.php \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: arxe_your_api_key_here" \
  -d '{"action":"ping"}'

Python

import requests

API_URL = "https://criticalityengine.com/api/index.php"
API_KEY = "arxe_your_api_key_here"
HEADERS = {
    "Content-Type": "application/json",
    "X-Api-Key": API_KEY,
}

def ce_request(action, **params):
    payload = {"action": action, **params}
    r = requests.post(API_URL, json=payload, headers=HEADERS)
    r.raise_for_status()
    return r.json()

# Example
result = ce_request("screen", system="percolation_3d")
print(result)

JavaScript / Node.js

const CE_URL = 'https://criticalityengine.com/api/index.php';
const CE_KEY = 'arxe_your_api_key_here';

async function ceRequest(action, params = {}) {
  const res = await fetch(CE_URL, {
    method: 'POST',
    headers: {
      'Content-Type': 'application/json',
      'X-Api-Key': CE_KEY,
    },
    body: JSON.stringify({ action, ...params }),
  });
  return res.json();
}

// Example
const result = await ceRequest('screen', { system: 'percolation_3d' });
console.log(result);

Errors

All responses include an ok boolean. On error, ok is false and error contains a human-readable message.

Error response

{
  "ok": false,
  "error": "System not available on your plan",
  "upgrade": true,   // present when a plan upgrade is needed
  "_ms": 12.4
}

HTTP status	Meaning
200	Always returned — check `ok` field for logical errors
500	Server-side PHP error — contact support

Rate limits

API requests count toward your plan's monthly run quota. Team plan has unlimited runs. Authentication failures are rate-limited to 10 attempts per 5 minutes per IP.

ping

POST action: "ping" Health check — no auth required

Returns server status, PHP version, and component availability. Useful for verifying connectivity before running jobs.

Response

{
  "ok": true,
  "php": "8.2.0",
  "runs": true,
  "paypal": true,
  "db": true,
  "engine": "loaded",
  "_ms": 8.2
}

systems

POST action: "systems" List available systems

Returns all physical systems and their availability for your plan.

Response

{
  "ok": true,
  "systems": {
    "percolation_3d": {
      "label": "Percolation 3D",
      "subtitle": "Composites, CNT/polymer, hydrogels",
      "prop_label": "Conductivity σ (S/m)",
      "validated": true,
      "locked": false
    },
    // ...
  }
}

screen ProTeam

POST action: "screen" Run a screening calculation

Runs a full percolation screening for the specified system. Counts toward your monthly run quota.

Parameter	Type	Description	Required
system	string	System key — see available systems	required

Request

{
  "action": "screen",
  "system": "percolation_3d"
}

Response

{
  "ok": true,
  "result": {
    "label":       "Percolation 3D",
    "scaling_law": "σ(p) = σ₀·(p−p_c)^γ",
    "p_c":         0.0000,
    "sigma_0":     1.0,
    "exponents": {
      "nu":    { "symbol": "ν", "value": 0.8774, "name": "Correlation", "viable": true },
      "gamma": { "symbol": "γ", "value": 1.7933, "name": "Susceptibility", "viable": true },
      "beta":  { "symbol": "β", "value": 0.4181, "name": "Order", "viable": true }
    },
    "_ms": 42.1
  },
  "_ms": 43.5
}

curve ProTeam

POST action: "curve" Generate conductivity curve

Generates a σ(p) curve over a concentration range and optionally finds the optimal concentration for a target property value.

Parameter	Type	Description	Required
system	string	System key	required
p_c	float	Percolation threshold (vol fraction). Default: `0.015`	optional
sigma0	float	Prefactor σ₀ (S/m). Default: `1.0`	optional
p_min	float	Scan start concentration. Default: `p_c`	optional
p_max	float	Scan end concentration. Default: `p_c × 5`	optional
target	float	Target σ value (S/m). If set, returns optimal p. Default: none	optional

Request

{
  "action":  "curve",
  "system":  "percolation_3d",
  "p_c":     0.015,
  "sigma0":  1.0,
  "p_min":   0.015,
  "p_max":   0.12,
  "target":  0.5
}

Response

{
  "ok": true,
  "curve": [
    { "p": 0.015, "y": 0.000 },
    { "p": 0.020, "y": 0.031 },
    // ... N points
  ],
  "p_opt": 0.048,   // null if no target was specified
  "_ms": 18.3
}

history ProTeam

POST action: "history" Retrieve past runs

Returns paginated run history. Retention period depends on your plan: 90 days (Pro), 365 days (Team).

Parameter	Type	Description	Required
limit	int	Results per page. Default: `20`, max: `100`	optional
offset	int	Pagination offset. Default: `0`	optional

Response

{
  "ok": true,
  "runs": [
    {
      "id":          "uuid",
      "system_key":  "percolation_3d",
      "params":      "{...}",
      "result":      "{...}",
      "exec_ms":     42.1,
      "created_at":  "2026-04-25 14:32:00"
    }
  ],
  "total": 47,
  "_ms": 9.1
}

me

POST action: "me" Get current user info

Returns account details, plan info, and current usage counters.

Response

{
  "ok": true,
  "user": {
    "id":          "uuid",
    "email":       "user@domain.com",
    "name":        "Name",
    "tier":        "team",
    "tier_label":  "Team",
    "runs_used":   12,
    "runs_limit":  -1,   // -1 = unlimited
    "runs_left":   -1,
    "systems":     ["percolation_3d", "ising_3d", "percolation_2d", "o2_3d"],
    "exports":     ["csv", "pdf", "xml", "json"],
    "api_access":  true,
    "history_days": 365
  }
}

create_api_key Team

POST action: "create_api_key" Generate a new API key

The full key is shown only once in the response. Store it securely — it cannot be retrieved later.

Parameter	Type	Description	Required
label	string	Human-readable name for this key. Default: `"API Key"`	optional

Response

{
  "ok":     true,
  "key":    "arxe_a1b2c3d4...",   // full key — save this
  "prefix": "arxe_a1b",
  "note":   "Store this key — it is not shown again"
}

list_api_keys Team

POST action: "list_api_keys" List all API keys

Returns all active and inactive keys for your account. Full key values are never returned — only the prefix.

revoke_api_key Team

POST action: "revoke_api_key" Deactivate an API key

Parameter	Type	Description	Required
key_id	string	UUID of the key to revoke (from list_api_keys)	required

Available systems

system key	Label	Application
percolation_3d	Percolation 3D	Composites, CNT/polymer, hydrogels
ising_3d	Ising 3D / SU(2)	Bulk ferromagnets, QCD lattice
percolation_2d	Percolation 2D	Planar networks, conductive paper, membranes
o2_3d	O(2) 3D Superfluids	He-4 λ-point, type-II superconductors

Systems marked as locked in the systems endpoint require a higher plan tier.