# `POST /v1/decisions` — Evaluate typed questions

Part of the [Bkper AI Gateway API](https://bkper.com/docs/api/ai-gateway.md). Read its guide for authentication, conventions, and examples.

A decision model evaluates a shared JSON-compatible state against independent noul, choice, and score questions. The result contains one typed answer per question ID; thresholds and actions stay in your code. Requests do not stream or retain state. Request and answer shapes follow the TypeSafe System One API, so TypeSafe SDKs work with base URL https://ai.bkper.app.

## Operation contract

```json
{
  "tags": [
    "Decisions"
  ],
  "operationId": "createDecision",
  "summary": "Evaluate typed questions",
  "description": "A decision model evaluates a shared JSON-compatible state against independent noul, choice, and score questions. The result contains one typed answer per question ID; thresholds and actions stay in your code. Requests do not stream or retain state. Request and answer shapes follow the TypeSafe System One API, so TypeSafe SDKs work with base URL https://ai.bkper.app.",
  "security": [
    {
      "bkperBearer": []
    }
  ],
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "$ref": "#/components/schemas/EvaluationRequest"
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "Typed answers for every question",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationResult"
          }
        }
      }
    },
    "400": {
      "description": "Invalid decision request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "401": {
      "description": "Missing or invalid Bkper bearer token",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "402": {
      "description": "Subscription payment is overdue",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "403": {
      "description": "Bkper AI entitlement is unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "429": {
      "description": "Monthly allowance exhausted or provider throttled",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "499": {
      "description": "Client aborted the request",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "502": {
      "description": "Provider or transport failure",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    },
    "503": {
      "description": "Decision model provider is temporarily overloaded or quota usage is unavailable",
      "content": {
        "application/json": {
          "schema": {
            "$ref": "#/components/schemas/EvaluationError"
          }
        }
      }
    }
  },
  "parameters": [
    {
      "name": "bkper-ai-source",
      "in": "header",
      "required": false,
      "description": "Stable lowercase client or application identifier used for usage attribution. Invalid values are recorded as unknown.",
      "schema": {
        "type": "string",
        "pattern": "^[a-z0-9][a-z0-9._-]{0,127}$"
      }
    }
  ]
}
```

## Schemas

### EvaluationRequest

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "minLength": 1,
      "description": "Canonical decision model ID or accepted compatibility alias."
    },
    "state": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object",
          "additionalProperties": {}
        }
      ],
      "description": "Shared state evaluated by every question."
    },
    "questions": {
      "type": "object",
      "additionalProperties": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/NoulEvaluationQuestion"
          },
          {
            "$ref": "#/components/schemas/ChoiceEvaluationQuestion"
          },
          {
            "$ref": "#/components/schemas/ScoreEvaluationQuestion"
          }
        ],
        "discriminator": {
          "propertyName": "type",
          "mapping": {
            "noul": "#/components/schemas/NoulEvaluationQuestion",
            "choice": "#/components/schemas/ChoiceEvaluationQuestion",
            "score": "#/components/schemas/ScoreEvaluationQuestion"
          }
        }
      },
      "description": "Nonempty map of independently evaluated named questions.",
      "minProperties": 1
    }
  },
  "required": [
    "model",
    "state",
    "questions"
  ],
  "additionalProperties": false
}
```

### NoulEvaluationQuestion

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "noul"
      ]
    },
    "instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object",
          "additionalProperties": {}
        }
      ],
      "description": "A string, JSON object, or JSON array."
    },
    "criteria": {
      "type": "object",
      "properties": {
        "true": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {}
            },
            {
              "type": "object",
              "additionalProperties": {}
            }
          ],
          "description": "A string, JSON object, or JSON array."
        },
        "false": {
          "anyOf": [
            {
              "type": "string"
            },
            {
              "type": "array",
              "items": {}
            },
            {
              "type": "object",
              "additionalProperties": {}
            }
          ],
          "description": "A string, JSON object, or JSON array."
        }
      }
    }
  },
  "required": [
    "type",
    "instructions"
  ],
  "additionalProperties": false
}
```

### ChoiceEvaluationQuestion

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "choice"
      ]
    },
    "instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object",
          "additionalProperties": {}
        }
      ],
      "description": "A string, JSON object, or JSON array."
    },
    "criteria": {
      "type": "object",
      "additionalProperties": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {}
          },
          {
            "type": "object",
            "additionalProperties": {}
          },
          {
            "type": "null"
          }
        ],
        "description": "Text, structured JSON, or null interpreted as a description."
      },
      "minProperties": 1,
      "maxProperties": 255
    }
  },
  "required": [
    "type",
    "instructions",
    "criteria"
  ],
  "additionalProperties": false
}
```

### ScoreEvaluationQuestion

```json
{
  "type": "object",
  "properties": {
    "type": {
      "type": "string",
      "enum": [
        "score"
      ]
    },
    "instructions": {
      "anyOf": [
        {
          "type": "string"
        },
        {
          "type": "array",
          "items": {}
        },
        {
          "type": "object",
          "additionalProperties": {}
        }
      ],
      "description": "A string, JSON object, or JSON array."
    },
    "criteria": {
      "type": "array",
      "items": {
        "anyOf": [
          {
            "type": "string"
          },
          {
            "type": "array",
            "items": {}
          },
          {
            "type": "object",
            "additionalProperties": {}
          }
        ],
        "description": "A string, JSON object, or JSON array."
      },
      "minItems": 2,
      "maxItems": 10
    }
  },
  "required": [
    "type",
    "instructions",
    "criteria"
  ],
  "additionalProperties": false
}
```

### EvaluationResult

```json
{
  "type": "object",
  "properties": {
    "model": {
      "type": "string",
      "description": "Concrete model revision that produced these answers, such as jev-1.13.0."
    },
    "answers": {
      "type": "object",
      "additionalProperties": {
        "$ref": "#/components/schemas/EvaluationAnswer"
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "input_tokens": {
          "type": "integer",
          "minimum": 0
        },
        "output_tokens": {
          "type": "integer",
          "minimum": 0
        }
      },
      "required": [
        "input_tokens",
        "output_tokens"
      ]
    }
  },
  "required": [
    "model",
    "answers",
    "usage"
  ]
}
```

### EvaluationAnswer

```json
{
  "oneOf": [
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "noul"
          ]
        },
        "noul": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "type",
        "noul"
      ]
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "choice"
          ]
        },
        "choice": {
          "type": "string"
        },
        "probabilities": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "description": "Probability distribution keyed by option or zero-based score level."
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "type",
        "choice",
        "probabilities",
        "confidence"
      ]
    },
    {
      "type": "object",
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "score"
          ]
        },
        "score": {
          "type": "number",
          "minimum": 0
        },
        "legend": {
          "type": "object",
          "additionalProperties": {
            "type": "string"
          }
        },
        "probabilities": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          },
          "description": "Probability distribution keyed by option or zero-based score level."
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      },
      "required": [
        "type",
        "score",
        "legend",
        "probabilities",
        "confidence"
      ]
    }
  ]
}
```

### EvaluationError

```json
{
  "type": "object",
  "properties": {
    "error": {
      "type": "object",
      "properties": {
        "message": {
          "type": "string"
        },
        "type": {
          "type": "string"
        },
        "param": {
          "type": [
            "string",
            "null"
          ]
        },
        "code": {
          "type": "string"
        }
      },
      "required": [
        "message",
        "type",
        "param",
        "code"
      ]
    }
  },
  "required": [
    "error"
  ]
}
```

## Authentication

```json
{
  "bkperBearer": {
    "type": "http",
    "scheme": "bearer",
    "bearerFormat": "Bkper OAuth access token",
    "description": "Send a Bkper OAuth access token. See [token setup](https://bkper.com/docs/api/ai-gateway#get-a-token-for-local-testing)."
  }
}
```