Denspath API
Discover conservation laws, governing equations, and invariant relationships from your data via a simple REST API.
Quickstart
1. Get your API key
Generate your free API key and set your LLM provider (OpenAI, Claude, Gemini, or Grok).
2. Upload your data
Prepare a CSV with your observations. For conservation mode, provide before/after state pairs (even rows = before, odd rows = after). For regression, provide data points with a target variable.
import requests
resp = requests.post(
"https://api.denspath.com/api/jobs/upload-csv",
headers={"X-API-Key": "lf_your_key"},
files={"file": open("collisions.csv")},
data={"mode": "conservation"}
)
job = resp.json()
print(job["job_id"]) # → "abc-123"3. Poll for results
Discovery runs asynchronously. Poll the job endpoint until status is completed.
import time
while True:
result = requests.get(
f"https://api.denspath.com/api/jobs/{job['job_id']}",
headers={"X-API-Key": "lf_your_key"}
).json()
if result["status"] == "completed":
break
time.sleep(2)
# Discovered laws
for inv in result["theory"]["invariants"]:
print(f"{inv['name']}: {inv['symbolic_form']}")
# → momentum: m1*v1 + m2*v2
# → energy: 0.5*m1*v1**2 + 0.5*m2*v2**24. Use discovered laws
Predict outcomes, check impossibilities, or run the agent for deeper analysis.
# Predict: "Given these initial conditions, what happens?"
resp = requests.post(
"https://api.denspath.com/api/predict/",
headers={"X-API-Key": "lf_your_key"},
json={
"theory_id": result["theory"]["id"],
"initial_state": {"m1": 1.0, "v1": 5.0, "m2": 2.0, "v2": 0.0},
"intervention": {"v1": 1.0}
}
)
print(resp.json()["predicted_state"])
# → {"m1": 1.0, "v1": 1.0, "m2": 2.0, "v2": 2.0}Authentication
All API requests require an X-API-Key header with your Denspath API key.
curl -X GET https://api.denspath.com/api/jobs/ \ -H "X-API-Key: lf_your_key_here"
Rate limits: Free tier allows 100 requests/hour. Rate limit info is returned in X-RateLimit-Limit and X-RateLimit-Remaining headers.
Discovery Modes
Conservation Mode
Discovers quantities that remain constant across state transitions. Your CSV must have an even number of rows — each consecutive pair represents (before, after) observations.
Example: elastic collisions → discovers momentum & energy conservation
Regression Mode
Discovers y = f(x) relationships. Provide data points with a designated target_variable.
Example: planetary orbits → discovers Kepler's third law
API Endpoints
/api/jobs/upload-csvUpload a CSV file and start an async discovery job.
Params: file (CSV), mode (conservation|regression), target_variable (regression only), use_llm, use_templates
/api/jobs/{job_id}Get the status and results of a discovery job.
Params: job_id (path)
/api/jobs/List all your discovery jobs with pagination.
Params: skip, limit
/api/discover/Run discovery synchronously on inline observations.
Params: observations, variable_names, mode, domain
/api/predict/Predict outcomes using discovered theories.
Params: theory_id, initial_state, intervention
/api/predict/impossibilityExplain why a state transition is impossible given known laws.
Params: theory_id, proposed_state
/api/simulate/Run a physics simulation with given parameters.
Params: system_type, initial_conditions, time_steps
/api/agent/startStart the autonomous discovery agent on a problem.
Params: observations, config
/api/agent/stopStop a running agent.
Params: None
/api/agent/statusGet current agent status and discovered theories.
Params: None
Interactive docs: The backend serves Swagger UI at /docs when running locally. Start the backend and visit http://localhost:8000/docs for interactive API exploration with try-it-out.
CSV Format
Conservation mode
Rows are paired: row 1 & 2 form observation 1, row 3 & 4 form observation 2, etc.
m1,v1,m2,v2 1.0,5.0,2.0,0.0 1.0,1.0,2.0,2.0 3.0,2.0,1.0,-1.0 3.0,0.5,1.0,3.5
Regression mode
Standard tabular data. Specify target_variable in the upload request.
period,semi_major_axis 0.241,0.387 0.615,0.723 1.0,1.0 1.88,1.524 11.86,5.203