UnderSky Docs

Decisions API (Jev / System One)

Reference for POST /v1/decisions and the path alias POST /api/alpha/decisions — TypeSafe Jev System One with pass-through billing, available to every API key.

Evaluate a state with typed questions (noul, choice, score) via TypeSafe Jev. UnderSky authenticates with your API key and bills at upstream pass-through cost.

Every valid API key can call the Jev models listed below, with or without the openrouter/ prefix. Any other model on this endpoint is admin-only (or ops disaster-recovery); ordinary API keys receive 403 / unsupported_model. Other OpenRouter access stays admin-only.

Endpoints

POST https://api.undersky.ai/v1/decisions
POST https://api.undersky.ai/api/alpha/decisions

/api/alpha/decisions is a path alias for the same handler, auth, RPM bucket, and billing as /v1/decisions.

Authentication

Use any valid UnderSky API key:

  • Authorization: Bearer sk-your-api-key

Parameters

Decisions-native body. Required fields:

ParameterTypeRequiredDescription
modelstringYesJev model ID (see below).
statestring | object | arrayYesContent to evaluate.
questionsobjectYesMap of question id → typed question (noul / choice / score).

Each question requires type and instructions. A choice question also requires a criteria object mapping option IDs to descriptions; a score question requires an ordered array of criteria descriptions.

Supported models

Model IDName
~typesafe/jev-latestJev Latest
typesafe/jev-1.13Jev 1.13

Pricing

Pass-through: charged from upstream usage (input_tokens, output_tokens, cost) in UnderSky credits. See Pricing.

Rate limits

Shares the Chat RPM tier bucket (same profile as Chat Completions). The /api/alpha/decisions alias maps to the same /v1/decisions key. See Rate Limits.

Request (curl)

curl -X POST https://api.undersky.ai/v1/decisions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "~typesafe/jev-latest",
    "state": {
      "ticket": "Customer paid twice for the same order",
      "amount_usd": 48
    },
    "questions": {
      "should_refund": {
        "type": "noul",
        "instructions": "Should we issue a full refund?"
      },
      "primary_reason": {
        "type": "choice",
        "instructions": "Primary reason category",
        "criteria": {
          "duplicate_charge": "The same order was charged more than once.",
          "defective": "The product was defective.",
          "late_delivery": "The delivery was late.",
          "other": "Another reason applies."
        }
      },
      "confidence": {
        "type": "score",
        "instructions": "Confidence that the refund is warranted (0-1)",
        "criteria": ["A full refund is not warranted.", "A full refund is warranted."]
      }
    }
  }'

Path alias (same body):

curl -X POST https://api.undersky.ai/api/alpha/decisions \
  -H "Authorization: Bearer sk-your-api-key" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13",
    "state": "Blank checkout page after payment redirect",
    "questions": {
      "is_incident": {
        "type": "noul",
        "instructions": "Is this a production incident?"
      }
    }
  }'

Response

Successful responses typically include answers plus usage (token counts and cost). Exact fields follow the upstream Decisions contract.

Notes

  • Requires the Decisions provider to be configured on the API (OPENROUTER_API_KEY).
  • Upstream timeout is 60 seconds.
  • Chat / Responses / Messages remain on their own endpoints; Decisions is only for typed Jev evaluations.

On this page