api-ref.mdx

title	API Examples
description	Human-friendly Decision Engine API map with curl examples for every route family and routing flavour.

API Examples

Use this page as the main route map for local smoke tests, dashboard integration, and sandbox debugging. It groups the APIs by the flows an operator usually performs: create merchant, create API key, configure routing, run transactions, send feedback, inspect analytics, and audit decisions. For schema-level details, use API Overview and the OpenAPI-backed endpoint pages.

Which API docs should I use?

There are two API documentation surfaces:

Surface	Location	Purpose
API Examples	docs/api-refs/*.mdx	Human-facing curl examples, complete flows, request variants, and practical payloads. Start here when testing or integrating.
OpenAPI Endpoint Reference	docs/api-reference/endpoint/*.mdx	One page per OpenAPI operation, backed by docs/openapi.json for schema/playground rendering. Use this when checking exact request/response schema.

The advanced AND, OR, nested, and value-variant routing examples live in Advanced rule tree. The /routing/create OpenAPI page also includes a shorter version for quick schema-page lookup.

Route access model

Access class	Routes	Required headers
Public health	GET /health, GET /health/ready, GET /health/diagnostics	None
Public auth entrypoint	POST /auth/signup, POST /auth/login	None
Admin bootstrap	POST /merchant-account/create	Admin secret as configured for the deployment
Protected operator/API-key APIs	Auth session, API keys, merchant reads/deletes, routing, rule config, decision, score update, config, analytics, and audit routes	Authorization: Bearer <jwt_token> or x-api-key: <api_key>
Sandbox Hyperswitch routing	Same protected/public route rules, routed through https://sandbox.hyperswitch.io	Add x-feature: decision-engine

Environment

# Local source or Docker Compose
export BASE_URL=http://localhost:8080

# Sandbox, when routed through Hyperswitch
# 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"

Public routes do not need AUTH_HEADER. Protected routes should include it:

curl "$BASE_URL/analytics/overview?range=1d" \
  --header "$AUTH_HEADER" \
  --header "$FEATURE_HEADER"

Main Contents

Health

• Health, readiness, and diagnostics: service liveness, dependency readiness, and local diagnostics with GET /health, GET /health/ready, and GET /health/diagnostics.

Auth And Onboarding

• Auth and onboarding: dashboard operator signup, login, logout, current user, merchant list, merchant switch, and dashboard merchant onboarding.

Merchant CRUD

• Create merchant account: create the merchant record used by routing, API keys, and analytics.
• Get merchant account: inspect the merchant account and setup state.
• Delete merchant account: remove a test merchant from Decision Engine local state.

API Key CRUD

• API keys: create, list, and revoke server-to-server API keys with POST /api-key/create, GET /api-key/list/:merchant_id, and DELETE /api-key/:key_id.

Rule-Based Routing CRUD And Lifecycle

• Create routing algorithm: create single, priority, volume_split, and advanced routing algorithms.
• Single connector: always return one configured connector.
• Priority list: return connectors in a fixed ordered priority.
• Volume split: distribute decisions across connectors by configured percentages.
• Advanced rule tree: AND, OR, nested AND+OR rules plus value variants such as enum arrays and number ranges.
• Activate routing algorithm: make a created algorithm active for a merchant.
• List routing algorithms: list created algorithms.
• List active routing algorithms: read the active algorithm.
• Evaluate routing algorithm: run a rule/volume decision through /routing/evaluate.
• Hybrid routing evaluation: evaluate the hybrid routing surface when rule output must be combined with runtime scoring.

There is no public deactivate route in the current API contract. To change active behavior, create or select another algorithm and call /routing/activate.

Rule Config CRUD

• Create success-rate config, get, update, and delete: manage auth-rate scoring config.
• Create elimination config, get, update, and delete: manage downtime/elimination config.

Decide Gateway Transactions

• SR-based routing: transact with SR_BASED_ROUTING.
• Priority-list routing: transact with PL_BASED_ROUTING.
• Debit/network routing: transact with NTW_BASED_ROUTING.
• Network + SR hybrid routing: transact with NTW_SR_HYBRID_ROUTING.

Update Gateway Score

• Update gateway score: send post-authorization feedback to update auth-rate analytics and scoring.

Debit Routing

• Debit-routing merchant flag: read, enable, and disable merchant-level debit routing.
• Debit/network routing transaction: run /decide-gateway with debit metadata after the flag is enabled.

Config

• Routing config endpoints: get supported routing keys and configure SR dimensions.

Analytics And Audit

• Analytics endpoints: overview, gateway scores, decisions, routing stats, logs, payment audit, preview trace, pagination, filters, and debit-routing audit.

Compatibility

• Legacy decision endpoint: old /decision_gateway compatibility route.
• Legacy update score: old /update-score compatibility route.

Routing Algorithm Values

Use backend enum strings in requests:

UI label	Request value	Route family
Auth-rate based	SR_BASED_ROUTING	/decide-gateway
Priority-list based	PL_BASED_ROUTING	/decide-gateway
Debit/network based	NTW_BASED_ROUTING	/decide-gateway
Network + SR hybrid	NTW_SR_HYBRID_ROUTING	/decide-gateway