AION API REFERENCE
==================

Base URL
--------
https://api.aiondashboard.site


Authentication
--------------
Send your API key in the X-API-Key header.

Example:

    X-API-Key: YOUR_API_KEY


Versioning
----------
Current version is path-based:

    /v1/...

Clients should pin to the versioned path and monitor release
notes for future compatibility changes.


Rate Limits by Tier
-------------------
Free/trial tiers: model-specific; AION Indian Market Intelligence (IMI) free trial is 300 requests for one month
Builder: 15,000 requests per month
Pro: 75,000 requests per month
Power: 250,000 requests per month


Endpoint 1
----------
Method:
GET

Path:
/v1/veritas/report

Purpose:
Return the stored, tier-scoped Veritas pre-market report for a
trade date. The endpoint reads the published report artifact; it
does not run model inference.

Parameters:
- date:
  Optional trade date in YYYY-MM-DD format. Defaults to today's
  IST trade date.

Example request:

    GET /v1/veritas/report?date=2026-06-08

Response example:

    {
      "trade_date": "2026-06-08",
      "tier": "power",
      "report": {
        "indices": {
          "nifty": {
            "q10": 23843.42,
            "q50": 24036.24,
            "q90": 24165.01,
            "range_confidence": 0.832,
            "directional_lean": "NEUTRAL",
            "directional_confidence": 0.4403
          }
        },
        "model_version": "2026-05-05_lgbm_5minute_full"
      }
    }

Field descriptions:
- trade_date:
  Report trade date.
- tier:
  Entitlement tier used for scoping the report.
- report:
  Tier-scoped report payload from the canonical Veritas report store.
- q10 / q50 / q90:
  Lower, midpoint, and upper opening-band levels.
- range_confidence:
  Calibrated interval confidence target.
- directional_lean:
  BULLISH / NEUTRAL / BEARISH context.
- directional_confidence:
  Confidence in the directional layer.
- model_version:
  Deployed prediction model version.


Endpoint 2
----------
Method:
POST

Path:
/v1/analyze

Purpose:
Analyze a headline with AION Indian Market Intelligence (IMI).

Request example:

    {
      "headline": "RBI hikes repo rate by 25 bps"
    }

Response example:

    {
      "event": "RBI_RATE_HIKE",
      "confidence": 0.87,
      "sector_vector": {
        "NIFTYBANK": -0.27,
        "NIFTYIT": 0.15
      },
      "meta_factors": {
        "interest_rate": -0.42,
        "rupee": 0.11
      },
      "stakeholder_views": {
        "traders": "Rate-sensitive sectors weaken while exporters may absorb currency effects differently."
      }
    }

Field descriptions:
- event:
  Canonical event class.
- confidence:
  Structured confidence measure.
- sector_vector:
  Sector incidence vector.
- meta_factors:
  Macro-factor decomposition.
- stakeholder_views:
  Participant-specific reading of the event.


Endpoint 4
----------
Method:
POST

Path:
/v1/edge

Purpose:
Return Edge Engine tradability context for a market state.

Request example:

    {
      "underlying": "nifty"
    }

Response example:

    {
      "edge_underlying": "nifty",
      "edge_ev": 0.1421,
      "edge_conf_low": 0.0314,
      "edge_tradable": true,
      "edge_tradable_raw": true,
      "edge_motive": "model",
      "edge_model_key": "model:edge:nifty",
      "edge_shadow_mode": false
    }

Field descriptions:
- edge_underlying:
  Evaluated market.
- edge_ev:
  Edge score.
- edge_conf_low:
  Conservative lower confidence bound.
- edge_tradable:
  Final enforced tradability.
- edge_tradable_raw:
  Raw model tradability before enforcement.
- edge_motive:
  Why the verdict was produced.
- edge_model_key:
  Model routing identifier.
- edge_shadow_mode:
  Live or paper-validation state.


Error Codes
-----------
401 Unauthorized
Returned when the API key is missing, invalid, or expired.

429 Too Many Requests
Returned when the account exceeds its rate limit.

400 Bad Request
Returned when required fields are missing or malformed.

500 Internal Server Error
Returned when the server cannot complete the request.

503 Service Unavailable
Returned when a dependent service is temporarily unavailable.

Example error response:

    {
      "error": {
        "code": "RATE_LIMIT_EXCEEDED",
        "message": "Monthly quota exhausted for current plan.",
        "status": 429
      }
    }


Code Examples
-------------
cURL — Veritas:

    curl -X GET "https://api.aiondashboard.site/v1/veritas/report?date=2026-06-08" \
      -H "X-API-Key: YOUR_API_KEY"

cURL — AION Indian Market Intelligence (IMI):

    curl -X POST "https://api.aiondashboard.site/v1/analyze" \
      -H "Content-Type: application/json" \
      -H "X-API-Key: YOUR_API_KEY" \
      -d '{"headline":"RBI hikes repo rate by 25 bps"}'

Python — Veritas:

    import requests

    response = requests.get(
        "https://api.aiondashboard.site/v1/veritas/report",
        headers={"X-API-Key": "YOUR_API_KEY"},
        params={"date": "2026-06-08"},
        timeout=30,
    )
    print(response.json())

Python — Edge Engine:

    import requests

    response = requests.post(
        "https://api.aiondashboard.site/v1/edge",
        headers={"X-API-Key": "YOUR_API_KEY"},
        json={"underlying": "nifty"},
        timeout=30,
    )
    print(response.json())


Summary
-------
The AION API exposes:
- Veritas report access
- India Event Intelligence headline analysis
- Edge Engine pre-decision context

The API is versioned, key-authenticated, and designed for
workflow integration rather than retail execution prompts.


Version
-------
Document version: 1.0
Last updated: 2026-06-08
Base URL: https://api.aiondashboard.site