api-reference/decision-engine-api-reference/api-reference/guides/api-ref.mdx
This guide walks the Decision Engine API in the order you'll actually use it: set up a merchant, configure how transactions should be routed, send transactions to /decide-gateway, feed outcomes back, and review analytics.
Every page below includes ready-to-run curl examples with realistic payloads. For exact request and response schemas plus an interactive playground, use the OpenAPI Reference.
| Surface | Best for |
|---|---|
| API Guide (this section) | Copy-paste curl examples, end-to-end flows, and request variants. |
| OpenAPI Reference | One page per endpoint with full schemas and a request playground. |
A typical integration follows these steps. Each links to the page with the exact request.
<Steps> <Step title="Create a merchant"> Create the merchant record that owns your routing config, API keys, and analytics. See [Create Merchant Account](/decision-engine-api-reference/api-reference/guides/merchant-accounts/merchant-account-create). </Step> <Step title="Create an API key"> Issue a server-to-server API key to authenticate the calls that follow. See [API Keys](/decision-engine-api-reference/api-reference/guides/auth-onboarding/api-keys). </Step> <Step title="Configure routing"> Decide how connectors are chosen — a fixed connector, a priority list, a volume split, or an advanced rule tree — then activate it. See [Create Routing Algorithm](/decision-engine-api-reference/api-reference/guides/configure-routing/routing-algorithm-create). </Step> <Step title="Run transactions"> Call `/decide-gateway` for each payment to get the connector to use. See [Run Transactions](/decision-engine-api-reference/api-reference/guides/run-transactions/decide-gateway-sr-based). </Step> <Step title="Send feedback"> Report the authorization outcome so scoring and analytics stay accurate. See [Update Gateway Score](/decision-engine-api-reference/api-reference/guides/feedback-scoring/update-gateway-score). </Step> <Step title="Review analytics"> Inspect gateway scores, decisions, and audit trails. See [Analytics & Audit](/decision-engine-api-reference/api-reference/guides/analytics-audit/analytics-endpoints). </Step> </Steps>Set these once in your shell and reuse them across every example.
# Base URL — local source build or Docker Compose
export BASE_URL=http://localhost:8080
# Sandbox (routed through Hyperswitch), when applicable
# export BASE_URL=https://sandbox.hyperswitch.io
# Protected endpoints accept either a dashboard JWT or an API key
export AUTH_HEADER="Authorization: Bearer <jwt_token>"
# export AUTH_HEADER="x-api-key: DE_<api_key>"
# Sandbox-only routing header
export FEATURE_HEADER="x-feature: decision-engine"
# Required on analytics routes, /health/diagnostics, and /gateway-score/reset only.
# "public" is the only tenant the shipped config files define.
export TENANT_HEADER="x-tenant-id: public"
Public routes need no auth. Protected routes include AUTH_HEADER:
curl "$BASE_URL/analytics/overview?range=1d" \
--header "$AUTH_HEADER" \
--header "$TENANT_HEADER" \
--header "$FEATURE_HEADER"
| Access class | Routes | Required headers |
|---|---|---|
| Public health | GET /health, GET /health/ready | None |
| Public health (tenant-scoped) | GET /health/diagnostics | TENANT_HEADER — no auth |
| Public auth entry | POST /auth/signup, POST /auth/login | None |
| Admin bootstrap | POST /merchant-account/create | Admin secret configured for the deployment |
| Protected APIs | API keys, merchant reads/deletes, routing, rule config, decisions, score updates, config | Authorization: Bearer <jwt_token> or x-api-key: <api_key> |
| Protected APIs (tenant-scoped) | All GET /analytics/*, POST /gateway-score/reset | The above, plus TENANT_HEADER |
| Sandbox (Hyperswitch) | Same rules, served through https://sandbox.hyperswitch.io | Add x-feature: decision-engine |
/decide-gateway supports several strategies, selected per request with rankingAlgorithm.
| Strategy | Request value | Guide |
|---|---|---|
| Success-rate (auth-rate) based | SR_BASED_ROUTING | SR-based routing |
| Priority-list based | PL_BASED_ROUTING | Priority-list routing |
| Debit / network based | NTW_BASED_ROUTING | Debit routing |
| Network + SR hybrid | NTW_SR_HYBRID_ROUTING | Hybrid routing |
Beyond the core decide/feedback loop, Decision Engine ships several self-contained systems that build on it:
| Capability | What it does | Start here |
|---|---|---|
| Cost data ingestion | Learns each connector's actual fee (from settlement reports and invoices) at a per-cluster level, feeding multi-objective routing's expected-value ranking. | Connector setup → uploads → fees & coverage |
| A/B testing | Splits traffic between a control and variant routing strategy — auth vs. cost-aware, manual vs. autopilot, or any two saved algorithms — with a guardrail and significance testing. | Create an experiment → read results |
| Simulation | Preview what any routing algorithm (including an A/B test arm) would decide for a given payment context, without a real transaction. | Evaluate Routing Algorithm |
| Autopilot & auto-calibration | Background job that self-tunes SR hedging % and bucket size from observed traffic, with a hard-reset endpoint for simulation runs. | Merchant Features |
Legacy routes are kept for older integrations. New integrations should use /decide-gateway and /update-gateway-score.
/decision_gateway route./update-score route.