API overview

The Algenta HTTP API — base URL, authentication, conventions, and where to find the full reference and the live explorer.

This page orients you to the Algenta REST API: where it lives, how to authenticate, how to discover what an instance supports, and how the endpoints are organized. Everything here is a copy-pasteable starting point. The same HTTP contract backs the Python and TypeScript SDKs, the algenta CLI, and the MCP server, so anything you can do over HTTP you can also do through those clients without changing semantics.

The HTTP API is the contract. Every other surface — Python, TypeScript, CLI, MCP — is a thin, faithful client over it. If you understand the endpoints below, you understand all of them.

Base URL

Every request targets one base URL. There is no global default that points at someone else's data; you choose explicitly.

Deployment	Base URL	When to use
Hosted (Algenta cloud)	https://api.algenta.ai	The managed control plane. This is DEFAULT_BASE_URL.
Self-hosted	http://localhost:8000	The engine you run yourself (Docker, Fly, or local).

All routes live under /v1. A few operational routes are unversioned (/metrics, /v1/health/ready for liveness/readiness, /docs, /redoc, /openapi.json).

export ALGENTA_BASE_URL="https://api.algenta.ai"   # or http://localhost:8000
export ALGENTA_API_KEY="de_live_..."

The interactive OpenAPI explorer is served from the running instance at /docs (Swagger UI), /redoc (ReDoc), and the raw schema at /openapi.json. The schema is the source of truth for request and response shapes.

Authentication

Authenticate with a bearer API key:

Authorization: Bearer ${ALGENTA_API_KEY}

Live keys are prefixed de_live_ and test keys de_test_. A legacy X-API-Key: header is also accepted for older clients, but Authorization: Bearer is the canonical scheme.

The SDKs read the key from the environment automatically. The variable is ALGENTA_API_KEY (the older DE_API_KEY still works).

Python

import os
from decision_engine import AlgentaClient

client = AlgentaClient(api_key=os.environ["ALGENTA_API_KEY"])
me = client.get_contract()  # GET /v1/meta/contract

TypeScript

import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient({ apiKey: process.env.ALGENTA_API_KEY });
const contract = await client.getContract();

cURL

curl -sS "${ALGENTA_BASE_URL}/v1/me" \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}"

Treat de_live_ keys as secrets. Keep them in environment variables or a secrets manager, never in source control. Use de_test_ keys for development and CI.

Device headers for capped keys

Some keys are bound to a device (for example, an installed runtime or a capped seat). When a request is made with such a key, the engine requires device-identity headers and a binding token. Sending them yourself is only necessary if you are calling the API directly; the SDKs and CLI manage device binding for you.

Advanced: device-identity headers for bound keys

Header	Meaning
X-Algenta-Device-Id	Stable device identifier (minimum 16 characters).
X-Algenta-Platform	Platform string for the device.
X-Algenta-Hostname-Hash	Hash of the hostname (never the raw hostname).
X-Algenta-Device-Binding-Token	Token proving this device is bound to the key.

curl -sS "${ALGENTA_BASE_URL}/v1/simulate" \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}" \
  -H "X-Algenta-Device-Id: ${ALGENTA_DEVICE_ID}" \
  -H "X-Algenta-Platform: ${ALGENTA_PLATFORM}" \
  -H "X-Algenta-Hostname-Hash: ${ALGENTA_HOSTNAME_HASH}" \
  -H "X-Algenta-Device-Binding-Token: ${ALGENTA_DEVICE_BINDING_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{ "mode": "auto", "scenario": { "name": "smoke", "variables": { "x": { "low": 1, "high": 2 } }, "objective": "maximize_net_value" }, "runs": 1000 }'

On the first bound request the engine issues a fresh X-Algenta-Device-Binding-Token in the response headers; store it and send it on subsequent calls. If a device header is missing, the error body names the exact required_header.

Discovery endpoints

Before hardcoding anything, ask the instance what it is and what it supports. These four endpoints are how the SDKs, CLI, and MCP bootstrap themselves.

Endpoint	Purpose
GET /v1/health	Liveness. Returns { "status": "ok", "timestamp": ... }. No auth.
GET /v1/meta/contract	Machine-readable platform contract: endpoint families, SDK and CLI and MCP method names, governed-filter rules.
GET /v1/runtime/manifest	Signed runtime manifest describing the engine build.
GET /v1/models	The LLM utility-model catalog this instance can actually execute.

Run the bootstrap sequence in order: confirm the instance is up, learn what it supports, confirm the build, then read the model catalog.

1

Confirm the instance is up

No auth required. A healthy instance returns { "status": "ok", "timestamp": ... }.

curl -sS "${ALGENTA_BASE_URL}/v1/health"

2

Read the platform contract

This is what drives the SDKs — endpoint families, method names, and governed-filter rules.

curl -sS "${ALGENTA_BASE_URL}/v1/meta/contract" \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}"

3

Confirm the runtime build

The signed runtime manifest tells you exactly which engine build is serving requests.

curl -sS "${ALGENTA_BASE_URL}/v1/runtime/manifest" \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}"

4

Read the model catalog

Discover which LLM utility models you can actually call on this instance.

curl -sS "${ALGENTA_BASE_URL}/v1/models" \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}"

GET /v1/models advertises only models that are truly executable on the instance: runtime-backed or explicitly configured provider-backed. If a model is not listed, calling it will not work. Read the catalog, then route to it.

Endpoint families

The router areas map cleanly to where you look for a given capability. All paths are under /v1.

Area	Representative paths	What it does
Data and query	/v1/data, /v1/data/{dataset_id}/summary, /v1/resolve, /v1/verify, /v1/query, /v1/query/batch, /v1/query/sql-report, /v1/sources	Discover datasets, resolve hints, run governed exact queries and read-only SQL reports.
Decisions	/v1/decisions, /v1/decisions/plan, /v1/decisions/{id}/outcome, /v1/decisions/{id}/execute	Decision memory: record decisions, plan, log outcomes, replay.
Simulate and recommend	/v1/simulate, /v1/simulate/templates, /v1/templates/{id}/run, /v1/recommend, /v1/score, /v1/compare	Monte Carlo simulation, templates, scoring and recommendation.
Agent runs	/v1/agent/runs, /v1/agent/runs/{run_id}, /v1/agent/runs/{run_id}/events	Launch and inspect agentic runs and their event streams.
Repositories	/v1/repositories/capabilities, /v1/repositories/{id}/snapshots, /v1/repositories/{id}/triage, /v1/repositories/{id}/graph-query	Repository intelligence: snapshot, triage, graph queries, security analyses.
LLM	/v1/models, plus the chat/embedding/utility routes under /v1	The governed LLM surface; models routed per the catalog.
Capabilities and connectors	/v1/capability-providers, /v1/capability-bindings, /v1/capabilities, /v1/capabilities/route, /v1/capabilities/execute	The capability plane: providers, bindings, routing and execution.
Account, keys, devices	/v1/me, /v1/usage, /v1/limits, /v1/api-keys, /v1/device/register, /v1/device/heartbeat, /v1/device/list	Identity, usage, key management, device lifecycle.
Billing and managed compatibility	/v1/billing/info, /v1/billing/checkout, /v1/billing/portal, /v1/credits/refresh, /v1/metering	Plan and billing plus generic managed-runtime compatibility. Algenta editions are unmetered.
License	/v1/license/challenge, /v1/license/renew, /v1/license/revocations	License verification and renewal for self-hosted and bound deployments.

The full, current set is always available at /openapi.json and described machine-readably at /v1/meta/contract.

Request and response shape

Requests and responses are JSON. Send Content-Type: application/json on bodies. A typical write is an auto-mode simulation — here is the same call across HTTP and the SDKs.

Python

envelope = client.simulate({
    "mode": "auto",
    "simulation_model": "monte_carlo",
    "scenario": {
        "name": "Product launch decision",
        "variables": {
            "revenue": {"low": 80000, "high": 200000},
            "cost": {"low": 40000, "high": 90000},
        },
        "objective": "maximize_net_value",
    },
    "runs": 10000,
})

cURL

curl -sS "${ALGENTA_BASE_URL}/v1/simulate" \
  -H "Authorization: Bearer ${ALGENTA_API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "mode": "auto",
    "simulation_model": "monte_carlo",
    "scenario": {
      "name": "Product launch decision",
      "variables": {
        "revenue": { "low": 80000, "high": 200000 },
        "cost":    { "low": 40000, "high": 90000 }
      },
      "objective": "maximize_net_value"
    },
    "runs": 10000
  }'

Successful responses carry the resource shape documented for each endpoint (for /v1/simulate, a decision envelope with expected_value, percentiles, recommended_action, confidence, execution_ms, and a structured decision_plan). Every response includes a request_id you can quote in support requests.

Error envelope

Every error — auth, validation, not found, rate limit, server — is returned in one envelope:

{
  "error": {
    "code": "invalid_api_key",
    "message": "The API key provided is invalid, expired, or has been revoked.",
    "request_id": "req_...",
    "docs_url": "https://docs.algenta.ai/errors/invalid_api_key"
  }
}

Status	Typical code	Meaning
401	authentication_required, invalid_api_key	No key, or the key is invalid/expired/revoked.
403	organization_suspended, account_suspended, email_verification_required	Authenticated but not permitted.
422	validation_error	Request body or query params failed validation. details lists each field and issue.
429	endpoint abuse control, provider limit, or operator policy	Inspect the error code and honor Retry-After when present.
500	internal_error	Unexpected server error; quote the request_id.

The complete, generated list of every code the API can return is on Error codes.

Example: a 422 validation error with field-level details

On a validation failure the details array names each offending field and the issue, so you can map errors back to your request precisely.

{
  "error": {
    "code": "validation_error",
    "message": "Request validation failed.",
    "details": [
      { "field": "body.runs", "issue": "Input should be less than or equal to 100000" }
    ],
    "request_id": "req_...",
    "docs_url": "https://docs.algenta.ai/errors/validation_error"
  }
}

Branch on error.code, not on the human-readable message. Codes are stable; messages are not.

Conventions

A few patterns hold across the API:

• Versioning — all routes are under /v1; the path version only changes on a breaking revision.

• Pagination — list endpoints accept limit/offset and report totals; page until you have what you need.

• Idempotency — mutating calls accept an idempotency key so a retry is safe (a reused key with a different body returns idempotency_key_conflict).

• Async jobs — long-running work goes to POST /v1/jobs; poll GET /v1/jobs/{id} and fetch GET /v1/jobs/{id}/result.

• Execution policy & safety limits — see Execution policy & safety limits; Algenta decisions are unlimited, while endpoint-specific 429 responses name their actual control.

The complete operation list is in the endpoint reference; try any of it live in the API explorer.

One contract, many clients

The HTTP API is the contract. The SDKs, the CLI, and MCP are thin, faithful surfaces over it — the method and tool names are themselves published in /v1/meta/contract. The same operation looks like this on each surface.

Python

from decision_engine import AlgentaClient

client = AlgentaClient(api_key="de_live_...")
datasets = client.list_datasets(search="orders", compact=True)

TypeScript

import { AlgentaClient } from "algenta-sdk";

const client = new AlgentaClient({ apiKey: "de_live_..." });
const datasets = await client.listDatasets({ search: "orders", compact: true });

CLI

de contract
de data list --search orders --compact --limit 10
de data summary $DATASET_ID

MCP clients (Claude Desktop, Codex, and other MCP hosts) connect to the same instance at the Streamable HTTP endpoint /mcp, with the matching tools at /mcp/tools, exposing tools such as get_contract, list_data, query_data, route_capabilities, and execute_capability. Whichever surface you choose, you are speaking the same /v1 contract — pick the one that fits your stack and start from the discovery endpoints above.

Next steps

API endpoint referenceAuthentication & API keysPython SDKMCP server