Evaluate typed questions

POST

/v1/evaluations

Evaluates a shared JSON-compatible state against independent boolean, choice, and score questions. The result contains one typed answer per question ID. Evaluation does not stream or retain state.

Authorizations

• bkperBearer

Parameters

Header Parameters

bkper-ai-source

string

/^[a-z0-9][a-z0-9._-]{0,127}$/

Stable lowercase client or application identifier used for usage attribution. Invalid values are recorded as unknown.

Request Body ^required

object

model

required

Canonical evaluation model ID or accepted compatibility alias.

string

>= 1 characters

state

required

Any of:

string

string

Array

Array

object

object

key

additional properties

questions

required

Nonempty map of independently evaluated named questions.

object

>= 1 properties

key

additional properties

One of: discriminator: type

object

object

type

required

string

Allowed values: boolean

instructions

required

Any of:

string

string

Array

Array

object

object

key

additional properties

criteria

object

true

Any of:

string

string

Array

Array

object

object

key

additional properties

null

null

false

Any of:

string

string

Array

Array

object

object

key

additional properties

null

null

object

object

type

required

string

Allowed values: choice

instructions

required

Any of:

string

string

Array

Array

object

object

key

additional properties

criteria

required

object

>= 1 properties

key

additional properties

Any of:

string

string

Array

Array

object

object

key

additional properties

null

null

object

object

type

required

string

Allowed values: score

instructions

required

Any of:

string

string

Array

Array

object

object

key

additional properties

criteria

required

Array

>= 2 items

Any of:

string

string

Array

Array

object

object

key

additional properties

null

null

Responses

200

Completed evaluation

object

model

required

Canonical Bkper evaluation model ID.

string

answers

required

object

key

additional properties

One of:

object

object

type

required

string

Allowed values: boolean

probability

required

number

<= 1

object

object

type

required

string

Allowed values: choice

choice

required

string

probabilities

Probability distribution keyed by option or zero-based score level.

object

key

additional properties

number

<= 1

object

object

type

required

string

Allowed values: score

score

required

number

probabilities

Probability distribution keyed by option or zero-based score level.

object

key

additional properties

number

<= 1

usage

required

object

input_tokens

required

integer

output_tokens

required

integer

total_tokens

required

integer

provider_metadata

Optional provider-specific metadata. TypeSafe confidence is separate from answer probabilities.

object

typesafe

required

object

confidence

required

object

key

additional properties

number

<= 1

400

Invalid evaluation request

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

401

Missing or invalid Bkper bearer token

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

402

Subscription payment is overdue

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

403

Bkper AI entitlement is unavailable

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

429

Monthly allowance exhausted or provider throttled

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

499

Client aborted the request

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

502

Provider or transport failure

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string

503

Evaluation provider is temporarily overloaded

object

error

required

object

message

required

string

type

required

string

param

required

string | null

code

required

string