Drive decisions through the API
Drive the full Algenta decisions API — plan, log, execute, and delete decisions — and call the one-line product endpoints for decision, agent, optimize, retrieve, and forecast.
Algenta exposes decisions at two altitudes. The decisions lifecycle under /v1/decisions lets you generate a structured plan, log the decision you made, execute it to a webhook, record the real outcome, and delete it. The one-call product endpoints (/v1/decision, /v1/agent/run, /v1/optimize, /v1/retrieve, /v1/forecast) wrap the engine behind a single business-shaped request so you can get an answer without touching simulation internals. This guide walks both.
You need an API key (see Authentication) exported as $ALGENTA_API_KEY, and a running engine — the hosted API at https://api.algenta.ai or a self-hosted server at http://localhost:8000.
The decisions lifecycle
Plan a decision
POST /v1/decisions/plan runs the same validated request contract as /v1/simulate but returns only the compact DecisionPlan — the recommended action, expected value, confidence, risk, and rationale — without the full envelope. It is the LLM- and dashboard-friendly summary.
curl -sS -X POST "https://api.algenta.ai/v1/decisions/plan" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"mode": "auto",
"scenario": {
"variables": {
"revenue": { "low": 80000, "high": 200000 },
"cost": { "low": 30000, "high": 90000 }
},
"objective": "maximize_net_value"
},
"runs": 10000,
"seed": 42
}'import os
from decision_engine import AlgentaClient
client = AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"])
plan = client.plan_decision({
"mode": "auto",
"scenario": {
"variables": {
"revenue": {"low": 80000, "high": 200000},
"cost": {"low": 30000, "high": 90000},
},
"objective": "maximize_net_value",
},
"runs": 10000,
"seed": 42,
})
print(plan.recommended_action, plan.expected_value, plan.confidence)The 200 DecisionPlan carries recommended_action, options, expected_value, confidence, rationale, a risk object (p5, p95, probability_of_loss), and an integrity object. Once your org has recorded outcomes, the returned confidence is calibrated and a calibration summary is attached.
Log the decision
POST /v1/decisions records the action you chose. Only chosen_action is required; logging expected_value is what lets the engine compute a delta later, and an optional run_id binds the record to the simulation that produced it. The call returns 201 Created with the new decision id.
curl -sS -X POST "https://api.algenta.ai/v1/decisions" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"context": "Q3 pricing change for the Pro tier",
"chosen_action": "raise_price_10pct",
"options_considered": ["hold", "raise_price_10pct", "raise_price_20pct"],
"expected_value": 142000,
"confidence": 0.78,
"risk_p5": -8000,
"risk_p95": 210000,
"risk_pol": 0.12
}'decision = client.log_decision({
"context": "Q3 pricing change for the Pro tier",
"chosen_action": "raise_price_10pct",
"options_considered": ["hold", "raise_price_10pct", "raise_price_20pct"],
"expected_value": 142000,
"confidence": 0.78,
"risk_p5": -8000,
"risk_p95": 210000,
"risk_pol": 0.12,
})
print(decision.id)Export the returned id as $DECISION_ID. The record also pins policy_snapshot_id, schema_snapshot_id, and manifest_version, which is what makes it auditable later.
Execute the decision to a webhook
POST /v1/decisions/{id}/execute fires the logged decision to an external HTTPS webhook, turning it into an automated action. The webhook receives the full decision context and integrity hashes; the response code and status are persisted back onto the record.
curl -sS -X POST "https://api.algenta.ai/v1/decisions/$DECISION_ID/execute" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"webhook_url": "https://ops.example.com/hooks/pricing",
"timeout_seconds": 10,
"metadata": {"channel": "pricing-bot"}
}'import os, requests
resp = requests.post(
f"https://api.algenta.ai/v1/decisions/{os.environ['DECISION_ID']}/execute",
headers={"Authorization": f"Bearer {os.environ['ALGENTA_API_KEY']}"},
json={
"webhook_url": "https://ops.example.com/hooks/pricing",
"timeout_seconds": 10,
},
)
receipt = resp.json()
print(receipt["execution_status"], receipt["response_code"])const resp = await fetch(
`https://api.algenta.ai/v1/decisions/${process.env.DECISION_ID}/execute`,
{
method: "POST",
headers: {
Authorization: `Bearer ${process.env.ALGENTA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({
webhook_url: "https://ops.example.com/hooks/pricing",
timeout_seconds: 10,
}),
},
);
const receipt = await resp.json();
console.log(receipt.execution_status, receipt.response_code);The 200 ExecutionReceipt returns execution_status (delivered or failed), response_code, executed_at, and a payload_summary. Execution passes through your org's safety gates: a decision below min_confidence or beyond risk_floor is blocked with 409 and an execution_blocked_* code. Pass force: true to re-fire an already-delivered decision, or override_safety: true to bypass the confidence and risk gates for one call. See Configure the execution policy.
Record the actual outcome
When the real number is known, close the loop with PATCH /v1/decisions/{id}/outcome. The engine sets outcome_recorded_at, computes outcome_delta = actual_outcome - expected_value, and refreshes your org's confidence calibration.
curl -sS -X PATCH "https://api.algenta.ai/v1/decisions/$DECISION_ID/outcome" \
-H "Authorization: Bearer $ALGENTA_API_KEY" \
-H "Content-Type: application/json" \
-d '{"actual_outcome": 131500, "outcome_notes": "Lower conversion than modeled."}'updated = client.record_outcome(
decision.id,
actual_outcome=131500,
outcome_notes="Lower conversion than modeled.",
)
print(updated.outcome_delta) # -10500const resp = await fetch(
`https://api.algenta.ai/v1/decisions/${process.env.DECISION_ID}/outcome`,
{
method: "PATCH",
headers: {
Authorization: `Bearer ${process.env.ALGENTA_API_KEY}`,
"Content-Type": "application/json",
},
body: JSON.stringify({ actual_outcome: 131500 }),
},
);
const updated = await resp.json();
console.log(updated.outcome_delta); // -10500Read and manage the log
GET /v1/decisions returns the org's decision history, most recent first, with pagination (page, limit) and a with_outcome_only filter. GET /v1/decisions/{id} reads one; DELETE /v1/decisions/{id} deletes one.
# List only decisions that already have an outcome recorded.
curl -sS "https://api.algenta.ai/v1/decisions?with_outcome_only=true&limit=20" \
-H "Authorization: Bearer $ALGENTA_API_KEY"
# Read a single record.
curl -sS "https://api.algenta.ai/v1/decisions/$DECISION_ID" \
-H "Authorization: Bearer $ALGENTA_API_KEY"
# Delete a record — returns 204 No Content.
curl -sS -X DELETE "https://api.algenta.ai/v1/decisions/$DECISION_ID" \
-H "Authorization: Bearer $ALGENTA_API_KEY"The list response carries decisions[], total, page, limit, and pages.
The one-call product API
These endpoints hide the engine behind a single business-shaped request. Each returns a latency_ms and a stable id, and each is metered like any other engine call.
POST /v1/decision
"What should I do?"
inputs[], objective, risk_tolerance, scenarios, engine
action, confidence, reasoning, why[], expected_outcome, downside_risk, upside_potential, probability_of_loss
POST /v1/agent/run
"Do this task."
task, context, tools[], max_steps, output_format
run_id, status, result, steps[], tools_used[]
POST /v1/optimize
"Find the best value."
objective, variables[] (min, max), constraints[], iterations, engine
optimal_values, objective_value, improvement_vs_midpoint, constraints_satisfied
POST /v1/retrieve
"Search my knowledge."
query, documents[] or collection_id, top_k, rerank
results[] (rank, relevance_score, snippet), total_searched
POST /v1/forecast
"What will happen?"
metric, history[], horizon, seasonality, confidence_level
baseline, forecast_mean, total_change_pct, periods[]
A worked example of the flagship endpoint — describe your inputs and get an action back:
The action is proceed, pause, or reject, with a plain-English reasoning string and three crisp why bullets. The remaining four endpoints follow the same one-request shape:
Troubleshooting
Next steps
Last updated
Was this helpful?