{ "openapi": "3.1.0", "info": { "title": "spaceemit electron emission API", "version": "0.1.0", "description": "Thermal-field electron emission from metal and semiconductor surfaces: current density, Nottingham heat, energy spectra, barrier, transmission and I–V fitting. Energies in eV with the vacuum level at the surface = 0 and the Fermi level at −W; spectrum and transmission energies are relative to E_F. See docs/emission-api.md. Deprecation policy: APIs are versioned in the URL path (/v1). Breaking changes introduce a new major version. Sunset and Deprecation headers are signaled 90 days before retirement.", "x-versioning-policy": "URL path versioning (/v1). Deprecations announced via Sunset and Deprecation headers with 90-day grace period." }, "servers": [ { "url": "http://localhost:8741" } ], "paths": { "/health": { "get": { "summary": "Liveness", "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "type": "object", "properties": { "status": { "type": "string", "const": "ok" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "operationId": "getHealth" } }, "/v1/info": { "get": { "summary": "Version, defaults, units, endpoints, models and citations", "responses": { "200": { "description": "Service description", "content": { "application/json": { "schema": { "type": "object" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" } }, "operationId": "getServiceInfo" } }, "/v1/emission": { "post": { "summary": "Batch current density and Nottingham heat", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissionRequest" } } } }, "responses": { "200": { "description": "Columnar results; failed points are null and listed in errors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EmissionResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "$ref": "#/components/responses/Error" } }, "operationId": "computeEmission" } }, "/v1/spectra": { "post": { "summary": "Total, normal and parallel energy distributions of one point", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Point" }, { "type": "object", "properties": { "points": { "type": "integer", "minimum": 8, "default": 256, "description": "Samples per distribution" } } } ] } } } }, "responses": { "200": { "description": "Spectra", "content": { "application/json": { "schema": { "type": "object", "properties": { "currentDensity": { "type": "number", "description": "A/nm^2" }, "nottinghamHeat": { "type": "number", "description": "W/nm^2" }, "totalEnergyDistribution": { "$ref": "#/components/schemas/Distribution" }, "normalEnergyDistribution": { "$ref": "#/components/schemas/Distribution" }, "parallelEnergyDistribution": { "$ref": "#/components/schemas/Distribution" }, "sumRules": { "type": "array", "items": { "type": "number" }, "description": "Integral of each distribution divided by J (total, normal, parallel)" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "$ref": "#/components/responses/Error" } }, "operationId": "computeEnergySpectra" } }, "/v1/barrier": { "post": { "summary": "Barrier potential profile and top", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["field"], "properties": { "field": { "type": "number", "description": "V/nm" }, "radius": { "type": ["number", "null"], "description": "nm; null = planar" }, "gamma": { "type": "number", "default": 10 }, "distance": { "type": "array", "items": { "type": "number" }, "description": "nm" }, "points": { "type": "integer", "description": "Log-spaced samples from 0.05 nm to maxDistance" }, "maxDistance": { "type": "number", "description": "nm" } } } } } }, "responses": { "200": { "description": "Barrier", "content": { "application/json": { "schema": { "type": "object", "properties": { "distance": { "type": "array", "items": { "type": "number" } }, "potential": { "type": "array", "items": { "type": "number" }, "description": "eV relative to the vacuum level" }, "topDistance": { "type": "number", "description": "nm" }, "topPotential": { "type": "number", "description": "eV relative to the vacuum level" }, "topHbarOmega": { "type": "number", "description": "eV" } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "$ref": "#/components/responses/Error" } }, "operationId": "computeBarrier" } }, "/v1/transmission": { "post": { "summary": "Transmission probability vs normal energy for one point", "requestBody": { "required": true, "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Point" }, { "type": "object", "properties": { "energy": { "oneOf": [ { "type": "number" }, { "type": "array", "items": { "type": "number" } } ], "description": "Normal energy relative to E_F (eV)" }, "points": { "type": "integer", "default": 101, "description": "Evenly spaced energies from max(E_F - 3 eV, band bottom) to barrier top + 1 eV" }, "parallelEnergy": { "type": "number", "default": 0, "description": "eV" } } } ] } } } }, "responses": { "200": { "description": "Transmission", "content": { "application/json": { "schema": { "type": "object", "properties": { "energy": { "type": "array", "items": { "type": "number" } }, "transmission": { "type": "array", "items": { "type": "number" } }, "logTransmission": { "type": "array", "items": { "type": "number" } }, "gamow": { "type": "array", "items": { "type": "number" } }, "kemble": { "type": "array", "items": { "type": "number" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "$ref": "#/components/responses/Error" } }, "operationId": "computeTransmission" } }, "/v1/iv-fit": { "post": { "summary": "Fit measured I–V data", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": ["voltage", "current", "workFunction"], "properties": { "voltage": { "type": "array", "items": { "type": "number" }, "description": "V" }, "current": { "type": "array", "items": { "type": "number" }, "description": "A" }, "workFunction": { "type": "number" }, "radius": { "type": ["number", "null"] }, "gamma": { "type": "number" }, "temperature": { "type": "number" }, "effectiveMass": { "type": "number" }, "bandDepth": { "type": "number" }, "fit": { "type": "array", "items": { "type": "string", "enum": ["radius", "gamma", "workFunction", "temperature"] }, "description": "Extra parameters to fit (beta and area are always fitted)" }, "initialBeta": { "type": "number", "description": "Starting beta (1/nm); default from a Fowler-Nordheim plot" }, "maxIterations": { "type": "integer", "default": 60 }, "bounds": { "type": "object", "description": "Any subset; missing entries keep their defaults", "additionalProperties": false, "properties": { "beta": { "$ref": "#/components/schemas/Range" }, "radius": { "$ref": "#/components/schemas/Range" }, "gamma": { "$ref": "#/components/schemas/Range" }, "workFunction": { "$ref": "#/components/schemas/Range" }, "temperature": { "$ref": "#/components/schemas/Range" } } }, "options": { "$ref": "#/components/schemas/Options" } } } } } }, "responses": { "200": { "description": "Fit result", "content": { "application/json": { "schema": { "type": "object", "properties": { "converged": { "type": "boolean" }, "iterations": { "type": "integer" }, "rmsLogResidual": { "type": "number" }, "beta": { "$ref": "#/components/schemas/Estimate" }, "area": { "$ref": "#/components/schemas/Estimate" }, "radius": { "$ref": "#/components/schemas/Estimate" }, "gamma": { "$ref": "#/components/schemas/Estimate" }, "workFunction": { "$ref": "#/components/schemas/Estimate" }, "temperature": { "$ref": "#/components/schemas/Estimate" }, "voltage": { "type": "array", "items": { "type": "number" } }, "current": { "type": "array", "items": { "type": "number" } }, "field": { "type": "array", "items": { "type": "number" } }, "fittedCurrent": { "type": "array", "items": { "type": "number" } } } } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "500": { "$ref": "#/components/responses/InternalServerError" }, "default": { "$ref": "#/components/responses/Error" } }, "operationId": "fitCurrentVoltage" } } }, "components": { "schemas": { "Range": { "type": "array", "items": { "type": "number" }, "minItems": 2, "maxItems": 2, "description": "[lower, upper]" }, "NumOrArray": { "oneOf": [ { "type": "number" }, { "type": "array", "items": { "type": "number" } } ] }, "Options": { "type": "object", "properties": { "mode": { "type": "string", "enum": ["exact", "wkb"], "default": "exact" }, "tolerance": { "type": "number", "default": 0.000001 } } }, "Point": { "type": "object", "required": ["field", "workFunction"], "properties": { "field": { "type": "number", "description": "Local field (V/nm)" }, "radius": { "type": ["number", "null"], "description": "Radius of curvature (nm); null = planar" }, "gamma": { "type": "number", "default": 10 }, "workFunction": { "type": "number", "description": "eV" }, "temperature": { "type": "number", "default": 300, "description": "K" }, "effectiveMass": { "type": "number", "default": 1, "description": "m_e" }, "bandDepth": { "type": "number", "default": 10, "description": "eV" }, "options": { "$ref": "#/components/schemas/Options" } } }, "EmissionRequest": { "type": "object", "required": ["field", "workFunction"], "properties": { "field": { "$ref": "#/components/schemas/NumOrArray" }, "radius": { "oneOf": [ { "type": "number" }, { "type": "null" }, { "type": "array", "items": { "type": "number" } } ], "description": "nm; omit or null for planar" }, "gamma": { "$ref": "#/components/schemas/NumOrArray" }, "workFunction": { "$ref": "#/components/schemas/NumOrArray" }, "temperature": { "$ref": "#/components/schemas/NumOrArray" }, "effectiveMass": { "$ref": "#/components/schemas/NumOrArray" }, "bandDepth": { "$ref": "#/components/schemas/NumOrArray" }, "options": { "$ref": "#/components/schemas/Options" } } }, "EmissionResponse": { "type": "object", "properties": { "count": { "type": "integer" }, "currentDensity": { "type": "array", "items": { "type": ["number", "null"] }, "description": "A/nm^2" }, "nottinghamHeat": { "type": "array", "items": { "type": ["number", "null"] }, "description": "W/nm^2; negative = emitter heated" }, "meanEnergy": { "type": "array", "items": { "type": ["number", "null"] }, "description": "eV relative to E_F" }, "barrierTop": { "type": "array", "items": { "type": ["number", "null"] }, "description": "eV relative to E_F" }, "regime": { "type": "array", "items": { "type": ["string", "null"], "enum": ["field", "intermediate", "thermionic", null] } }, "errors": { "type": "array", "items": { "$ref": "#/components/schemas/PointError" } }, "elapsedMs": { "type": "number" } } }, "PointError": { "type": "object", "properties": { "index": { "type": "integer" }, "code": { "type": "string" }, "message": { "type": "string" } } }, "Distribution": { "type": "object", "properties": { "energy": { "type": "array", "items": { "type": "number" }, "description": "eV (relative to E_F; parallel energy >= 0)" }, "value": { "type": "array", "items": { "type": "number" }, "description": "A/nm^2/eV" } } }, "Estimate": { "type": "object", "properties": { "value": { "type": "number" }, "sigma": { "type": "number", "description": "One standard deviation; 0 if held fixed" } } }, "Error": { "type": "object", "properties": { "error": { "type": "object", "properties": { "code": { "type": "string", "enum": [ "invalid_json", "invalid_request", "invalid_parameter", "no_barrier", "length_mismatch", "fit_failed", "payload_too_large", "batch_too_large", "not_found" ] }, "message": { "type": "string" } } } } }, "ProblemDetails": { "type": "object", "required": ["type", "title", "status"], "properties": { "type": { "type": "string", "format": "uri", "example": "about:blank" }, "title": { "type": "string", "example": "Bad Request" }, "status": { "type": "integer", "example": 400 }, "detail": { "type": "string", "example": "Invalid parameter value provided." }, "code": { "type": "string", "example": "invalid_parameter" } } } }, "responses": { "Error": { "description": "Request-level error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "BadRequest": { "description": "Bad Request / Parameter Validation Failure (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } }, "InternalServerError": { "description": "Internal Server Error (RFC 9457)", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } }, "application/json": { "schema": { "$ref": "#/components/schemas/ProblemDetails" } } } } } } }