feat(docs): improve docs

README.md

@@ -108,7 +108,9 @@ Open:
 - API: `http://localhost:8080`
 - Dashboard: `http://localhost:8081/dashboard/`
 - Docs: `http://localhost:8081/introduction`
-- API examples: `http://localhost:8081/api-refs/api-ref`
+- API documentation map: `http://localhost:8081/api-overview`
+
+For deployed docs or dashboard environments, use the same docs paths under the deployed host, for example `https://<docs-host>/api-overview`. That page links to the API examples and OpenAPI reference sections.
 
 ### 🦀 From Source
 
@@ -144,8 +146,7 @@ curl http://localhost:8080/health
 | [Local Setup Guide](docs/local-setup.md) | Canonical guide for CLI, Docker, Compose profiles, and Helm |
 | [MySQL Setup Guide](docs/setup-guide-mysql.md) | MySQL-specific walkthrough |
 | [PostgreSQL Setup Guide](docs/setup-guide-postgres.md) | PostgreSQL-specific walkthrough |
-| [API Reference](docs/api-reference.md) | OpenAPI-backed REST API documentation |
-| [API Examples](docs/api-refs/api-ref.mdx) | Curl examples for every route family and routing flavour |
+| [API Documentation Map](docs/api-overview.md) | Main API entrypoint with embedded links to API examples, OpenAPI schema pages, route access rules, local URLs, and deployed docs paths |
 | [Configuration Guide](docs/configuration.md) | All config options explained |
 | [Deep Dive Blog](https://juspay.io/blog/juspay-orchestrator-and-merchant-controlled-routing-engine) | How routing logic works |
 

docs/api-overview.md

@@ -0,0 +1,90 @@
+# API Documentation Map
+
+Decision Engine keeps API documentation in two complementary forms: example-first guides for integration work, and OpenAPI-backed endpoint pages for schema lookup.
+
+## Start here
+
+| Page | Use it for |
+| --- | --- |
+| [API Examples](api-refs/api-ref.mdx) | Copy-paste cURL flows, request variants, rule examples, merchant/API-key CRUD, decision calls, debit routing, analytics, and audit. |
+| [OpenAPI Overview](api-reference.md) | Schema-oriented endpoint navigation backed by `docs/openapi.json`. |
+| [OpenAPI contract](openapi.json) | Machine-readable contract used by Mintlify and API tooling. |
+
+## API examples by route family
+
+| Route family | Example docs |
+| --- | --- |
+| Health | [Health, readiness, and diagnostics](api-refs/health-check.mdx) |
+| Auth and onboarding | [Auth and onboarding](api-refs/auth-and-onboarding.mdx) |
+| Merchant CRUD | [Create merchant](api-refs/merchant-account-create.mdx), [get merchant](api-refs/merchant-account-get.mdx), [delete merchant](api-refs/merchant-account-delete.mdx) |
+| API key CRUD | [Create, list, and revoke API keys](api-refs/api-keys.mdx) |
+| Rule-based routing lifecycle | [Create](api-refs/routing-algorithm-create.mdx), [activate](api-refs/routing-algorithm-activate.mdx), [list](api-refs/routing-algorithm-list.mdx), [list active](api-refs/routing-algorithm-list-active.mdx), [evaluate](api-refs/routing-algorithm-evaluate.mdx), [hybrid](api-refs/routing-hybrid.mdx) |
+| Rule algorithm variants | [Single connector](api-refs/routing-single-connector-example.mdx), [priority](api-refs/routing-priority-example.mdx), [volume split](api-refs/routing-volume-split-example.mdx), [advanced AND/OR/nested](api-refs/routing-advanced-example.mdx) |
+| Rule config CRUD | [Success-rate create](api-refs/success-rate-config-create.mdx), [get](api-refs/success-rate-config-get.mdx), [update](api-refs/success-rate-config-update.mdx), [delete](api-refs/success-rate-config-delete.mdx), [elimination create](api-refs/elimination-config-create.mdx), [get](api-refs/elimination-config-get.mdx), [update](api-refs/elimination-config-update.mdx), [delete](api-refs/elimination-config-delete.mdx) |
+| Decide gateway transactions | [SR-based](api-refs/decide-gateway-sr-based.mdx), [priority-list](api-refs/decide-gateway-pl-based.mdx), [debit/network](api-refs/decide-gateway-debit-routing.mdx), [network + SR hybrid](api-refs/decide-gateway-hybrid-routing.mdx) |
+| Score update | [Update gateway score](api-refs/update-gateway-score.mdx), [legacy update score](api-refs/update-score-legacy.mdx) |
+| Debit routing | [Merchant debit-routing flag](api-refs/merchant-debit-routing.mdx), [debit transaction request](api-refs/decide-gateway-debit-routing.mdx) |
+| Config | [Routing config endpoints](api-refs/config-endpoints.mdx) |
+| Analytics and audit | [Analytics endpoints](api-refs/analytics-endpoints.mdx) |
+| Compatibility | [Legacy decision endpoint](api-refs/decision-gateway-legacy.mdx), [legacy update score](api-refs/update-score-legacy.mdx) |
+
+## OpenAPI endpoint pages
+
+Use these when you need schema-backed endpoint pages or Mintlify playground metadata:
+
+| Family | OpenAPI docs |
+| --- | --- |
+| Health | [Health](api-reference/endpoint/healthCheck.mdx), [ready](api-reference/endpoint/healthReady.mdx), [diagnostics](api-reference/endpoint/healthDiagnostics.mdx) |
+| Auth and onboarding | [Signup](api-reference/endpoint/signup.mdx), [login](api-reference/endpoint/login.mdx), [logout](api-reference/endpoint/logout.mdx), [me](api-reference/endpoint/me.mdx), [merchants](api-reference/endpoint/listUserMerchants.mdx), [switch merchant](api-reference/endpoint/switchMerchant.mdx), [onboard merchant](api-reference/endpoint/onboardMerchant.mdx) |
+| API keys | [Create](api-reference/endpoint/createApiKey.mdx), [list](api-reference/endpoint/listApiKeys.mdx), [revoke](api-reference/endpoint/revokeApiKey.mdx) |
+| Merchant account | [Create](api-reference/endpoint/createMerchant.mdx), [get](api-reference/endpoint/getMerchant.mdx), [delete](api-reference/endpoint/deleteMerchant.mdx), [get debit routing](api-reference/endpoint/getMerchantDebitRouting.mdx), [update debit routing](api-reference/endpoint/updateMerchantDebitRouting.mdx) |
+| Routing | [Create](api-reference/endpoint/createRoutingRule.mdx), [activate](api-reference/endpoint/activateRoutingRule.mdx), [list](api-reference/endpoint/listRoutingRules.mdx), [active](api-reference/endpoint/getActiveRoutingRule.mdx), [evaluate](api-reference/endpoint/evaluateRoutingRule.mdx), [hybrid](api-reference/endpoint/hybridRouting.mdx) |
+| Rule config | [Create](api-reference/endpoint/createRuleConfig.mdx), [get](api-reference/endpoint/getRuleConfig.mdx), [update](api-reference/endpoint/updateRuleConfig.mdx), [delete](api-reference/endpoint/deleteRuleConfig.mdx) |
+| Decision and score | [Decide gateway](api-reference/endpoint/decideGateway.mdx), [legacy decision gateway](api-reference/endpoint/legacyDecisionGateway.mdx), [update gateway score](api-reference/endpoint/updateGatewayScore.mdx), [legacy update score](api-reference/endpoint/legacyUpdateScore.mdx) |
+| Config | [Routing keys](api-reference/endpoint/getRoutingConfig.mdx), [SR dimensions](api-reference/endpoint/configSrDimension.mdx) |
+| Analytics | [Overview](api-reference/endpoint/analyticsOverview.mdx), [gateway scores](api-reference/endpoint/analyticsGatewayScores.mdx), [decisions](api-reference/endpoint/analyticsDecisions.mdx), [routing stats](api-reference/endpoint/analyticsRoutingStats.mdx), [log summaries](api-reference/endpoint/analyticsLogSummaries.mdx), [payment audit](api-reference/endpoint/analyticsPaymentAudit.mdx), [preview trace](api-reference/endpoint/analyticsPreviewTrace.mdx) |
+
+## Local docs URLs
+
+When running the dashboard/docs Compose profile, docs are available through the local Nginx route:
+
+```text
+http://localhost:8081/introduction
+http://localhost:8081/api-overview
+http://localhost:8081/api-refs/api-ref
+http://localhost:8081/api-reference
+```
+
+## Deployed docs URLs
+
+For a deployed docs/dashboard host, use the same paths under the deployed base URL:
+
+```text
+https://<docs-host>/introduction
+https://<docs-host>/api-overview
+https://<docs-host>/api-refs/api-ref
+https://<docs-host>/api-reference
+```
+
+If the dashboard is hosted under a prefix such as `/decision-engine/`, the docs proxy should preserve the same page paths under that prefix.
+
+## Route access classes
+
+| Access class | Routes | Authentication |
+| --- | --- | --- |
+| Public | `GET /health`, `GET /health/ready`, `GET /health/diagnostics`, `POST /auth/signup`, `POST /auth/login` | None |
+| Admin bootstrap | `POST /merchant-account/create` | Admin secret configured for the deployment |
+| Protected | Routing, decision, score update, rule config, API key, merchant read/delete, analytics, audit, config, and authenticated auth routes | `Authorization: Bearer <jwt_token>` or `x-api-key: <api_key>` |
+| Sandbox | Same routes through `https://sandbox.hyperswitch.io` | Same auth rules plus `x-feature: decision-engine` |
+
+## Common flows
+
+| Flow | Primary docs |
+| --- | --- |
+| Merchant CRUD | [API Examples: Merchant CRUD](api-refs/api-ref.mdx#merchant-crud) |
+| API key CRUD | [API Examples: API Key CRUD](api-refs/api-ref.mdx#api-key-crud) |
+| Rule-based routing lifecycle | [Create routing algorithm](api-refs/routing-algorithm-create.mdx) |
+| Advanced AND/OR/nested rules | [Advanced rule tree](api-refs/routing-advanced-example.mdx) |
+| Decide-gateway transactions | [SR-based routing](api-refs/decide-gateway-sr-based.mdx) |
+| Debit routing | [Debit-routing merchant flag](api-refs/merchant-debit-routing.mdx) |
+| Analytics and audit | [Analytics endpoints](api-refs/analytics-endpoints.mdx) |

docs/api-reference.md

@@ -2,6 +2,25 @@
 
 The canonical OpenAPI contract for the docs site is `docs/openapi.json`. Use this page for schema-oriented navigation. Use [API Examples](./api-refs/api-ref.mdx) for curl-first flows, valid payloads, and route variants.
 
+## Docs surfaces
+
+| Surface | What it is for | Path |
+| --- | --- | --- |
+| API Examples | Public integration guide with cURL flows, variants, and working payloads. | [`docs/api-refs/`](./api-refs/api-ref.mdx) |
+| OpenAPI Endpoint Reference | Schema-backed endpoint pages generated around `docs/openapi.json`. | [`docs/api-reference/endpoint/`](./api-reference/endpoint/createRoutingRule.mdx) |
+| OpenAPI contract | Machine-readable contract consumed by Mintlify and tooling. | [`docs/openapi.json`](./openapi.json) |
+
+If you need rule examples such as AND, OR, nested AND+OR, `volume_split_priority`, enum arrays, or number-array matching, start with [Advanced Routing Example](./api-refs/routing-advanced-example.mdx). If you need the exact `POST /routing/create` schema and playground metadata, use [Create Routing Rule](./api-reference/endpoint/createRoutingRule.mdx).
+
+## Access classes
+
+| Class | Routes | Authentication |
+| --- | --- | --- |
+| Public | `GET /health`, `GET /health/ready`, `GET /health/diagnostics`, `POST /auth/signup`, `POST /auth/login` | None |
+| Admin bootstrap | `POST /merchant-account/create` | Admin secret |
+| Protected | All routing, decision, score update, rule config, API key, merchant read/delete, analytics, audit, config, and authenticated auth routes | `Authorization: Bearer <jwt_token>` or `x-api-key: <api_key>` |
+| Sandbox | Any Decision Engine route served through `https://sandbox.hyperswitch.io` | Same auth rules plus `x-feature: decision-engine` |
+
 ## Endpoint Families
 
 ### Health

docs/api-reference/endpoint/activateRoutingRule.mdx

@@ -1,4 +1,65 @@
 ---
 title: "Activate Routing Rule"
-openapi: "POST /routing/activate"
+description: "Activate a routing rule by ID for a merchant. Only one rule can be active at a time — activating a new rule deactivates the previous one."
+openapi: "openapi.json POST /routing/activate"
 ---
+
+# Activate Routing Rule
+
+## Use case
+
+Marks a created routing algorithm as active for the merchant/creator scope.
+
+## Authentication
+
+Protected. Send either `Authorization: Bearer <jwt_token>` or `x-api-key: <api_key>`. In sandbox, also send `x-feature: decision-engine`.
+
+For local development, start with:
+
+```bash
+export BASE_URL=http://localhost:8080
+export AUTH_HEADER="Authorization: Bearer <jwt_token>"
+# Sandbox only:
+# export BASE_URL=https://sandbox.hyperswitch.io
+# export FEATURE_HEADER="x-feature: decision-engine"
+```
+
+## Request
+
+- Method and path: `POST /routing/activate`
+- Parameters: none.
+- Body: JSON body with `created_by` and `routing_algorithm_id` or rule identifier returned by `/routing/create`.
+
+## Example
+
+### Activate rule
+
+```bash
+curl --location "$BASE_URL/routing/activate" \
+  --header "$AUTH_HEADER" \
+  --header "Content-Type: application/json" \
+  --data '{
+  "created_by": "merchant_demo",
+  "routing_algorithm_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0"
+}'
+```
+
+## Response
+
+```json
+{
+  "message": "routing rule activated",
+  "routing_algorithm_id": "routing_e641380c-6f24-4405-8454-5ae6cbceb7a0"
+}
+```
+
+## Notes
+
+- Only one routing algorithm should be active for a given creator scope.
+- Activate before calling `/routing/evaluate` from the explorer.
+
+## Related
+
+- [Create Routing Rule](./createRoutingRule.mdx)
+- [Get Active Routing Rule](./getActiveRoutingRule.mdx)
+- [Activate Routing Algorithm](../../api-refs/routing-algorithm-activate.mdx)

docs/api-reference/endpoint/analyticsDecisions.mdx

@@ -1,4 +1,102 @@
 ---
 title: "Analytics Decisions"
-openapi: "GET /analytics/decisions"
+description: "ClickHouse-backed decisions read endpoint."
+openapi: "openapi.json GET /analytics/decisions"
 ---
+
+# Analytics Decisions
+
+## Use case
+
+Returns decision volume time series and routing approach totals for the selected window.
+
+## Authentication
+
+Protected. Send either `Authorization: Bearer <jwt_token>` or `x-api-key: <api_key>`. In sandbox, also send `x-feature: decision-engine`.
+
+For local development, start with:
+
+```bash
+export BASE_URL=http://localhost:8080
+export AUTH_HEADER="Authorization: Bearer <jwt_token>"
+# Sandbox only:
+# export BASE_URL=https://sandbox.hyperswitch.io
+# export FEATURE_HEADER="x-feature: decision-engine"
+```
+
+## Request
+
+- Method and path: `GET /analytics/decisions`
+- Parameters:
+  - `range` (query, optional, string)
+  - `start_ms` (query, optional, integer)
+  - `end_ms` (query, optional, integer)
+  - `page` (query, optional, integer)
+  - `page_size` (query, optional, integer)
+  - `payment_method_type` (query, optional, string)
+  - `payment_method` (query, optional, string)
+  - `card_network` (query, optional, string)
+  - `card_is_in` (query, optional, string)
+  - `currency` (query, optional, string)
+  - `country` (query, optional, string)
+  - `auth_type` (query, optional, string)
+  - `gateway` (query, optional, string)
+  - `payment_id` (query, optional, string)
+  - `request_id` (query, optional, string)
+  - `route` (query, optional, string)
+  - `status` (query, optional, string)
+  - `flow_type` (query, optional, string)
+  - `routing_approach` (query, optional, string)
+  - `exclude_routing_approach` (query, optional, string)
+  - `error_code` (query, optional, string)
+- Body: Optional query parameters include `range`, `routing_approach`, `exclude_routing_approach`, `gateway`, and routing dimensions.
+
+## Example
+
+### Decision activity
+
+```bash
+curl "$BASE_URL/analytics/decisions?range=1h" \
+  --header "$AUTH_HEADER"
+```
+
+### Exclude debit routing
+
+```bash
+curl "$BASE_URL/analytics/decisions?range=1d&exclude_routing_approach=NTW_BASED_ROUTING" \
+  --header "$AUTH_HEADER"
+```
+
+## Response
+
+```json
+{
+  "series": [
+    {
+      "timestamp_ms": 1777136400000,
+      "gateway": "adyen",
+      "count": 7
+    },
+    {
+      "timestamp_ms": 1777136400000,
+      "gateway": "stripe",
+      "count": 3
+    }
+  ],
+  "totals": {
+    "SR_SELECTION_V3_ROUTING": 10
+  }
+}
+```
+
+## Notes
+
+- Analytics reads are ClickHouse-backed and merchant-scoped by the authenticated context.
+- Use `range=15m|1h|12h|1d|1w` or `start_ms` plus `end_ms` for a custom window.
+- Use this for route volume charts; use gateway scores for auth-rate score percentages.
+
+## Related
+
+- [Analytics Routing Stats](./analyticsRoutingStats.mdx)
+- [Payment Audit](./analyticsPaymentAudit.mdx)
+- [Analytics Endpoints](../../api-refs/analytics-endpoints.mdx)