API explorer (live)
Try the Algenta HTTP API live — set your key and base URL, then send real requests to every endpoint from the browser.
Every endpoint below renders live from the Algenta OpenAPI specification. Expand an operation to see parameters, request and response schemas, and example payloads, then use Test it to call the API directly from this page with your own key.
Account
GET /v1/api-keys
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/api-keys HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"label": "text",
"key_prefix": "text",
"device_limit": 1,
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"last_used_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z"
}
]POST /v1/api-keys
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Returned once at key creation — raw key shown here only.
Max registered devices for this key on the local runtime path. 0 preserves the plan's unlimited or no-local-runtime behavior.
The full API key — shown ONCE, store it securely.
Validation Error
POST /v1/api-keys HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 73
{
"label": "text",
"expires_at": "2026-01-01T00:00:00.000Z",
"device_limit": 1
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"label": "text",
"key_prefix": "text",
"device_limit": 1,
"raw_key": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"expires_at": "2026-01-01T00:00:00.000Z"
}DELETE /v1/api-keys/{key_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
No content
Validation Error
DELETE /v1/api-keys/{key_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
GET /v1/distributions
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/distributions HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"name": "text",
"description": "text",
"required_params": [
"text"
],
"optional_params": [
"text"
],
"example": {}
}
]GET /v1/limits
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/limits HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"plan": "text",
"max_simulations_per_month": 1,
"max_runs_per_simulation": 1,
"max_batch_items": 1,
"rate_limit_per_minute": 1,
"async_jobs_enabled": true,
"webhooks_enabled": true
}GET /v1/me
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/me HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"user": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "text",
"name": "text",
"role": "text",
"email_verified": true,
"created_at": "2026-01-01T00:00:00.000Z"
},
"org": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"slug": "text",
"plan": "text",
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}
}PATCH /v1/me
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
PATCH /v1/me HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 33
{
"name": "text",
"org_name": "text"
}{
"user": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"email": "text",
"name": "text",
"role": "text",
"email_verified": true,
"created_at": "2026-01-01T00:00:00.000Z"
},
"org": {
"id": "123e4567-e89b-12d3-a456-426614174000",
"name": "text",
"slug": "text",
"plan": "text",
"status": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}
}POST /v1/products/{product}/onboard
GET /v1/products/{product}/whoami
GET /v1/provider-keys
POST /v1/provider-keys
DELETE /v1/provider-keys/{backend}
POST /v1/telys/onboard
GET /v1/templates
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/templates HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "text",
"name": "text",
"description": "text",
"category": "text",
"example_request": {}
}
]GET /v1/usage
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/usage HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"billing_period": "text",
"simulations_run": 1,
"api_calls": 1,
"quota_limit": 1,
"quota_used_pct": 1
}Agent Runtime
POST /v1/agent/runs
GET /v1/agent/runs
GET /v1/agent/runs/checkpoints
GET /v1/agent/runs/mission-events
GET /v1/agent/runs/telemetry
GET /v1/agent/runs/{run_id}
POST /v1/agent/runs/{run_id}/approve
POST /v1/agent/runs/{run_id}/cancel
GET /v1/agent/runs/{run_id}/checkpoints
GET /v1/agent/runs/{run_id}/events
POST /v1/agent/runs/{run_id}/fork
GET /v1/agent/runs/{run_id}/mission-events
POST /v1/agent/runs/{run_id}/replay
POST /v1/agent/runs/{run_id}/resume
GET /v1/agent/runs/{run_id}/telemetry
Async Jobs
POST /v1/jobs
Submit a large simulation to run asynchronously. Returns a job_id immediately. Poll /v1/jobs/{job_id} for status. Provide a callback_url to receive a webhook when complete.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Request to submit an async simulation job.
URL to POST when the job completes. Must be HTTPS in production.
Successful Response
Returned immediately on job submission.
Job queued. Poll the poll_url for status updates.Validation Error
POST /v1/jobs HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 260
{
"request": {
"mode": "auto",
"runs": 10000,
"scenario": {
"name": "Product launch decision",
"objective": "maximize_net_value",
"variables": {
"cost": {
"high": 90000,
"low": 40000
},
"revenue": {
"high": 200000,
"low": 80000
}
}
},
"simulation_model": "monte_carlo"
},
"callback_url": "text"
}{
"job_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "text",
"poll_url": "text",
"message": "Job queued. Poll the poll_url for status updates."
}GET /v1/jobs/list
Paginated list of all jobs for the authenticated org.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
125Successful Response
Validation Error
GET /v1/jobs/list HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}GET /v1/jobs/{job_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Job status returned by poll endpoint.
Validation Error
GET /v1/jobs/{job_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"job_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "text",
"queue_name": "text",
"retry_count": 1,
"callback_url": "text",
"callback_status": "text",
"error_message": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"ttl_expires_at": "2026-01-01T00:00:00.000Z",
"poll_url": "text"
}POST /v1/jobs/{job_id}/cancel
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Job status returned by poll endpoint.
Validation Error
POST /v1/jobs/{job_id}/cancel HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"job_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "text",
"queue_name": "text",
"retry_count": 1,
"callback_url": "text",
"callback_status": "text",
"error_message": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"started_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"ttl_expires_at": "2026-01-01T00:00:00.000Z",
"poll_url": "text"
}GET /v1/jobs/{job_id}/result
Returns the full result if completed, or 202 with status if still processing.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/jobs/{job_id}/result HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}POST /v1/webhooks/test
Send a test webhook payload to a URL and return the delivery result.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
URL to send test webhook to
Successful Response
Validation Error
POST /v1/webhooks/test HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 23
{
"callback_url": "text"
}{
"success": true,
"status_code": 1,
"message": "text"
}Auth
POST /v1/auth/forgot-password
POST /v1/auth/login
POST /v1/auth/reset-password
POST /v1/auth/signup
GET /v1/auth/verify
BYOK
GET /v1/byok
POST /v1/byok
DELETE /v1/byok
Billing
POST /v1/billing/checkout
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
POST /v1/billing/checkout HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{}GET /v1/billing/info
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/billing/info HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{}GET /v1/billing/plans
POST /v1/billing/portal
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
POST /v1/billing/portal HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{}Calibration
GET /v1/calibration
Returns the org's historical prediction accuracy metrics computed from all recorded outcomes (PATCH /v1/decisions/{id}/outcome). The confidence_multiplier is applied automatically to every simulation and recommendation once n_samples >= 5.
Key fields
bias: mean relative error — negative means over-optimistichit_rate: fraction of predictions within ±20% of actualconfidence_multiplier: factor currently applied to raw simulation confidenceis_reliable: false until 5+ outcomes are recorded
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Org-level confidence calibration state.
GET /v1/calibration HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"org_id": "text",
"is_reliable": true,
"n_samples": 1,
"bias": 1,
"rmse_pct": 1,
"hit_rate": 1,
"direction": "text",
"confidence_multiplier": 1,
"summary": "text",
"last_updated": "text"
}Capability Plane
GET /v1/capabilities
POST /v1/capabilities/execute
POST /v1/capabilities/outcomes
POST /v1/capabilities/route
GET /v1/capabilities/{capability_id}
GET /v1/capability-bindings
POST /v1/capability-bindings
POST /v1/capability-bindings/discover
POST /v1/capability-bindings/test
GET /v1/capability-bindings/{binding_id}
PATCH /v1/capability-bindings/{binding_id}
DELETE /v1/capability-bindings/{binding_id}
POST /v1/capability-bindings/{binding_id}/authorize/complete
POST /v1/capability-bindings/{binding_id}/authorize/start
POST /v1/capability-bindings/{binding_id}/discover
POST /v1/capability-bindings/{binding_id}/test
POST /v1/capability-executions/{plan_id}/approve
GET /v1/capability-providers
GET /v1/capability-providers/{provider_id}
Data
GET /v1/data
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
1falseSuccessful Response
Validation Error
GET /v1/data HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}POST /v1/data/connect
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
database | api | object_storage | file_upload
Public dataset name.
Specific provider such as postgres, snowflake, s3, rest.
Canonical connector envelope with type/location/auth/options. Preferred for cross-SDK and MCP compatibility.
Reuse an existing saved connection.
Optional saved connection label.
Connector credentials/config.
Chosen table/query/path.
private | shared
Successful Response
Validation Error
POST /v1/data/connect HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 307
{
"connection_type": "text",
"dataset_name": "text",
"provider": "text",
"connector": {},
"connection_id": "text",
"connection_name": "text",
"connection_config": {},
"selection": {},
"description": "text",
"visibility": "text",
"records": [
{}
],
"csv": "text",
"json_str": "text",
"url": "text",
"excel_b64": "text",
"parquet_b64": "text"
}{}GET /v1/data/{dataset_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/data/{dataset_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}DELETE /v1/data/{dataset_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
DELETE /v1/data/{dataset_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}POST /v1/data/{dataset_id}/refresh
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/data/{dataset_id}/refresh HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}GET /v1/data/{dataset_id}/summary
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/data/{dataset_id}/summary HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Data Connectors
GET /v1/connectors
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/connectors HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
[
{
"id": "text",
"name": "text",
"description": "text",
"connector_type": "text",
"status": "text",
"visibility": "text",
"last_tested_at": "2026-01-01T00:00:00.000Z",
"error_message": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}
]POST /v1/connectors
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/connectors HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 92
{
"name": "text",
"connector_type": "text",
"description": "text",
"visibility": "text",
"config": {}
}{
"id": "text",
"name": "text",
"description": "text",
"connector_type": "text",
"status": "text",
"visibility": "text",
"last_tested_at": "2026-01-01T00:00:00.000Z",
"error_message": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}POST /v1/connectors/browse
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/connectors/browse HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"connector_type": "text",
"config": {}
}{
"connector_type": "text",
"items": [
{}
],
"total": 1,
"message": "text",
"labels": {},
"discovery": {}
}POST /v1/connectors/test
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/connectors/test HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 37
{
"connector_type": "text",
"config": {}
}{
"success": true,
"message": "text",
"latency_ms": 1,
"status": "text",
"error_type": "text",
"recoverable": true
}GET /v1/connectors/types
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/connectors/types HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
}GET /v1/connectors/{connector_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/connectors/{connector_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "text",
"name": "text",
"description": "text",
"connector_type": "text",
"status": "text",
"visibility": "text",
"last_tested_at": "2026-01-01T00:00:00.000Z",
"error_message": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}PATCH /v1/connectors/{connector_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
PATCH /v1/connectors/{connector_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 68
{
"name": "text",
"description": "text",
"visibility": "text",
"config": {}
}{
"id": "text",
"name": "text",
"description": "text",
"connector_type": "text",
"status": "text",
"visibility": "text",
"last_tested_at": "2026-01-01T00:00:00.000Z",
"error_message": "text",
"created_at": "2026-01-01T00:00:00.000Z"
}DELETE /v1/connectors/{connector_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
No content
Validation Error
DELETE /v1/connectors/{connector_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
GET /v1/connectors/{connector_id}/browse
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/connectors/{connector_id}/browse HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"connector_type": "text",
"items": [
{}
],
"total": 1,
"message": "text",
"labels": {},
"discovery": {}
}POST /v1/connectors/{connector_id}/test
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/connectors/{connector_id}/test HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"success": true,
"message": "text",
"latency_ms": 1,
"status": "text",
"error_type": "text",
"recoverable": true
}Data Mapping
POST /v1/map
Connect and understand any dataset instantly.
Drop in CSV files, JSON records, or table names from multiple sources. Get back a unified schema with every field mapped, explained, and ready to run decisions on.
What it detects:
Matching fields across sources (revenue ↔ sales, qty ↔ quantity)
Value distributions (lognormal for prices, triangular for ranges)
Polarity (cost → negative, revenue → positive)
Join keys between tables (background if slow)
Derived formulas A×B≈C (background if slow)
Confidence and plain-English reasoning for every mapping
Two-speed pipeline: Phase 1 (schema + column matches) returns in <300ms. Phase 2 (join detection + relation detection) is embedded in the response if it finishes within 200ms, otherwise deep_analysis_pending: true is set and results can be retrieved via GET /v1/map/{map_id}.
The data funnel: Upload → Map → Query → Decide → Optimize
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Drop in any data sources. Get back semantic field mappings and a unified schema.
No configuration required. The engine auto-detects:
- Which fields represent the same concept across sources
- Distribution shapes for numeric fields
- Polarity (revenue → positive, cost → negative)
- Primary/foreign keys for joins
- Confidence and reasoning for every mapping
Minimum confidence threshold for mappings (default: 0.5)
0.5Include value distribution statistics in response
trueSuccessful Response
falseValidation Error
POST /v1/map HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 245
{
"sources": [
{
"name": "text",
"dataset_id": "text",
"source_id": "text",
"records": [
{}
],
"csv": "text",
"json_str": "text",
"url": "text",
"excel_b64": "text",
"parquet_b64": "text",
"connection": {},
"table": "text"
}
],
"min_confidence": 0.5,
"include_statistics": true
}{
"map_id": "text",
"sources_analyzed": 1,
"total_fields": 1,
"mappings": [
{
"source_field": "text",
"source": "text",
"target_field": "text",
"target": "text",
"confidence": 1,
"reason": [
"text"
],
"match_type": "text"
}
],
"unified_schema": [
{
"name": "text",
"sources": [
"text"
],
"distribution": "text",
"unit": "text",
"polarity": 1,
"sample_values": []
}
],
"join_keys": [
{}
],
"derived_relationships": [
{}
],
"simulation_ready": true,
"simulation_payload": {},
"deep_analysis_pending": false,
"latency_ms": 1
}GET /v1/map/{map_id}
When POST /v1/map returns deep_analysis_pending: true, poll this endpoint with the map_id to retrieve join keys, derived relationships, and the simulation payload once Phase 2 analysis completes.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/map/{map_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Datasets
GET /v1/datasets
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
1falseSuccessful Response
Validation Error
GET /v1/datasets HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}POST /v1/datasets/onboard
Drop in data → instantly queryable.
Accepts JSON records, inline CSV, or column names only
Profiles schema and role-classifies every column automatically
Auto-suggests domain aliases (PPA → per/person/average, etc.)
Fires background semantic training immediately when the training runtime is installed
Returns model tier — queries work immediately via base/deterministic fallback
For file uploads (CSV, Excel, Parquet, JSON) use POST /v1/datasets/onboard/file.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Register any data source for semantic querying.
Provide data via ONE of: records — list of row dicts (JSON records) csv — raw CSV text (headers in first row) columns — list of column name strings (schema-only, no samples)
For file uploads use POST /v1/datasets/onboard/file.
Human-readable dataset name
datasetTable name used in the schema
JSON records (list of row dicts)
Raw CSV text with header row
Column names only — no data required
Fire background semantic training immediately
true8032Successful Response
Validation Error
POST /v1/datasets/onboard HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 187
{
"name": "dataset",
"source_name": "text",
"records": [
{}
],
"csv": "text",
"columns": [
"text"
],
"domain_aliases": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"async_train": true,
"epochs": 80,
"batch_size": 32
}{
"dataset_id": "text",
"name": "text",
"schema_hash": "text",
"status": "text",
"model_tier": "text",
"decision_mode": "text",
"source_names": [
"text"
],
"column_count": 1,
"domain_aliases": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"registered_at": "text",
"updated_at": "text",
"schema": {},
"suggested_aliases": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"latency_ms": 1
}POST /v1/datasets/onboard/file
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
datasettrue8032Successful Response
Validation Error
POST /v1/datasets/onboard/file HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: multipart/form-data
Accept: */*
Content-Length: 131
{
"file": "binary",
"name": "dataset",
"source_name": "text",
"domain_aliases_json": "text",
"async_train": true,
"epochs": 80,
"batch_size": 32
}{
"dataset_id": "text",
"name": "text",
"schema_hash": "text",
"status": "text",
"model_tier": "text",
"decision_mode": "text",
"source_names": [
"text"
],
"column_count": 1,
"domain_aliases": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"registered_at": "text",
"updated_at": "text",
"schema": {},
"suggested_aliases": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"latency_ms": 1
}POST /v1/datasets/{dataset_id}/retrain
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
8032Successful Response
Validation Error
POST /v1/datasets/{dataset_id}/retrain HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}GET /v1/datasets/{dataset_id}/status
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/datasets/{dataset_id}/status HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"dataset_id": "text",
"name": "text",
"schema_hash": "text",
"status": "text",
"model_tier": "text",
"decision_mode": "text",
"source_names": [
"text"
],
"column_count": 1,
"domain_aliases": {
"ANY_ADDITIONAL_PROPERTY": [
"text"
]
},
"registered_at": "text",
"updated_at": "text"
}Decision
POST /v1/batch
Submit 1–100 simulation requests. Partial failures are allowed; failed items include an error message.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Request body for /v1/batch.
Successful Response
Response from /v1/batch.
Validation Error
POST /v1/batch HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 238
{
"items": [
{
"mode": "auto",
"runs": 10000,
"scenario": {
"name": "Product launch decision",
"objective": "maximize_net_value",
"variables": {
"cost": {
"high": 90000,
"low": 40000
},
"revenue": {
"high": 200000,
"low": 80000
}
}
},
"simulation_model": "monte_carlo"
}
]
}{
"total": 1,
"succeeded": 1,
"failed": 1,
"results": [
{
"index": 1,
"success": true,
"envelope": {
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"engine_version": "text",
"recommended_action": "text",
"confidence": 1,
"rationale": "text",
"metrics": {
"expected_value": 1,
"median": 1,
"std_deviation": 1,
"variance": 1,
"probability_of_loss": 1,
"var_95": 1,
"cvar_95": 1
},
"percentiles": {
"p5": 1,
"p10": 1,
"p25": 1,
"p50": 1,
"p75": 1,
"p90": 1,
"p95": 1,
"p99": 1
},
"scenarios_run": 1,
"execution_ms": 1,
"metadata": {
"mode": "text",
"seed": 1,
"billing_units": 1,
"engine_version": "text"
},
"simulation_model": "monte_carlo",
"engine_type": "text",
"simulation_class": "predictive",
"model_revision": "text",
"assumptions_hash": "text",
"validated_inputs": {},
"confidence_interval": {},
"request_id": "text",
"scenario_analysis": {},
"sensitivity_analysis": {},
"bootstrap_result": {},
"mcmc_result": {},
"importance_sampling_result": {},
"scenario_ranking": [
{}
],
"sensitivity_ranking": [
{}
],
"score": 1,
"score_breakdown": {},
"created_at": "2026-01-01T00:00:00.000Z",
"decision_tree_result": {},
"time_series_result": {},
"formatted_result": {},
"unit_context": {},
"unit_warnings": [
"text"
],
"charts": {},
"histogram_data": {},
"decision_plan": {
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"options": [
{
"name": "text",
"rank": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"score": 1
}
],
"rationale": "text",
"integrity": {},
"calibration": "text"
},
"request_hash": "text",
"result_hash": "text"
},
"error": "text"
}
]
}POST /v1/compare
Run and compare 2–10 named scenarios. Returns full results with deltas versus the winning scenario.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Request body for /v1/compare.
10000Successful Response
Response from /v1/compare.
Validation Error
POST /v1/compare HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 290
{
"scenarios": [
{
"name": "text",
"request": {
"mode": "auto",
"runs": 10000,
"scenario": {
"name": "Product launch decision",
"objective": "maximize_net_value",
"variables": {
"cost": {
"high": 90000,
"low": 40000
},
"revenue": {
"high": 200000,
"low": 80000
}
}
},
"simulation_model": "monte_carlo"
}
}
],
"runs": 10000,
"seed": 1
}{
"winner": "text",
"margin": {
"expected_value_delta": 1,
"probability_of_loss_delta": 1,
"score_delta": 1
},
"scenarios": [
{
"name": "text",
"envelope": {
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"engine_version": "text",
"recommended_action": "text",
"confidence": 1,
"rationale": "text",
"metrics": {
"expected_value": 1,
"median": 1,
"std_deviation": 1,
"variance": 1,
"probability_of_loss": 1,
"var_95": 1,
"cvar_95": 1
},
"percentiles": {
"p5": 1,
"p10": 1,
"p25": 1,
"p50": 1,
"p75": 1,
"p90": 1,
"p95": 1,
"p99": 1
},
"scenarios_run": 1,
"execution_ms": 1,
"metadata": {
"mode": "text",
"seed": 1,
"billing_units": 1,
"engine_version": "text"
},
"simulation_model": "monte_carlo",
"engine_type": "text",
"simulation_class": "predictive",
"model_revision": "text",
"assumptions_hash": "text",
"validated_inputs": {},
"confidence_interval": {},
"request_id": "text",
"scenario_analysis": {},
"sensitivity_analysis": {},
"bootstrap_result": {},
"mcmc_result": {},
"importance_sampling_result": {},
"scenario_ranking": [
{}
],
"sensitivity_ranking": [
{}
],
"score": 1,
"score_breakdown": {},
"created_at": "2026-01-01T00:00:00.000Z",
"decision_tree_result": {},
"time_series_result": {},
"formatted_result": {},
"unit_context": {},
"unit_warnings": [
"text"
],
"charts": {},
"histogram_data": {},
"decision_plan": {
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"options": [
{
"name": "text",
"rank": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"score": 1
}
],
"rationale": "text",
"integrity": {},
"calibration": "text"
},
"request_hash": "text",
"result_hash": "text"
},
"delta_vs_best": {
"expected_value_delta": 1,
"probability_of_loss_delta": 1,
"score_delta": 1
}
}
]
}POST /v1/recommend
Run simulations for 2–10 named actions and return them ranked by expected value. The top-ranked action is returned as recommended_action.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Request body for /v1/recommend — compare 2-10 named actions.
10000Successful Response
Response from /v1/recommend.
Validation Error
POST /v1/recommend HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 330
{
"actions": [
{
"name": "launch_product_a",
"request": {
"mode": "auto",
"scenario": {
"objective": "maximize_net_value",
"variables": {
"revenue": {
"high": 200000,
"low": 80000
}
}
}
}
},
{
"name": "launch_product_b",
"request": {
"mode": "auto",
"scenario": {
"objective": "maximize_net_value",
"variables": {
"revenue": {
"high": 300000,
"low": 50000
}
}
}
}
}
],
"runs": 10000
}{
"recommended_action": "text",
"confidence": 1,
"rationale": "text",
"action_results": [
{
"name": "text",
"rank": 1,
"envelope": {
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"engine_version": "text",
"recommended_action": "text",
"confidence": 1,
"rationale": "text",
"metrics": {
"expected_value": 1,
"median": 1,
"std_deviation": 1,
"variance": 1,
"probability_of_loss": 1,
"var_95": 1,
"cvar_95": 1
},
"percentiles": {
"p5": 1,
"p10": 1,
"p25": 1,
"p50": 1,
"p75": 1,
"p90": 1,
"p95": 1,
"p99": 1
},
"scenarios_run": 1,
"execution_ms": 1,
"metadata": {
"mode": "text",
"seed": 1,
"billing_units": 1,
"engine_version": "text"
},
"simulation_model": "monte_carlo",
"engine_type": "text",
"simulation_class": "predictive",
"model_revision": "text",
"assumptions_hash": "text",
"validated_inputs": {},
"confidence_interval": {},
"request_id": "text",
"scenario_analysis": {},
"sensitivity_analysis": {},
"bootstrap_result": {},
"mcmc_result": {},
"importance_sampling_result": {},
"scenario_ranking": [
{}
],
"sensitivity_ranking": [
{}
],
"score": 1,
"score_breakdown": {},
"created_at": "2026-01-01T00:00:00.000Z",
"decision_tree_result": {},
"time_series_result": {},
"formatted_result": {},
"unit_context": {},
"unit_warnings": [
"text"
],
"charts": {},
"histogram_data": {},
"decision_plan": {
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"options": [
{
"name": "text",
"rank": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"score": 1
}
],
"rationale": "text",
"integrity": {},
"calibration": "text"
},
"request_hash": "text",
"result_hash": "text"
},
"expected_value": 1,
"probability_of_loss": 1,
"score": 1
}
],
"total_actions": 1,
"decision_plan": {
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"options": [
{
"name": "text",
"rank": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"score": 1
}
],
"rationale": "text",
"integrity": {},
"calibration": "text"
}
}POST /v1/score
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Request body for /v1/score.
Successful Response
Response from /v1/score — DecisionEnvelope with score breakdown.
Validation Error
POST /v1/score HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 286
{
"request": {
"mode": "auto",
"runs": 10000,
"scenario": {
"name": "Product launch decision",
"objective": "maximize_net_value",
"variables": {
"cost": {
"high": 90000,
"low": 40000
},
"revenue": {
"high": 200000,
"low": 80000
}
}
},
"simulation_model": "monte_carlo"
},
"scoring_weights": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}{
"envelope": {
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"engine_version": "text",
"recommended_action": "text",
"confidence": 1,
"rationale": "text",
"metrics": {
"expected_value": 1,
"median": 1,
"std_deviation": 1,
"variance": 1,
"probability_of_loss": 1,
"var_95": 1,
"cvar_95": 1
},
"percentiles": {
"p5": 1,
"p10": 1,
"p25": 1,
"p50": 1,
"p75": 1,
"p90": 1,
"p95": 1,
"p99": 1
},
"scenarios_run": 1,
"execution_ms": 1,
"metadata": {
"mode": "text",
"seed": 1,
"billing_units": 1,
"engine_version": "text"
},
"simulation_model": "monte_carlo",
"engine_type": "text",
"simulation_class": "predictive",
"model_revision": "text",
"assumptions_hash": "text",
"validated_inputs": {},
"confidence_interval": {},
"request_id": "text",
"scenario_analysis": {},
"sensitivity_analysis": {},
"bootstrap_result": {},
"mcmc_result": {},
"importance_sampling_result": {},
"scenario_ranking": [
{}
],
"sensitivity_ranking": [
{}
],
"score": 1,
"score_breakdown": {},
"created_at": "2026-01-01T00:00:00.000Z",
"decision_tree_result": {},
"time_series_result": {},
"formatted_result": {},
"unit_context": {},
"unit_warnings": [
"text"
],
"charts": {},
"histogram_data": {},
"decision_plan": {
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"options": [
{
"name": "text",
"rank": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"score": 1
}
],
"rationale": "text",
"integrity": {},
"calibration": "text"
},
"request_hash": "text",
"result_hash": "text"
},
"score": 1,
"score_breakdown": {
"ANY_ADDITIONAL_PROPERTY": 1
}
}Decision Memory
POST /v1/decisions
Record a decision that was made. Link it to a simulation run_id to bind the full DecisionPlan context. Call PATCH /outcome later to close the loop.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Body for POST /v1/decisions — log a decision that was made.
ID of the simulation run that produced this decision (links DecisionPlan -> DecisionLog).
Free-text description of the business situation when this decision was made.
The action that was chosen.
All option names that were evaluated before choosing.
Probability of loss at decision time
Successful Response
Single decision log entry.
Validation Error
POST /v1/decisions HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 253
{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"context": "text",
"chosen_action": "text",
"options_considered": [
"text"
],
"expected_value": 1,
"confidence": 1,
"rationale": "text",
"risk_p5": 1,
"risk_p95": 1,
"risk_pol": 1,
"request_hash": "text",
"result_hash": "text"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"context": "text",
"chosen_action": "text",
"options_considered": [
"text"
],
"expected_value": 1,
"confidence": 1,
"rationale": "text",
"risk_p5": 1,
"risk_p95": 1,
"risk_pol": 1,
"request_hash": "text",
"result_hash": "text",
"actual_outcome": 1,
"outcome_delta": 1,
"outcome_notes": "text",
"outcome_recorded_at": "2026-01-01T00:00:00.000Z",
"executed_at": "2026-01-01T00:00:00.000Z",
"execution_status": "text",
"execution_webhook_url": "text",
"execution_response_code": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}GET /v1/decisions
Returns the org's decision history, most recent first. Supports pagination.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
1Legacy compatibility alias for limit.
When true, return only decisions where actual_outcome has been recorded.
falseSuccessful Response
Validation Error
GET /v1/decisions HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"decisions": [
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"context": "text",
"chosen_action": "text",
"options_considered": [
"text"
],
"expected_value": 1,
"confidence": 1,
"rationale": "text",
"risk_p5": 1,
"risk_p95": 1,
"risk_pol": 1,
"request_hash": "text",
"result_hash": "text",
"actual_outcome": 1,
"outcome_delta": 1,
"outcome_notes": "text",
"outcome_recorded_at": "2026-01-01T00:00:00.000Z",
"executed_at": "2026-01-01T00:00:00.000Z",
"execution_status": "text",
"execution_webhook_url": "text",
"execution_response_code": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}
],
"total": 1,
"page": 1,
"limit": 1,
"pages": 1,
"page_size": 1
}POST /v1/decisions/plan
GET /v1/decisions/{decision_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Single decision log entry.
Validation Error
GET /v1/decisions/{decision_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"id": "123e4567-e89b-12d3-a456-426614174000",
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"context": "text",
"chosen_action": "text",
"options_considered": [
"text"
],
"expected_value": 1,
"confidence": 1,
"rationale": "text",
"risk_p5": 1,
"risk_p95": 1,
"risk_pol": 1,
"request_hash": "text",
"result_hash": "text",
"actual_outcome": 1,
"outcome_delta": 1,
"outcome_notes": "text",
"outcome_recorded_at": "2026-01-01T00:00:00.000Z",
"executed_at": "2026-01-01T00:00:00.000Z",
"execution_status": "text",
"execution_webhook_url": "text",
"execution_response_code": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}DELETE /v1/decisions/{decision_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
No content
Validation Error
DELETE /v1/decisions/{decision_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
POST /v1/decisions/{decision_id}/execute
Fire the decision to an external webhook URL, turning the logged decision into an automated action. The webhook receives the full decision context (chosen action, expected value, confidence, risk profile, integrity hashes). Execution status and the HTTP response code are persisted back to the decision log for full audit trail. Re-execution is allowed — each call overwrites the prior receipt.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Body for POST /v1/decisions/{id}/execute — fire the decision to a webhook.
HTTPS endpoint that will receive and act on this decision.
Webhook request timeout in seconds.
10Override the idempotency gate. Pass true to re-execute a decision that was already delivered. Does NOT override confidence or risk_floor gates.
falseBypass confidence and risk_floor policy gates for this single execution. Requires explicit intent. Logs the override for audit.
falseOptional extra key-value pairs merged into the webhook payload.
Successful Response
Returned by POST /v1/decisions/{id}/execute.
falseValidation Error
POST /v1/decisions/{decision_id}/execute HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 95
{
"webhook_url": "text",
"timeout_seconds": 10,
"force": false,
"override_safety": false,
"metadata": {}
}{
"decision_id": "123e4567-e89b-12d3-a456-426614174000",
"webhook_url": "text",
"execution_status": "text",
"response_code": 1,
"executed_at": "2026-01-01T00:00:00.000Z",
"payload_summary": {},
"safety_overridden": false
}PATCH /v1/decisions/{decision_id}/outcome
Close the feedback loop: record what actually happened after the decision was made. Sets actual_outcome, computes outcome_delta = actual - expected, and timestamps the recording.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Body for PATCH /v1/decisions/{id}/outcome — close the feedback loop.
Observed outcome value (e.g. actual monthly revenue).
Successful Response
Single decision log entry.
Validation Error
PATCH /v1/decisions/{decision_id}/outcome HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"actual_outcome": 1,
"outcome_notes": "text"
}{
"id": "123e4567-e89b-12d3-a456-426614174000",
"org_id": "123e4567-e89b-12d3-a456-426614174000",
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"context": "text",
"chosen_action": "text",
"options_considered": [
"text"
],
"expected_value": 1,
"confidence": 1,
"rationale": "text",
"risk_p5": 1,
"risk_p95": 1,
"risk_pol": 1,
"request_hash": "text",
"result_hash": "text",
"actual_outcome": 1,
"outcome_delta": 1,
"outcome_notes": "text",
"outcome_recorded_at": "2026-01-01T00:00:00.000Z",
"executed_at": "2026-01-01T00:00:00.000Z",
"execution_status": "text",
"execution_webhook_url": "text",
"execution_response_code": 1,
"created_at": "2026-01-01T00:00:00.000Z",
"updated_at": "2026-01-01T00:00:00.000Z"
}Decision Workflow
GET /v1/analysis-runs/{run_id}
POST /v1/analysis-runs/{run_id}/action-plans
GET /v1/analysis-runs/{run_id}/evidence
GET /v1/analysis-runs/{run_id}/result
POST /v1/decision-cases
PUT /v1/decision-cases/{case_id}
GET /v1/decision-cases/{case_id}
POST /v1/decision-cases/{case_id}/analysis-runs
POST /v1/decision-cases/{case_id}/outcomes
POST /v1/decision-cases/{case_id}/refresh
POST /v1/decision-plans/{plan_id}/approve
POST /v1/decision-plans/{plan_id}/execute
Deployments
GET /v1/deployments
Return the active deployment for this org, or None if using shared pool.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/deployments HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"deployment_id": "text",
"org_id": "text",
"provider": "text",
"region": "text",
"status": "text",
"endpoint_url": "text",
"cost_usd_month": 1,
"billable_cost_usd_month": 1,
"billing_markup_pct": 1,
"created_at": "text",
"provisioned_at": "text",
"error_message": "text"
}POST /v1/deployments
Provision an isolated engine deployment on your chosen cloud provider and region. Returns 202 Accepted immediately — provisioning is async (typically 3-5 minutes). Poll GET /v1/deployments to check status. When status=active, all API calls are automatically routed to your isolated deployment. Requires owner role.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Cloud provider: algenta_shared, aws, azure, gcp
algenta_sharedCloud region identifier. Use /v1/deployments/regions to list options.
algenta-sharedOptional provider-specific configuration. Supported keys: instance_size (e.g. 'small'|'medium'|'large'), storage_gb, max_concurrent_runs, auto_scale_max.
Pass-through cost markup percentage. Default: 20%.
20Successful Response
Validation Error
POST /v1/deployments HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 91
{
"provider": "algenta_shared",
"region": "algenta-shared",
"config": {},
"billing_markup_pct": 20
}{
"deployment_id": "text",
"org_id": "text",
"provider": "text",
"region": "text",
"status": "text",
"endpoint_url": "text",
"cost_usd_month": 1,
"billable_cost_usd_month": 1,
"billing_markup_pct": 1,
"created_at": "text",
"provisioned_at": "text",
"error_message": "text"
}GET /v1/deployments/regions
Returns all available cloud providers and their supported regions. Regions are fetched live from cloud SDKs when credentials are available, otherwise returns a comprehensive static fallback list. Use the region id field when creating a deployment.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/deployments/regions HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{}DELETE /v1/deployments/{deployment_id}
Tear down cloud resources for a deployment. Org will revert to shared pool. Requires owner role.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
DELETE /v1/deployments/{deployment_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"ANY_ADDITIONAL_PROPERTY": "text"
}GET /v1/deployments/{deployment_id}/cost
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/deployments/{deployment_id}/cost HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Engines
GET /v1/engines
Return the full Algenta engine catalogue.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
125Successful Response
Authentication required
Validation Error
GET /v1/engines HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"count": 1,
"total": 1,
"page": 1,
"limit": 1,
"pages": 1,
"engines": [
{
"name": "text",
"slug": "text",
"description": "text",
"api_path": "text",
"mojo_libs": [
"text"
],
"use_cases": [
"text"
],
"tier": "text"
}
]
}GET /v1/engines/tiers
Return engines grouped by tier: core / advanced / platform.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Authentication required
GET /v1/engines/tiers HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"core": [
{
"name": "text",
"slug": "text",
"description": "text",
"api_path": "text",
"mojo_libs": [
"text"
],
"use_cases": [
"text"
],
"tier": "text"
}
],
"advanced": [
{
"name": "text",
"slug": "text",
"description": "text",
"api_path": "text",
"mojo_libs": [
"text"
],
"use_cases": [
"text"
],
"tier": "text"
}
],
"platform": [
{
"name": "text",
"slug": "text",
"description": "text",
"api_path": "text",
"mojo_libs": [
"text"
],
"use_cases": [
"text"
],
"tier": "text"
}
]
}GET /v1/engines/{slug}
Return detail for a single engine by slug.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Authentication required
Validation Error
GET /v1/engines/{slug} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"name": "text",
"slug": "text",
"description": "text",
"api_path": "text",
"mojo_libs": [
"text"
],
"use_cases": [
"text"
],
"tier": "text"
}Execution Policy
GET /v1/execution/policy
Returns the org's current autonomous execution safety policy. Gates applied to every POST /v1/decisions/{id}/execute call and trigger auto_execute:
min_confidence: decisions below this confidence are blocked
risk_floor: decisions where worst-case (p5) exceeds this loss are blocked
require_calibration: auto_execute waits for ≥5 recorded outcomes
allow_reexecution: idempotency — prevents double-actions
All gates can be bypassed individually: force=true (idempotency) or override_safety=true (confidence + risk_floor).
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Current execution policy for the calling org.
GET /v1/execution/policy HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"org_id": "text",
"min_confidence": 1,
"risk_floor": 1,
"require_calibration": true,
"allow_reexecution": true,
"updated_at": "text"
}PATCH /v1/execution/policy
Partial update — only supplied fields are changed. Changes take effect immediately for all subsequent executions. Audit logs record every update.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Partial update — only supplied fields are changed.
Minimum confidence to allow execution (0–1). Default: 0.5.
Maximum tolerable downside loss (absolute). If p5 < -risk_floor the execution is blocked. Set to null to disable the check.
When true, trigger auto_execute is disabled until the org has ≥5 recorded outcomes. Manual execution is always allowed.
When true, already-executed decisions can fire again without force=true.
Successful Response
Current execution policy for the calling org.
Validation Error
PATCH /v1/execution/policy HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 87
{
"min_confidence": 1,
"risk_floor": 1,
"require_calibration": true,
"allow_reexecution": true
}{
"org_id": "text",
"min_confidence": 1,
"risk_floor": 1,
"require_calibration": true,
"allow_reexecution": true,
"updated_at": "text"
}GET /v1/execution/policy/snapshots
Export
GET /v1/runs/{run_id}/export.{fmt}
Export a simulation run in the requested format.
csv
text/csv
stdlib — always available
xlsx
application/vnd.openxmlformats-officedocument.spreadsheetml.sheet
openpyxl
pdf
application/pdf
fpdf2
json
application/json
stdlib — always available
If the optional dependency is not installed the endpoint returns 503.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Simulation run UUID
Export format: csv | xlsx | pdf | json
Export file bytes
Unsupported format
Run not found
Validation Error
Export dependency not installed
GET /v1/runs/{run_id}/export.{fmt} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Infrastructure
GET /v1/infrastructure
Return real engine health status and compute node information.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
binaryGET /v1/infrastructure HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{
"deployment_mode": "text",
"engine_version": "text",
"api_version": "text",
"nodes": [
{
"node_id": "text",
"status": "text",
"engine_version": "text",
"cpu_pct": 1,
"memory_gb": 1,
"jobs_per_sec": 1,
"region": "text",
"last_heartbeat": "2026-01-01T00:00:00.000Z"
}
],
"probe_latency_ms": 1,
"uptime_30d_pct": 1,
"avg_latency_ms": 1,
"p95_latency_ms": 1,
"throughput_rpm": 1,
"last_health_check": "2026-01-01T00:00:00.000Z",
"engine_mode": "binary"
}POST /v1/nodes/heartbeat
Update node status and metrics. Call every 30s from worker nodes.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
liveSuccessful Response
Validation Error
POST /v1/nodes/heartbeat HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 77
{
"node_id": "text",
"cpu_pct": 1,
"memory_gb": 1,
"jobs_per_sec": 1,
"status": "live"
}{}POST /v1/nodes/register
Called by self-hosted Algenta workers on startup to register with the API. The node will appear in GET /v1/infrastructure for the org.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
localSuccessful Response
Validation Error
POST /v1/nodes/register HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 111
{
"node_id": "text",
"region": "local",
"engine_version": "text",
"cpu_count": 1,
"memory_gb": 1,
"capabilities": [
"text"
]
}{
"node_id": "text",
"registered_at": "text",
"message": "text"
}DELETE /v1/nodes/{node_id}
Gracefully deregister a self-hosted worker node.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
No content
Validation Error
DELETE /v1/nodes/{node_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Ingest
POST /v1/ingest
Drop in your data. Get back a ready-to-run simulation.
Paste CSV text or send JSON records
Multiple tables: auto-detects join keys and merges
Auto-detects distributions, polarity, units, and objective function
Selects the best simulation engine for your data shape
Set
auto_run: trueto get simulation results immediately
Powered by the Algenta FieldMapper — same logic as field_mapper.mojo.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Drop in your data. Get back a ready-to-run simulation.
Supports:
- Single table: records or CSV text
- Multiple tables: auto-detects join keys, merges, then analyzes
No configuration required. The engine auto-detects everything.
Optional domain hint (finance, supply_chain, hr, etc.) for better field mapping
""Scenarios to evaluate
10000If true, run the simulation immediately and return results
falseSuccessful Response
Validation Error
POST /v1/ingest HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 144
{
"tables": [
{
"name": "table",
"records": [
{}
],
"csv": "text"
}
],
"domain": "",
"runs": 10000,
"auto_run": false,
"join_on": {
"ANY_ADDITIONAL_PROPERTY": "text"
}
}{
"ingest_id": "text",
"records_analyzed": 1,
"fields_detected": 1,
"join_applied": true,
"join_key": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"variables": [
{}
],
"objective_function": "text",
"engine": "text",
"engine_reason": "text",
"field_analysis": {},
"simulation_payload": {},
"simulation_result": {},
"latency_ms": 1
}LLM API
POST /v1/artifacts/resolve
POST /v1/chat/completions
POST /v1/count_tokens
POST /v1/embeddings
POST /v1/embeddings/similarity
GET /v1/models
POST /v1/rerank
POST /v1/responses
POST /v1/tokenize
Logs
GET /v1/logs
SSE stream of API log events.
Query params:
node_id: filter by compute node ID
level: filter by log level (info, warning, error)
Connect with: const es = new EventSource('/v1/logs', { headers: { Authorization: 'Bearer sk_...' } })
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/logs HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Playground
POST /v1/playground
No sign-up. No API key. Just try it.
Run a decision analysis, optimization, simulation, or forecast in one API call. Rate limited at 10 requests/minute per IP.
Upgrade at algenta.ai for:
500 simulations/month free
Up to 1,000,000 scenarios per request
All 12 engines
Describe what you want to analyze. No statistics knowledge required.
Modes: decision → What should I do? Returns proceed/pause/reject + why optimize → Find the best value. Returns optimal config + improvement simulate → What's the range of outcomes? Returns distribution forecast → What will happen? Returns future periods with CI
Example: { "mode": "decision", "inputs": {"revenue": 120000, "cost": 70000}, "runs": 1000 }
What to run: decision, optimize, simulate, forecast
decisionYour input variables as name → value (or name → {value, low, high})
What to optimize (for optimize mode): 'maximize profit', 'minimize cost', etc.
maximize_valueScenarios to evaluate (playground cap: 5,000 — upgrade for 1,000,000+)
1000Historical values for forecast mode (most recent last, min 3)
Successful Response
Validation Error
POST /v1/playground HTTP/1.1
Host: api.algenta.ai
Content-Type: application/json
Accept: */*
Content-Length: 86
{
"mode": "decision",
"inputs": {},
"objective": "maximize_value",
"runs": 1000,
"history": [
1
]
}{
"playground_id": "text",
"mode": "text",
"action": "text",
"value": 1,
"confidence": 1,
"why": [
"text"
],
"details": {},
"latency_ms": 1,
"upgrade_hint": "text"
}Products
POST /v1/agent/run
Give the Algenta Agent Engine a task. It breaks it down, uses tools (search, simulate, optimize, calculate), and returns a structured result.
Direct replacement for LangChain and LangGraph agent pipelines.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Give Algenta a task. It plans, executes tools, and returns a structured result.
Drop-in replacement for LangChain / LangGraph agent workflows.
What should the agent do?
Additional context or data
Tools to make available: search, simulate, optimize, calculate, summarize
Maximum execution steps
10Output format: text, json, markdown
textSuccessful Response
Validation Error
POST /v1/agent/run HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83
{
"task": "text",
"context": {},
"tools": [
"text"
],
"max_steps": 10,
"output_format": "text"
}{
"run_id": "text",
"status": "text",
"result": "text",
"steps": [
{
"step": 1,
"action": "text",
"tool": "text",
"result": "text",
"status": "completed"
}
],
"tools_used": [
"text"
],
"latency_ms": 1
}POST /v1/decision
Give Algenta your inputs and constraints. Get back the optimal action with confidence, risk, and plain-English reasoning.
Evaluates thousands of possible scenarios in milliseconds using the Algenta API — no statistics or simulation expertise required.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Ask Algenta: given these inputs and constraints, what should I do?
Algenta tests thousands of possible outcomes and returns the optimal action with confidence, risk, and reasoning — no statistics knowledge required.
What to optimize: maximize_value, minimize_risk, maximize_profit, minimize_cost
maximize_valueHow much risk is acceptable: low, medium, high
mediumHow many scenarios to evaluate (more = higher confidence)
10000Simulation engine. 'auto' (default) selects the best engine automatically based on your data shape. Options: monte_carlo, lhs, qmc_sobol, bootstrap, mcmc, importance_sampling, time_series, sensitivity
autoOptional label for this decision
Successful Response
Recommended action: proceed, pause, reject, or custom
Confidence in this recommendation (0–1)
Plain-English explanation
3 crisp reasons behind this recommendation
Expected value in your input units
Value at 5th percentile (worst-case)
Value at 95th percentile (best-case)
Probability of negative outcome
Validation Error
POST /v1/decision HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 258
{
"inputs": [
{
"high": 180000,
"low": 80000,
"name": "revenue",
"unit": "USD",
"value": 120000
},
{
"high": 100000,
"low": 50000,
"name": "cost",
"unit": "USD",
"value": 70000
}
],
"objective": "maximize_value",
"risk_tolerance": "medium",
"scenarios": 10000,
"engine": "auto",
"label": "text"
}{
"decision_id": "text",
"action": "text",
"confidence": 1,
"reasoning": "text",
"why": [
"text"
],
"expected_outcome": 1,
"downside_risk": 1,
"upside_potential": 1,
"probability_of_loss": 1,
"scenarios_evaluated": 1,
"latency_ms": 1
}POST /v1/forecast
Forecast any metric — revenue, demand, capacity — using historical data.
Combines time-series analysis with Monte Carlo uncertainty quantification. Returns point forecasts with confidence intervals for each period.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Forecast what will happen based on historical data and business drivers.
Use cases: demand forecasting, revenue projection, capacity planning.
What you're forecasting, e.g. 'monthly_revenue'
Historical values (most recent last)
How many periods ahead to forecast
12Account for seasonal patterns
trueConfidence interval width
0.9Successful Response
Most recent historical value
Expected value at end of horizon
Expected % change over horizon
Validation Error
POST /v1/forecast HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 86
{
"metric": "text",
"history": [
1
],
"horizon": 12,
"seasonality": true,
"confidence_level": 0.9
}{
"forecast_id": "text",
"metric": "text",
"baseline": 1,
"forecast_mean": 1,
"total_change_pct": 1,
"periods": [
{
"period": 1,
"forecast": 1,
"lower_bound": 1,
"upper_bound": 1,
"trend": "text"
}
],
"scenarios_evaluated": 1,
"latency_ms": 1
}POST /v1/optimize
Find the optimal value for pricing, routing, scheduling, or resource allocation.
Describe your objective and constraints in plain English — Algenta finds the best configuration across thousands of iterations.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Find the best value given inputs, constraints, and an objective.
Use cases: pricing, routing, scheduling, resource allocation. No math required — just describe what you're optimizing.
What to optimize, e.g. 'maximize profit', 'minimize cost', 'maximize throughput'
Search iterations
1000Simulation engine. 'auto' selects the best engine automatically. Options: lhs (recommended for optimization), monte_carlo, qmc_sobol
autoSuccessful Response
% improvement vs naive midpoint solution
Validation Error
POST /v1/optimize HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 177
{
"objective": "text",
"variables": [
{
"name": "text",
"min": 1,
"max": 1,
"step": 1,
"unit": "text"
}
],
"constraints": [
{
"expression": "text",
"required": true
}
],
"iterations": 1000,
"engine": "auto"
}{
"optimization_id": "text",
"status": "text",
"optimal_values": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"objective_value": 1,
"improvement_vs_midpoint": 1,
"constraints_satisfied": true,
"iterations_run": 1,
"latency_ms": 1
}POST /v1/retrieve
Search documents or a connected data source and get ranked, relevant results.
Combines BM25 keyword search, dense vector similarity, and cross-encoder reranking for enterprise-grade accuracy. No setup required — pass documents inline or connect a data source.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Search your knowledge base and get ranked, relevant results.
Plug-and-play enterprise search and RAG pipeline. Pass documents inline or reference a connected collection.
What are you looking for?
ID of a connected data source to search
Number of results to return
5Apply cross-encoder reranking for higher accuracy
trueSuccessful Response
Validation Error
POST /v1/retrieve HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 122
{
"query": "text",
"documents": [
{
"id": "text",
"content": "text",
"metadata": {}
}
],
"collection_id": "text",
"top_k": 5,
"rerank": true
}{
"retrieval_id": "text",
"query": "text",
"results": [
{
"rank": 1,
"document_id": "text",
"content": "text",
"relevance_score": 1,
"snippet": "text"
}
],
"total_searched": 1,
"latency_ms": 1
}Registry
POST /v1/registry/credentials
Repository Intelligence
GET /v1/repositories/capabilities
POST /v1/repositories/{repository_id}/apply
POST /v1/repositories/{repository_id}/decision-plans
POST /v1/repositories/{repository_id}/graph-query
POST /v1/repositories/{repository_id}/pipeline
POST /v1/repositories/{repository_id}/security-analyses
POST /v1/repositories/{repository_id}/security-analyses/closure
POST /v1/repositories/{repository_id}/simulate
POST /v1/repositories/{repository_id}/simulate-patch
POST /v1/repositories/{repository_id}/snapshots
GET /v1/repositories/{repository_id}/snapshots/{snapshot_id}
POST /v1/repositories/{repository_id}/triage
Runs
GET /v1/analytics
Return aggregated analytics using real SQL GROUP BY — O(1) in DB, not O(n) in Python.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
30Successful Response
Aggregated analytics for dashboard charts.
Validation Error
GET /v1/analytics HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"total_runs": 1,
"runs_by_day": [
{}
],
"runs_by_status": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"runs_by_mode": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"avg_duration_ms": 1,
"p95_duration_ms": 1
}GET /v1/runs
Return paginated simulation run history for the authenticated org.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
120Successful Response
Validation Error
GET /v1/runs HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"runs": [
{
"run_id": "text",
"mode": "text",
"status": "text",
"scenarios_run": 1,
"duration_ms": 1,
"result_hash": "text",
"request_hash": "text",
"execution_type": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"probability_of_loss": 1,
"std_deviation": 1,
"rationale": "text"
}
],
"total": 1,
"page": 1,
"limit": 1,
"pages": 1
}GET /v1/runs/{run_id}
Return details for a single simulation run (org-scoped).
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/runs/{run_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"run_id": "text",
"mode": "text",
"status": "text",
"scenarios_run": 1,
"duration_ms": 1,
"result_hash": "text",
"request_hash": "text",
"execution_type": "text",
"created_at": "2026-01-01T00:00:00.000Z",
"completed_at": "2026-01-01T00:00:00.000Z",
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"probability_of_loss": 1,
"std_deviation": 1,
"rationale": "text"
}Runtime Libraries
GET /v1/libraries
POST /v1/libraries/execute
GET /v1/libraries/health
Semantic Query
POST /v1/query
Structured query execution engine.
This endpoint takes structured intent — produced by an LLM from the user's natural-language question. It does NOT accept raw text.
Separation of concerns:
LLM: language → structured intent, ambiguity resolution, user interaction
Algenta: schema understanding, math relationships, fast execution, correctness
Role resolution:
Detect derived formulas across all numeric column triples (Mojo, ~100ms)
Assign structural roles: derived_measure, base_measure, unit_measure…
Match requested role → best column
Execute aggregation, return result + all candidates for LLM disambiguation
Ambiguity handling: If confidence < 0.7, check candidates — multiple columns may match the role. The LLM can present options to the user or pick the most contextually appropriate one.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Structured query execution request.
═══════════════════════════════════════════════════════════ PRIMARY PATH — Exact spec (use after reading the schema) ═══════════════════════════════════════════════════════════ The correct flow:
- Call POST /v1/sources/register or POST /v1/sources/schema
- LLM reads the returned schema (column names, roles, formulas)
- LLM sends exact column names — Mojo validates and executes
Example (top 5 customers by revenue): { "source_name": "S0", "metric_column": "measure_total", "group_column": "dimension_label", "aggregation": "sum", "limit": 5 }
For multi-hop joins: { "source_name": "S0", "metric_column": "measure_total", "group_column": "dimension_label", "join_path": { "base_source": "S0", "group_source": "S2", "edges": [ { "left_source": "S0", "right_source": "S1", "left_key": "k01_left", "right_key": "k01_right" }, { "left_source": "S1", "right_source": "S2", "left_key": "k12_left", "right_key": "k12_right" } ] }, "aggregation": "sum" }
═══════════════════════════════════════════════════════════ FALLBACK PATH — Hint spec (when schema is not yet known) ═══════════════════════════════════════════════════════════ The engine resolves source and columns from structural role hints. Use this ONLY for exploratory queries. Always migrate to exact spec once you have the schema — it is faster and never ambiguous.
Example: { "metric": {"role": "derived_measure", "hint": "total value"}, "group_by": ["segment"], "aggregation": "sum", "limit": 5 }
Public dataset ID alias for a registered source. When provided, query execution is scoped to that one registered dataset.
EXACT source name from the registry (e.g. 'Bookings'). Bypasses source resolver entirely. Get this from POST /v1/sources/schema or the registration response.
EXACT column name for the metric (e.g. 'EXT_PRICE'). Bypasses column resolver. The engine validates this column exists in source_name.
EXACT column name for group-by (e.g. 'CUSTOMER'). Bypasses group resolver. Can be in source_name or in the terminal source of join_path.
Hint mode only: dimension words from the user's question (e.g. ['customer', 'region']). Ignored when group_column is set.
[]Hint mode only: source name the LLM believes is correct. Hard-locks the source resolver. Ignored when source_name is set.
Hint mode only: when True and resolver confidence < 0.40, return null result with source candidates instead of guessing.
falseHint mode only: minimum resolver confidence threshold.
0sum | avg | count | max | min
sumTop-N limit
desc | asc
desc0.5Successful Response
[]false[][]planner_hintValidation Error
POST /v1/query HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 1786
{
"dataset_id": "text",
"source_name": "text",
"metric_column": "text",
"group_column": "text",
"join_path": {
"base_source": "text",
"group_source": "text",
"edges": [
{
"left_source": "text",
"right_source": "text",
"left_key": "text",
"right_key": "text",
"join_type": "inner",
"min_confidence": 0,
"expected_cardinality": "text",
"allow_many_to_many": false
}
],
"max_hops": 4,
"min_path_confidence": 0,
"reject_on_ambiguity": true,
"reject_on_fanout": true
},
"sources": [
{
"name": "text",
"dataset_id": "text",
"source_id": "text",
"records": [
{}
],
"csv": "text",
"json_str": "text",
"url": "text",
"excel_b64": "text",
"parquet_b64": "text",
"connection": {},
"table": "text"
}
],
"metric": {
"role": "derived_measure",
"hint": "text"
},
"group_by": [
"text"
],
"preferred_source": "text",
"reject_on_ambiguity": false,
"min_source_confidence": 0,
"aggregation": "sum",
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"min_confidence": 0.5,
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"resolved_plan": {
"source_name": "text",
"metric_column": "text",
"aggregation": "sum",
"group_column": "text",
"join_path": {
"base_source": "text",
"group_source": "text",
"edges": [
{
"left_source": "text",
"right_source": "text",
"left_key": "text",
"right_key": "text",
"join_type": "inner",
"min_confidence": 0,
"expected_cardinality": "text",
"allow_many_to_many": false
}
],
"max_hops": 4,
"min_path_confidence": 0,
"reject_on_ambiguity": true,
"reject_on_fanout": true
},
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"schema_revision": "text"
}
}{
"query_id": "text",
"result": null,
"result_type": "text",
"confidence": 1,
"plan": [
"text"
],
"resolved_column": "text",
"resolved_role": "text",
"resolved_source": "text",
"row_count": 1,
"candidates": [
{
"source": "text",
"column": "text",
"role": "text",
"magnitude": "text",
"formula": "text",
"confidence": 1,
"score_components": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"notes": [
"text"
]
}
],
"source_scores": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"ambiguous": true,
"exact_spec": true,
"explanation": [
"text"
],
"latency_ms": 1,
"decision_path": "text",
"plan_hash": "text",
"schema_revision": "text",
"validated": true,
"deterministic_scope": "text",
"confidence_source": "text",
"clarification_required": false,
"rejection_reason": "text",
"request_id": "text",
"source_set": [
"text"
],
"join_path": [
{}
],
"planner_mode": "planner_hint"
}POST /v1/query/batch
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/query/batch HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 2007
{
"defaults": {
"dataset_id": "text",
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "text"
},
"queries": [
{
"key": "text",
"request": {
"dataset_id": "text",
"source_name": "text",
"metric_column": "text",
"group_column": "text",
"join_path": {
"base_source": "text",
"group_source": "text",
"edges": [
{
"left_source": "text",
"right_source": "text",
"left_key": "text",
"right_key": "text",
"join_type": "inner",
"min_confidence": 0,
"expected_cardinality": "text",
"allow_many_to_many": false
}
],
"max_hops": 4,
"min_path_confidence": 0,
"reject_on_ambiguity": true,
"reject_on_fanout": true
},
"sources": [
{
"name": "text",
"dataset_id": "text",
"source_id": "text",
"records": [
{}
],
"csv": "text",
"json_str": "text",
"url": "text",
"excel_b64": "text",
"parquet_b64": "text",
"connection": {},
"table": "text"
}
],
"metric": {
"role": "derived_measure",
"hint": "text"
},
"group_by": [
"text"
],
"preferred_source": "text",
"reject_on_ambiguity": false,
"min_source_confidence": 0,
"aggregation": "sum",
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"min_confidence": 0.5,
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"resolved_plan": {
"source_name": "text",
"metric_column": "text",
"aggregation": "sum",
"group_column": "text",
"join_path": {
"base_source": "text",
"group_source": "text",
"edges": [
{
"left_source": "text",
"right_source": "text",
"left_key": "text",
"right_key": "text",
"join_type": "inner",
"min_confidence": 0,
"expected_cardinality": "text",
"allow_many_to_many": false
}
],
"max_hops": 4,
"min_path_confidence": 0,
"reject_on_ambiguity": true,
"reject_on_fanout": true
},
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"schema_revision": "text"
}
}
}
]
}{
"results": [
{
"key": "text",
"data": {
"query_id": "text",
"result": null,
"result_type": "text",
"confidence": 1,
"plan": [
"text"
],
"resolved_column": "text",
"resolved_role": "text",
"resolved_source": "text",
"row_count": 1,
"candidates": [
{
"source": "text",
"column": "text",
"role": "text",
"magnitude": "text",
"formula": "text",
"confidence": 1,
"score_components": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"notes": [
"text"
]
}
],
"source_scores": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"ambiguous": true,
"exact_spec": true,
"explanation": [
"text"
],
"latency_ms": 1,
"decision_path": "text",
"plan_hash": "text",
"schema_revision": "text",
"validated": true,
"deterministic_scope": "text",
"confidence_source": "text",
"clarification_required": false,
"rejection_reason": "text",
"request_id": "text",
"source_set": [
"text"
],
"join_path": [
{}
],
"planner_mode": "planner_hint"
},
"metadata": {
"request_id": "text",
"latency_ms": 1,
"tokens_in": 1,
"tokens_out": 1,
"cost_usd": 1,
"cache_hit": true
},
"error": {
"code": "text",
"message": "text",
"details": {}
}
}
],
"request_id": "text"
}POST /v1/query/sql-report
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
falseValidation Error
POST /v1/query/sql-report HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 76
{
"sources": [
{
"dataset_id": "text",
"alias": "text"
}
],
"sql": "text",
"max_rows": 1
}{
"columns": [
"text"
],
"rows": [
{}
],
"row_count": 1,
"truncated": false,
"request_id": "text",
"latency_ms": 1
}POST /v1/resolve
Bounded deterministic planner.
This endpoint resolves structured intent into an exact plan for POST /v1/query. It only uses registered-source metadata, join graph metadata, planner cache, and precomputed statistics. It does not scan datasets or execute queries.
Scope rules:
Provide
dataset_idfor dataset-scoped planning, orset
allow_org_scope=trueto plan across all visible datasets.
Deterministic guarantees:
identical intent_signature + schema_revision + scope => identical output
ambiguity clarifies or rejects; it never expands search
no fallback to slower planning paths exists
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Bounded planning request that returns an exact executable plan.
Public dataset ID alias for a registered source. Required unless allow_org_scope=true or only one visible dataset exists.
false0sum | avg | count | max | min
sumTop-N limit
desc | asc
descOptional non-authoritative raw text hint. Structured intent remains the source of truth.
falseWhen true, resolve can consider all visible datasets in the org.
falseSuccessful Response
""""""falseregistry_plannerValidation Error
POST /v1/resolve HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 519
{
"dataset_id": "text",
"metric": {
"role": "derived_measure",
"hint": "text"
},
"group_by": [
"text"
],
"preferred_source": "text",
"reject_on_ambiguity": false,
"min_source_confidence": 0,
"aggregation": "sum",
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"raw_text": "text",
"include_explanation": false,
"allow_org_scope": false
}{
"resolved_plan": {
"source_name": "text",
"metric_column": "text",
"aggregation": "sum",
"group_column": "text",
"join_path": {
"base_source": "text",
"group_source": "text",
"edges": [
{
"left_source": "text",
"right_source": "text",
"left_key": "text",
"right_key": "text",
"join_type": "inner",
"min_confidence": 0,
"expected_cardinality": "text",
"allow_many_to_many": false
}
],
"max_hops": 4,
"min_path_confidence": 0,
"reject_on_ambiguity": true,
"reject_on_fanout": true
},
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"schema_revision": "text"
},
"confidence": 1,
"plan": [
"text"
],
"explanation": [
"text"
],
"resolved_column": "",
"resolved_role": "",
"resolved_source": "",
"candidates": [
{
"source": "text",
"column": "text",
"role": "text",
"magnitude": "text",
"formula": "text",
"confidence": 1,
"score_components": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"notes": [
"text"
]
}
],
"source_scores": {
"ANY_ADDITIONAL_PROPERTY": 1
},
"latency_ms": 1,
"decision_path": "text",
"plan_hash": "text",
"schema_revision": "text",
"validated": true,
"deterministic_scope": "text",
"confidence_source": "text",
"clarification_required": false,
"rejection_reason": "text",
"request_id": "text",
"intent_signature": "text",
"source_set": [
"text"
],
"join_path": [
{}
],
"planner_mode": "registry_planner"
}POST /v1/sources/schema
Call this once when a user connects a data source.
Returns the full Algenta structural schema: column roles, detected formulas, cardinality, and query_hints the LLM should use when calling POST /v1/query.
The schema is also embedded as Arrow metadata in the returned Parquet bytes (parquet_b64), which the LLM agent can store and reuse — no re-profiling on subsequent queries.
Flow:
User connects data source
Call
POST /v1/sources/schema— ~1-2s, runs onceLLM reads
schemaJSON andquery_hintsUser asks questions → LLM produces structured intent →
POST /v1/query(~200ms, cached)
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
POST /v1/sources/schema HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 198
{
"sources": [
{
"name": "text",
"dataset_id": "text",
"source_id": "text",
"records": [
{}
],
"csv": "text",
"json_str": "text",
"url": "text",
"excel_b64": "text",
"parquet_b64": "text",
"connection": {},
"table": "text"
}
]
}{}POST /v1/verify
LLM calls this after reading /v1/sources/schema.
Submit the exact source + column names chosen by the LLM. The engine verifies:
Source exists in registry
metric_column exists and is numeric
aggregation is valid for the column's role
group_column exists (if given)
join path exists with sufficient confidence (if join_source_name given)
Returns valid: true + resolved names on success, or valid: false + errors + suggestions on failure. Call /v1/execute (or /v1/query with exact-spec) only after verify returns valid.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
LLM-produced execution plan. All names are EXACT (from schema endpoint). Mojo checks: source exists, columns exist, aggregation is valid for the column role, and join keys have sufficient confidence.
Exact source name from schema
Public dataset ID alias for a registered source. When provided, verification is scoped to that one registered dataset.
Exact column name to aggregate
sum | avg | count | max | min
Exact column name for group-by
Second source name for join
[local_col, remote_col] — join key pair. Omit to auto-detect.
Reject join paths below this confidence threshold. Default 0.85 — only statistically solid joins are accepted. Lower to 0.50 to allow weaker joins at your own risk.
0.85strict — reject invalid plans with no suggestions (enterprise enforcement). assist — reject invalid plans AND return corrective suggestions (default, LLM-friendly).
assistSuccessful Response
[][]""falseassistValidation Error
POST /v1/verify HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 921
{
"source_name": "text",
"dataset_id": "text",
"metric_column": "text",
"aggregation": "text",
"group_column": "text",
"join_source_name": "text",
"join_columns": [
"text"
],
"min_join_confidence": 0.85,
"mode": "assist",
"resolved_plan": {
"source_name": "text",
"metric_column": "text",
"aggregation": "sum",
"group_column": "text",
"join_path": {
"base_source": "text",
"group_source": "text",
"edges": [
{
"left_source": "text",
"right_source": "text",
"left_key": "text",
"right_key": "text",
"join_type": "inner",
"min_confidence": 0,
"expected_cardinality": "text",
"allow_many_to_many": false
}
],
"max_hops": 4,
"min_path_confidence": 0,
"reject_on_ambiguity": true,
"reject_on_fanout": true
},
"filter": {
"time_filter": "text",
"conditions": [
{
"column": "text",
"dimension_hint": "text",
"op": "eq",
"value": null,
"values": []
}
]
},
"limit": 1,
"order": "desc",
"constraints": {
"requires_derived": false,
"no_cross_source": false,
"min_column_confidence": 0,
"max_join_hops": 4
},
"schema_revision": "text"
}
}{
"valid": true,
"errors": [
"text"
],
"suggestions": [
"text"
],
"resolved": {
"ANY_ADDITIONAL_PROPERTY": "text"
},
"valid_dimensions": [
"text"
],
"valid_measures": [
"text"
],
"source_behavior": "",
"latency_ms": 1,
"verified": false,
"request_id": "text",
"schema_revision": "text",
"plan_hash": "text",
"verification_mode": "assist",
"rejection_reason": "text"
}Simulation
POST /v1/simulate
Execute a Monte Carlo simulation and receive a structured decision envelope. Use mode: 'auto' for minimal setup or mode: 'expert' for full control.
Performance: p50 < 15ms server-side (Mojo worker pool, async persistence).
Execution policy: Algenta editions have unlimited decisions and no plan request meter. HTTP 429 is reserved for explicit endpoint, provider, or operator controls.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Full decision output returned by /v1/simulate, /v1/recommend, and /v1/score.
completedWhich simulation algorithm was used. Possible values: monte_carlo | qmc_sobol | lhs | bootstrap | scenario | sensitivity | mcmc | decision_tree | time_series | compare | importance_sampling
monte_carloEngine that ran the simulation (e.g. 'mojo-native-expr', 'lhs', 'mcmc')
High-level simulation contract class. Examples: predictive, scenario_analysis, sensitivity_analysis, decision_tree.
predictiveStable engine or model revision used to generate this result.
Stable fingerprint of the validated simulation assumptions executed by the engine.
Normalized summary of the validated request inputs used for execution. Includes mode, runs, variable counts, and model selection.
Primary outcome confidence interval derived from the simulated distribution.
Correlation identifier propagated from the API request.
Populated for simulation_model='scenario': expected_value, best_case, scenarios list
Populated for simulation_model='sensitivity': tornado_chart, first_order_sobol, variable_importance
Populated for simulation_model='bootstrap': statistic, observed_value, CI, bias, SE
Populated for simulation_model='mcmc': posterior summaries, R-hat, acceptance_rate
Populated for simulation_model='importance_sampling'. Contains: tail_direction, target_threshold, tail_probability, tail_probability_se, cvar_tail, weighted_mean, weighted_std, theta (tilt parameter), tilt_variable, effective_sample_size, nominal_sample_size, variance_reduction_factor, naive_tail_count.
Populated for simulation_model='decision_tree': n_paths, expected_value, paths[]
Populated for simulation_model='time_series'. Contains: model, granularity, dt_years, initial_value, n_steps, fan_chart (per-horizon p5/p25/p50/p75/p95), terminal distribution, max_drawdown_pct, and optional sample_paths for visualization.
Human-readable formatted output values with units. Populated when output_unit_specs or unit_spec is provided. Contains: mean_formatted, p5_formatted, p95_formatted, unit, unit_type, etc.
Unit metadata for all variables and outputs. Contains per-variable unit type, code, precision, and display scale. Use this to reconstruct formatted values client-side.
Non-fatal unit validation warnings (e.g. negative currency, out-of-range probability). Simulation still ran — these are advisory only.
Pre-computed Vega-Lite compatible chart specs for instant rendering. Populated when include_charts=true in the request or automatically for sensitivity/time_series engine types. Keys: 'histogram', 'cdf', 'tornado', 'fan_chart', 'scatter'. Each value is a complete Vega-Lite spec that can be passed to vega-embed.
Pre-computed histogram bins (50 bins) for the primary output distribution.
SHA-256 fingerprint of the INPUT payload (variables, distributions, objective function, seed). Cryptographic proof of what data was used to make this decision. Computed at submission time before simulation runs. Format: hex string, 64 chars.
SHA-256 fingerprint of this decision OUTPUT (64-char hex). Covers: run_id, request_hash (input binding), recommended_action, confidence, rationale, metrics, percentiles, scenarios_run, engine_version, simulation_model. Binds the decision to both its inputs AND outputs. Use to verify the decision has not been tampered with. Also returned as X-Decision-Hash response header.
Validation Error
POST /v1/simulate HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226
{
"mode": "auto",
"runs": 10000,
"scenario": {
"name": "Product launch decision",
"objective": "maximize_net_value",
"variables": {
"cost": {
"high": 90000,
"low": 40000
},
"revenue": {
"high": 200000,
"low": 80000
}
}
},
"simulation_model": "monte_carlo"
}{
"run_id": "123e4567-e89b-12d3-a456-426614174000",
"status": "completed",
"engine_version": "text",
"recommended_action": "text",
"confidence": 1,
"rationale": "text",
"metrics": {
"expected_value": 1,
"median": 1,
"std_deviation": 1,
"variance": 1,
"probability_of_loss": 1,
"var_95": 1,
"cvar_95": 1
},
"percentiles": {
"p5": 1,
"p10": 1,
"p25": 1,
"p50": 1,
"p75": 1,
"p90": 1,
"p95": 1,
"p99": 1
},
"scenarios_run": 1,
"execution_ms": 1,
"metadata": {
"mode": "text",
"seed": 1,
"billing_units": 1,
"engine_version": "text"
},
"simulation_model": "monte_carlo",
"engine_type": "text",
"simulation_class": "predictive",
"model_revision": "text",
"assumptions_hash": "text",
"validated_inputs": {},
"confidence_interval": {},
"request_id": "text",
"scenario_analysis": {},
"sensitivity_analysis": {},
"bootstrap_result": {},
"mcmc_result": {},
"importance_sampling_result": {},
"scenario_ranking": [
{}
],
"sensitivity_ranking": [
{}
],
"score": 1,
"score_breakdown": {},
"created_at": "2026-01-01T00:00:00.000Z",
"decision_tree_result": {},
"time_series_result": {},
"formatted_result": {},
"unit_context": {},
"unit_warnings": [
"text"
],
"charts": {},
"histogram_data": {},
"decision_plan": {
"recommended_action": "text",
"confidence": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"options": [
{
"name": "text",
"rank": 1,
"expected_value": 1,
"risk": {
"p5": 1,
"p95": 1,
"probability_of_loss": 1,
"var_95": 1
},
"score": 1
}
],
"rationale": "text",
"integrity": {},
"calibration": "text"
},
"request_hash": "text",
"result_hash": "text"
}GET /v1/simulate/templates
Returns all available domain-specific simulation templates. Requires API key authentication. Use the template's id with GET /v1/simulate/templates/{id} to get a ready-to-run payload.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
125Successful Response
Validation Error
GET /v1/simulate/templates HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
GET /v1/simulate/templates/{template_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
50000Successful Response
Validation Error
GET /v1/simulate/templates/{template_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
POST /v1/templates/{template_id}/run
Run a simulation template by ID without constructing the full payload. Optionally override runs and seed. Returns simulation results immediately.
Use GET /v1/simulate/templates to list all available templates.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
10000monte_carloSuccessful Response
Validation Error
POST /v1/templates/{template_id}/run HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
No content
Source Registry
GET /v1/sources
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
1Successful Response
Validation Error
GET /v1/sources HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}GET /v1/sources/graph
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
GET /v1/sources/graph HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
Successful Response
{}POST /v1/sources/register
One-time registration per data source.
Full column scan (handles sparse/late-appearing data)
Mojo detects A×B≈C formulas within the source
Mojo detects join keys to every already-registered source
Result cached in memory (hot) + persisted to disk (survives restarts)
After registration, use POST /v1/query with sources: [] to query all registered sources, or pass source_ids to target specific ones.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Optional human description
Successful Response
Validation Error
POST /v1/sources/register HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 216
{
"source": {
"name": "text",
"dataset_id": "text",
"source_id": "text",
"records": [
{}
],
"csv": "text",
"json_str": "text",
"url": "text",
"excel_b64": "text",
"parquet_b64": "text",
"connection": {},
"table": "text"
},
"description": "text"
}{}GET /v1/sources/{source_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
GET /v1/sources/{source_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}DELETE /v1/sources/{source_id}
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
Successful Response
Validation Error
DELETE /v1/sources/{source_id} HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{}Streaming
POST /v1/simulate/stream
Run a simulation and receive progressive results via Server-Sent Events.
The connection stays open and emits events as the Mojo engine computes:
progressevents everycheckpoint_everyruns (default: 1000) Each carries Welford online statistics:mean,std,min,max,probability_of_loss,runs_completed,progress(0–1).finalevent when complete — contains the fullDecisionEnvelopeidentical to what/v1/simulatereturns.
Example (curl)
curl -N -X POST /v1/simulate/stream \
-H "Authorization: Bearer sk-..." \
-H "Content-Type: application/json" \
-d '{"mode":"expert","runs":100000,"variables":[...]}'Example (JavaScript EventSource)
const es = new EventSource('/v1/simulate/stream?token=sk-...');
es.addEventListener('progress', e => console.log(JSON.parse(e.data)));
es.addEventListener('final', e => {
console.log(JSON.parse(e.data).result);
es.close();
});Query parameters
checkpoint_every— emit a progress event every N runs (default: 1000, min: 100)
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
1000SSE stream of progress events + final DecisionEnvelope
Validation Error
POST /v1/simulate/stream HTTP/1.1
Host: api.algenta.ai
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 226
{
"mode": "auto",
"runs": 10000,
"scenario": {
"name": "Product launch decision",
"objective": "maximize_net_value",
"variables": {
"cost": {
"high": 90000,
"low": 40000
},
"revenue": {
"high": 200000,
"low": 80000
}
}
},
"simulation_model": "monte_carlo"
}System
GET /v1/admin/egress-log
GET /v1/admin/egress-policy
GET /v1/admin/privacy-report
GET /v1/admin/runtime/benchmarks
GET /v1/admin/runtime/modules
GET /v1/admin/runtime/validation
GET /v1/health
GET /v1/meta/contract
Successful Response
GET /v1/meta/contract HTTP/1.1
Host: api.algenta.ai
Accept: */*
Successful Response
{
"contract_version": "text",
"brand": "text",
"api_base_url": "text",
"mcp_endpoint": "text",
"mcp_tools_endpoint": "text",
"auth_scheme": "text",
"api_key_prefixes": {
"live": "text",
"test": "text"
},
"compatibility": {
"legacy_headers": [
"text"
],
"legacy_env_vars": [
"text"
],
"legacy_domains": [
"text"
],
"deprecation_window_days": 1
},
"defaults": {
"read_only_default": true,
"write_confirmation_required": true,
"plan_limits": {
"ANY_ADDITIONAL_PROPERTY": {}
}
},
"primary_data_query_contract": {},
"integrations": [
{
"name": "text",
"description": "text",
"icon": "text",
"capabilities": [
"text"
],
"auth_scheme": "text",
"required_scopes": [
"text"
],
"read_only_default": true,
"write_actions": [
"text"
],
"admin_controls": [
"text"
],
"docs_url": "text",
"privacy_url": "text",
"terms_url": "text",
"support_url": "text",
"regions": [
"text"
],
"status": "text"
}
]
}GET /v1/runtime/library-stats
GET /v1/runtime/manifest
GET /v1/version
Successful Response
GET /v1/version HTTP/1.1
Host: api.algenta.ai
Accept: */*
Successful Response
{
"api_version": "text",
"engine_version": "text",
"environment": "text"
}Team
GET /v1/audit-logs
Return paginated audit log for the authenticated org from the audit_events table.
Canonical v1 authentication. Use Authorization: Bearer <api_key>.
125Successful Response
Validation Error