Technical reference / V1

Institutional Signals API.

Retrieve forward export basis and logistics snapshots, inspect historical samples, or download an institutional tear sheet.

01 / Getting started

Authentication

Use the HTTPS base URL of your KAIRO deployment, without a trailing slash. Send the key issued to your institution in the X-API-Key header for all signal and report requests. Keep the key in a server-side environment variable.

The examples use KAIRO_BASE_URL and KAIRO_API_KEY as local environment variables. Set them before running a request.

02 / Requests

Endpoints

Commodity identifiers are case-insensitive. The examples use SOYBEANS, CORN, SUGAR, SOY_MEAL, SOY_OIL and IRON_ORE.

GET /v1/signals/{commodity}/latest: Returns one snapshot as JSON. Read as_of_date and published_at before using the record as current.
GET /v1/signals/{commodity}/history: Returns a JSON array of snapshots in ascending cutoff order. Optional start_date and end_date use YYYY-MM-DD and filter the cutoff inclusively. The available sample cutoffs are 31 March and 30 April 2024. A filter with no matches returns [].
GET /v1/reports/{commodity}/latest/pdf: Returns an executive tear sheet as application/pdf. Use the Content-Disposition header for the suggested attachment filename.
GET /v1/risk/operational/{commodity}/latest: Returns published operational risk indicators (OpVaR, Expected Shortfall, and projected demurrage) across maritime export corridors.
GET /v1/rankings/facilities/{commodity}/latest: Returns the latest confirmed facility ranking. Use preview=true to explicitly request an unreconciled preview.
POST /v1/scenarios/run: Executes on-demand What-If physical and basis scenario simulation with custom parameter shocks (port precipitation, waterway draft drop, railway stoppage, harvest delay, storage deficit).
GET /v1/simulation/berth-queues: Simulates vessel waiting and demurrage at a selected facility.
GET /v1/simulation/corridor-routing: Simulates allocation of export volume across corridors under the supplied assumptions.
GET /v1/analytics/multi-commodity-matrix: Summarizes throughput and shared capacity across facilities and commodities.
GET /v1/factors/exposures/{commodity}/latest: Illustrative corridor exposures with demo=true. Empirical exposures are unavailable.
GET /v1/factors/covariance/latest: Illustrative factor covariance with demo=true. Empirical covariance is unavailable.
POST /v1/factors/risk-attribution: Illustrative portfolio risk breakdown with demo=true in the request body.
POST /v1/signals/batch: Returns latest quantitative snapshots for multiple commodities in a single round-trip.
GET /v1/arbitrage/corridor-spreads: Illustrative netbacks based on fixed assumptions. Requires demo=true.
GET /v1/integrations/excel-template: Downloads a workbook with illustrative inputs and a Power Query setup guide.
GET /v1/events/stream: Returns a finite sample event stream with demo=true. Live delivery is unavailable.
POST /v1/webhooks/subscribe: Webhook delivery is unavailable and this route returns 503.
GET /v1/webhooks/subscriptions: Webhook delivery is unavailable and this route returns 503.
GET /v1/account/usage: Account usage telemetry is unavailable and this route returns 503.
GET /v1/health Public: Returns JSON containing status (healthy), timestamp (UTC date-time), version and service.
GET /public/market-news.json Public: Returns the latest published market brief as JSON.

03 / Examples

Try a request

Client SDK / kairo-python

import kairo

# Reads KAIRO_API_KEY and KAIRO_BASE_URL from the environment.
client = kairo.KairoClient()

# Latest risk snapshot
snapshot = client.get_latest_signal("SOYBEANS")

# Spatial corridor arbitrage & netback calculation
arbitrage = client.get_corridor_arbitrage("SOYBEANS", demo=True)

# Multi-factor portfolio risk attribution
risk = client.attribute_portfolio_risk({
    "FOB_SANTOS_SOYBEANS": 0.60,
    "FOB_PARANAGUA_SOYBEANS": 0.40,
}, demo=True)

Latest snapshot, history and PDF

curl --fail-with-body \
  -H "X-API-Key: $KAIRO_API_KEY" \
  "$KAIRO_BASE_URL/v1/signals/SOYBEANS/latest"

curl --fail-with-body --get \
  -H "X-API-Key: $KAIRO_API_KEY" \
  --data-urlencode 'start_date=2024-04-01' \
  --data-urlencode 'end_date=2024-04-30' \
  "$KAIRO_BASE_URL/v1/signals/SOYBEANS/history"

curl --fail \
  -H "X-API-Key: $KAIRO_API_KEY" \
  --output kairo-soybeans.pdf \
  "$KAIRO_BASE_URL/v1/reports/SOYBEANS/latest/pdf"

Snapshot / Illustrative values

{
  "feed_id": "EXAMPLE-SOYBEANS-20240430",
  "run_id": "RUN-EXAMPLE-SOYBEANS-20240430",
  "commodity": "SOYBEANS",
  "as_of_date": "2024-04-30",
  "published_at": "2024-05-01T12:00:00Z",
  "market_regime": "NORMAL_FLOW",
  "is_demo": false,
  "evidence_stage": "retrospective_proxy_evaluation",
  "national_port_utilization_forecast": {
    "p10": 0.55,
    "p50": 0.63,
    "p90": 0.74,
    "std_dev": 0.07
  },
  "corridors": [
    {
      "corridor_id": "SANTOS",
      "saturation_probability": 0.12,
      "projected_waiting_days": {
        "p10": 1.0,
        "p50": 2.0,
        "p90": 4.0,
        "std_dev": 1.1
      },
      "freight_pressure_index": 32.0
    }
  ],
  "basis_dislocation_curve": [
    {
      "target_period": "2024-05",
      "projected_basis_cents_bu": {
        "p10": 42.0,
        "p50": 50.0,
        "p90": 58.0,
        "std_dev": 6.2
      },
      "historical_directional_hit_ratio": 0.5,
      "out_of_sample_ic": 0.0
    }
  ],
  "operational_stress_indicators": null,
  "operational_risk": null,
  "input_manifest_hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "provenance_hash": "0000000000000000000000000000000000000000000000000000000000000000",
  "disclaimer": "Illustrative institutional research example."
}

04 / Response contract

Read a snapshot

InstitutionalRiskFeedSnapshot is the JSON object returned by the latest endpoint and the element type of the history array.

feed_id string: Identifier for the snapshot.
run_id string: Unique execution run identifier bound across JSON, API, and PDF.
commodity string: Commodity identifier returned in uppercase.
as_of_date date: Information cutoff in YYYY-MM-DD.
published_at date-time: Publication timestamp with timezone.
market_regime enum: NORMAL_FLOW, ELEVATED_LOGISTIC_PRESSURE, CRITICAL_PORT_CONGESTION or SEASONAL_DEPLETION.
is_demo boolean: Flag indicating whether the snapshot is a demonstration sample.
evidence_stage string: Empirical evidence classification (e.g. retrospective_proxy_evaluation or conditioned_physical_simulation).
national_port_utilization_forecast QuantileForecast: National port utilization, expressed as a fraction from 0 to 1.
corridors CorridorPressureMetric[]: Logistics indicators by export corridor.
basis_dislocation_curve BasisDislocationSignal[]: One forecast entry per target month.
operational_stress_indicators OperationalDisruptionScores | null: High-frequency operational physical indices.
operational_risk OperationalRiskSummary | null: Operational risk and demurrage indicators.
input_manifest_hash string: Cryptographic SHA-256 hash of the input data manifest.
provenance_hash string: SHA-256 identifier for provenance tracking.
disclaimer string: Terms accompanying the research snapshot.

QuantileForecast

p10, p50 and p90 are numeric percentiles. std_dev is the standard deviation, in the same units as the percentiles.

CorridorPressureMetric

corridor_id string: Export corridor identifier, for example SANTOS.
saturation_probability number: Probability of corridor saturation on a 0 to 1 scale.
projected_waiting_days QuantileForecast: Projected vessel waiting time in days.
freight_pressure_index number: Transport pressure on a 0 to 100 scale.

BasisDislocationSignal

target_period string: Delivery month in YYYY-MM.
projected_basis_cents_bu QuantileForecast: FOB export basis against the benchmark, expressed in US cents per bushel by this contract.
historical_directional_hit_ratio number: Directional hit ratio field, from 0 to 1.
out_of_sample_ic number: Rank information coefficient field, from −1 to 1.

The values in the example are illustrative, including the two research metric fields.

Market brief response

schema_version is 1. edition is a YYYY-MM-DD date or null. items is an array of up to six entries with title, summary, source, topic, an HTTPS url and published_on (YYYY-MM-DD). If an edition is unavailable, edition is null and items is empty.

05 / Status codes

Handle the response

200: Success. Read JSON or save the PDF, depending on the endpoint.
401: The key is missing or invalid. Check the X-API-Key header.
404: The path or commodity is unsupported. Check the endpoint and the identifier.
422: The request parameters failed validation. Check the date format on history requests.
503: Institutional access is unavailable on the deployment.

For these error responses, read the JSON detail field. It is a message for 401, 404 and 503, or a list of validation issues for 422.