Skip to Content

Evaluate state with TypeSafe Jev

POSThttps://api.respan.ai/api/typesafe/v1/systemone

Evaluate a state against named questions and return TypeSafe’s answers keyed by question name. Respan removes the typesafe/ model prefix and respan_params before forwarding the request, then returns the TypeSafe JSON response unchanged.

Authenticate with your Respan key and supply a TypeSafe key through respan_params.credential_override or Respan Settings > Providers. Use the model name without typesafe/ as the override key: jev-1.13.0 for typesafe/jev-1.13.0. To use a saved key, select Use saved TypeSafe key and omit credential_override. TypeSafe does not use Respan gateway credits.

The refund example uses noul, a probability from 0 to 1. See the TypeSafe API reference  for question types. Streaming is unsupported: stream: true returns HTTP 400. Retry HTTP 429 (rate limit) and 529 (overloaded) with exponential backoff.

Servers

https://api.respan.ai: Respan API Server

Authentication

RespanApiKey

Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.

HTTP scheme: bearer; format: Respan API key.

HTTP
Authorization: Bearer $RESPAN_API_KEY

Request body

A request body is required.

application/json

Field Type Requirement Description and constraints
$ object or object Required body
-
$ (anyOf 1) object Schema variant
Supply a TypeSafe API key with this request. Authenticate with your Respan key in Authorization.
Reference: #/components/schemas/TypeSafeRequestCredentials
$ (anyOf 1).respan_params object Required in parent
Request-scoped TypeSafe credentials. Respan removes these parameters before forwarding the request.
Additional properties are allowed
$ (anyOf 1).respan_params.credential_override object Required in parent
Map the model name without the typesafe/ prefix, such as jev-1.13.0, to your TypeSafe credentials.
Minimum properties: 1
Example: {"jev-1.13.0":{"api_key":"YOUR_TYPESAFE_API_KEY"}}
$ (anyOf 1).respan_params.credential_override.<key> object Map value
-
$ (anyOf 1).respan_params.credential_override.<key>.api_key string Required in parent
Your TypeSafe API key.
Format: password
Write only
$ (anyOf 1).model string Required in parent
Respan model ID, for example typesafe/jev-1.13.0.
Example: "typesafe/jev-1.13.0"
$ (anyOf 1).state string or object or array<any> Required in parent
Text or structured context supplied to Jev.
Reference: #/components/schemas/TypeSafeContent
$ (anyOf 1).state (oneOf 1) string Schema variant
-
$ (anyOf 1).state (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).state (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).state (oneOf 3)[] any Array item
-
$ (anyOf 1).questions object Required in parent
Named questions evaluated against the same state.
Minimum properties: 1
$ (anyOf 1).questions.<key> object or object or object Map value
-
$ (anyOf 1).questions.<key> (oneOf 1) object Schema variant
A yes/no judgment expressed as a probability.
Reference: #/components/schemas/TypeSafeNoulQuestion
$ (anyOf 1).questions.<key> (oneOf 1).type string Required in parent
Allowed: "noul"
$ (anyOf 1).questions.<key> (oneOf 1).instructions string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 1).questions.<key> (oneOf 1).instructions (oneOf 1) string or null Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 1).instructions (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 1).instructions (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 1).instructions (oneOf 3)[] any Array item
-
$ (anyOf 1).questions.<key> (oneOf 1).criteria object or null Optional
Optional guidance for yes and no.
$ (anyOf 1).questions.<key> (oneOf 1).criteria.true string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 1).questions.<key> (oneOf 1).criteria.true (oneOf 1) string or null Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 1).criteria.true (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 1).criteria.true (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 1).criteria.true (oneOf 3)[] any Array item
-
$ (anyOf 1).questions.<key> (oneOf 1).criteria.false string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 1).questions.<key> (oneOf 1).criteria.false (oneOf 1) string or null Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 1).criteria.false (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 1).criteria.false (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 1).criteria.false (oneOf 3)[] any Array item
-
$ (anyOf 1).questions.<key> (oneOf 2) object Schema variant
Select an option from the supplied criteria.
Reference: #/components/schemas/TypeSafeChoiceQuestion
$ (anyOf 1).questions.<key> (oneOf 2).type string Required in parent
Allowed: "choice"
$ (anyOf 1).questions.<key> (oneOf 2).instructions string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 1).questions.<key> (oneOf 2).instructions (oneOf 1) string or null Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 2).instructions (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 2).instructions (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 2).instructions (oneOf 3)[] any Array item
-
$ (anyOf 1).questions.<key> (oneOf 2).criteria object Required in parent
Option names mapped to descriptions. Use null for an option without a description.
Maximum properties: 255
$ (anyOf 1).questions.<key> (oneOf 2).criteria.<key> string or null or object or array<any> Map value
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 1).questions.<key> (oneOf 2).criteria.<key> (oneOf 1) string or null Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 2).criteria.<key> (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 2).criteria.<key> (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 2).criteria.<key> (oneOf 3)[] any Array item
-
$ (anyOf 1).questions.<key> (oneOf 3) object Schema variant
Evaluate the state on an ordered rubric.
Reference: #/components/schemas/TypeSafeScoreQuestion
$ (anyOf 1).questions.<key> (oneOf 3).type string Required in parent
Allowed: "score"
$ (anyOf 1).questions.<key> (oneOf 3).instructions string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 1).questions.<key> (oneOf 3).instructions (oneOf 1) string or null Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 3).instructions (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 3).instructions (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 3).instructions (oneOf 3)[] any Array item
-
$ (anyOf 1).questions.<key> (oneOf 3).criteria array<string or object or array<any>> Required in parent
Rubric levels in order, starting at index 0.
Minimum items: 2
Maximum items: 10
$ (anyOf 1).questions.<key> (oneOf 3).criteria[] string or object or array<any> Array item
Text or structured context supplied to Jev.
Reference: #/components/schemas/TypeSafeContent
$ (anyOf 1).questions.<key> (oneOf 3).criteria[] (oneOf 1) string Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 3).criteria[] (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 1).questions.<key> (oneOf 3).criteria[] (oneOf 3) array<any> Schema variant
-
$ (anyOf 1).questions.<key> (oneOf 3).criteria[] (oneOf 3)[] any Array item
-
$ (anyOf 2) object Schema variant
Use a TypeSafe key saved in Respan Settings > Providers.
Reference: #/components/schemas/TypeSafeSavedCredentials
$ (anyOf 2).respan_params object Optional
Optional Respan parameters, removed before forwarding the request.
Additional properties are allowed
$ (anyOf 2).respan_params.credential_override object Optional
Override the saved key for this request. Use the model name without the typesafe/ prefix, such as jev-1.13.0.
Example: {"jev-1.13.0":{"api_key":"YOUR_TYPESAFE_API_KEY"}}
$ (anyOf 2).respan_params.credential_override.<key> object Map value
-
$ (anyOf 2).respan_params.credential_override.<key>.api_key string Required in parent
Your TypeSafe API key.
Format: password
Write only
$ (anyOf 2).model string Required in parent
Respan model ID, for example typesafe/jev-1.13.0.
Example: "typesafe/jev-1.13.0"
$ (anyOf 2).state string or object or array<any> Required in parent
Text or structured context supplied to Jev.
Reference: #/components/schemas/TypeSafeContent
$ (anyOf 2).state (oneOf 1) string Schema variant
-
$ (anyOf 2).state (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).state (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).state (oneOf 3)[] any Array item
-
$ (anyOf 2).questions object Required in parent
Named questions evaluated against the same state.
Minimum properties: 1
$ (anyOf 2).questions.<key> object or object or object Map value
-
$ (anyOf 2).questions.<key> (oneOf 1) object Schema variant
A yes/no judgment expressed as a probability.
Reference: #/components/schemas/TypeSafeNoulQuestion
$ (anyOf 2).questions.<key> (oneOf 1).type string Required in parent
Allowed: "noul"
$ (anyOf 2).questions.<key> (oneOf 1).instructions string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 2).questions.<key> (oneOf 1).instructions (oneOf 1) string or null Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 1).instructions (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 1).instructions (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 1).instructions (oneOf 3)[] any Array item
-
$ (anyOf 2).questions.<key> (oneOf 1).criteria object or null Optional
Optional guidance for yes and no.
$ (anyOf 2).questions.<key> (oneOf 1).criteria.true string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 2).questions.<key> (oneOf 1).criteria.true (oneOf 1) string or null Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 1).criteria.true (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 1).criteria.true (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 1).criteria.true (oneOf 3)[] any Array item
-
$ (anyOf 2).questions.<key> (oneOf 1).criteria.false string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 2).questions.<key> (oneOf 1).criteria.false (oneOf 1) string or null Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 1).criteria.false (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 1).criteria.false (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 1).criteria.false (oneOf 3)[] any Array item
-
$ (anyOf 2).questions.<key> (oneOf 2) object Schema variant
Select an option from the supplied criteria.
Reference: #/components/schemas/TypeSafeChoiceQuestion
$ (anyOf 2).questions.<key> (oneOf 2).type string Required in parent
Allowed: "choice"
$ (anyOf 2).questions.<key> (oneOf 2).instructions string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 2).questions.<key> (oneOf 2).instructions (oneOf 1) string or null Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 2).instructions (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 2).instructions (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 2).instructions (oneOf 3)[] any Array item
-
$ (anyOf 2).questions.<key> (oneOf 2).criteria object Required in parent
Option names mapped to descriptions. Use null for an option without a description.
Maximum properties: 255
$ (anyOf 2).questions.<key> (oneOf 2).criteria.<key> string or null or object or array<any> Map value
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 2).questions.<key> (oneOf 2).criteria.<key> (oneOf 1) string or null Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 2).criteria.<key> (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 2).criteria.<key> (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 2).criteria.<key> (oneOf 3)[] any Array item
-
$ (anyOf 2).questions.<key> (oneOf 3) object Schema variant
Evaluate the state on an ordered rubric.
Reference: #/components/schemas/TypeSafeScoreQuestion
$ (anyOf 2).questions.<key> (oneOf 3).type string Required in parent
Allowed: "score"
$ (anyOf 2).questions.<key> (oneOf 3).instructions string or null or object or array<any> Optional
Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced .
Reference: #/components/schemas/TypeSafeEntry
$ (anyOf 2).questions.<key> (oneOf 3).instructions (oneOf 1) string or null Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 3).instructions (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 3).instructions (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 3).instructions (oneOf 3)[] any Array item
-
$ (anyOf 2).questions.<key> (oneOf 3).criteria array<string or object or array<any>> Required in parent
Rubric levels in order, starting at index 0.
Minimum items: 2
Maximum items: 10
$ (anyOf 2).questions.<key> (oneOf 3).criteria[] string or object or array<any> Array item
Text or structured context supplied to Jev.
Reference: #/components/schemas/TypeSafeContent
$ (anyOf 2).questions.<key> (oneOf 3).criteria[] (oneOf 1) string Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 3).criteria[] (oneOf 2) object Schema variant
Additional properties are allowed
$ (anyOf 2).questions.<key> (oneOf 3).criteria[] (oneOf 3) array<any> Schema variant
-
$ (anyOf 2).questions.<key> (oneOf 3).criteria[] (oneOf 3)[] any Array item
-

OpenAPI request schema

{
  "anyOf": [
    {
      "$ref": "#/components/schemas/TypeSafeRequestCredentials"
    },
    {
      "$ref": "#/components/schemas/TypeSafeSavedCredentials"
    }
  ]
}
Example
JSON
{ "respan_params": { "credential_override": { "jev-1.13.0": { "api_key": "YOUR_TYPESAFE_API_KEY" } } }, "model": "typesafe/jev-1.13.0", "state": "I want a refund.", "questions": { "is_refund": { "type": "noul", "instructions": "Is the customer asking for a refund?" } } }

Responses

200

TypeSafe evaluation result. The example is from the refund request; probabilities and token counts can vary.

application/json

Field Type Requirement Description and constraints
$ object Body
-
model string Required in parent
Model identifier returned by TypeSafe.
answers object Required in parent
Results keyed by the names supplied in questions.
answers.<key> object or object or object Map value
-
answers.<key> (oneOf 1) object Schema variant
Reference: #/components/schemas/TypeSafeNoulAnswer
answers.<key> (oneOf 1).type string Required in parent
Allowed: "noul"
answers.<key> (oneOf 1).noul number Required in parent
Probability of yes: 0 means no, 1 means yes.
Minimum: 0
Maximum: 1
answers.<key> (oneOf 2) object Schema variant
Reference: #/components/schemas/TypeSafeChoiceAnswer
answers.<key> (oneOf 2).type string Required in parent
Allowed: "choice"
answers.<key> (oneOf 2).choice string Required in parent
Selected option name.
answers.<key> (oneOf 2).probabilities object Required in parent
-
answers.<key> (oneOf 2).probabilities.<key> number Map value
Minimum: 0
Maximum: 1
answers.<key> (oneOf 2).confidence number Required in parent
Minimum: 0
Maximum: 1
answers.<key> (oneOf 3) object Schema variant
Reference: #/components/schemas/TypeSafeScoreAnswer
answers.<key> (oneOf 3).type string Required in parent
Allowed: "score"
answers.<key> (oneOf 3).score number Required in parent
Probability-weighted level index; may be fractional.
answers.<key> (oneOf 3).legend object Required in parent
Level indices mapped to rubric descriptions.
answers.<key> (oneOf 3).legend.<key> string or object or array<any> Map value
Text or structured context supplied to Jev.
Reference: #/components/schemas/TypeSafeContent
answers.<key> (oneOf 3).legend.<key> (oneOf 1) string Schema variant
-
answers.<key> (oneOf 3).legend.<key> (oneOf 2) object Schema variant
Additional properties are allowed
answers.<key> (oneOf 3).legend.<key> (oneOf 3) array<any> Schema variant
-
answers.<key> (oneOf 3).legend.<key> (oneOf 3)[] any Array item
-
answers.<key> (oneOf 3).probabilities object Required in parent
-
answers.<key> (oneOf 3).probabilities.<key> number Map value
Minimum: 0
Maximum: 1
answers.<key> (oneOf 3).confidence number Required in parent
Minimum: 0
Maximum: 1
usage object Required in parent
-
usage.input_tokens integer Required in parent
-
usage.output_tokens integer Required in parent
-

OpenAPI response schema

{
  "type": "object",
  "required": [
    "model",
    "answers",
    "usage"
  ],
  "properties": {
    "model": {
      "type": "string",
      "description": "Model identifier returned by TypeSafe."
    },
    "answers": {
      "type": "object",
      "description": "Results keyed by the names supplied in questions.",
      "additionalProperties": {
        "oneOf": [
          {
            "$ref": "#/components/schemas/TypeSafeNoulAnswer"
          },
          {
            "$ref": "#/components/schemas/TypeSafeChoiceAnswer"
          },
          {
            "$ref": "#/components/schemas/TypeSafeScoreAnswer"
          }
        ]
      }
    },
    "usage": {
      "type": "object",
      "properties": {
        "input_tokens": {
          "type": "integer"
        },
        "output_tokens": {
          "type": "integer"
        }
      },
      "required": [
        "input_tokens",
        "output_tokens"
      ]
    }
  }
}
Example
JSON
{ "model": "jev-1.13.0", "answers": { "is_refund": { "type": "noul", "noul": 0.99 } }, "usage": { "input_tokens": 279, "output_tokens": 22 } }

400

Invalid request, including stream: true.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

401

No TypeSafe provider credentials are available, or TypeSafe rejected the provider API key.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

403

Missing, invalid, or expired Respan API key.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

422

TypeSafe rejected the request body or question format.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

429

Rate limit exceeded. Retry with exponential backoff.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

529

TypeSafe is temporarily overloaded. Retry with exponential backoff.

application/json

Field Type Requirement Description and constraints
$ object Body
Additional properties are allowed

OpenAPI response schema

{
  "type": "object",
  "additionalProperties": true
}

OpenAPI source

The operation and referenced components below retain the complete OpenAPI definitions, including constraints and examples.

OpenAPI operation

{
  "summary": "Evaluate state with TypeSafe Jev",
  "operationId": "typesafe_systemone",
  "tags": [
    "TypeSafe Gateway"
  ],
  "description": "Evaluate a state against named questions and return TypeSafe's answers keyed by question name. Respan removes the `typesafe/` model prefix and `respan_params` before forwarding the request, then returns the TypeSafe JSON response unchanged.\n\nAuthenticate with your Respan key and supply a TypeSafe key through `respan_params.credential_override` or Respan Settings > Providers. Use the model name without `typesafe/` as the override key: `jev-1.13.0` for `typesafe/jev-1.13.0`. To use a saved key, select **Use saved TypeSafe key** and omit `credential_override`. TypeSafe does not use Respan gateway credits.\n\nThe refund example uses `noul`, a probability from 0 to 1. See the [TypeSafe API reference](https://docs.typesafe.ai/api) for question types. Streaming is unsupported: `stream: true` returns HTTP 400. Retry HTTP 429 (rate limit) and 529 (overloaded) with exponential backoff.",
  "requestBody": {
    "required": true,
    "content": {
      "application/json": {
        "schema": {
          "anyOf": [
            {
              "$ref": "#/components/schemas/TypeSafeRequestCredentials"
            },
            {
              "$ref": "#/components/schemas/TypeSafeSavedCredentials"
            }
          ]
        },
        "example": {
          "respan_params": {
            "credential_override": {
              "jev-1.13.0": {
                "api_key": "YOUR_TYPESAFE_API_KEY"
              }
            }
          },
          "model": "typesafe/jev-1.13.0",
          "state": "I want a refund.",
          "questions": {
            "is_refund": {
              "type": "noul",
              "instructions": "Is the customer asking for a refund?"
            }
          }
        }
      }
    }
  },
  "responses": {
    "200": {
      "description": "TypeSafe evaluation result. The example is from the refund request; probabilities and token counts can vary.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "required": [
              "model",
              "answers",
              "usage"
            ],
            "properties": {
              "model": {
                "type": "string",
                "description": "Model identifier returned by TypeSafe."
              },
              "answers": {
                "type": "object",
                "description": "Results keyed by the names supplied in questions.",
                "additionalProperties": {
                  "oneOf": [
                    {
                      "$ref": "#/components/schemas/TypeSafeNoulAnswer"
                    },
                    {
                      "$ref": "#/components/schemas/TypeSafeChoiceAnswer"
                    },
                    {
                      "$ref": "#/components/schemas/TypeSafeScoreAnswer"
                    }
                  ]
                }
              },
              "usage": {
                "type": "object",
                "properties": {
                  "input_tokens": {
                    "type": "integer"
                  },
                  "output_tokens": {
                    "type": "integer"
                  }
                },
                "required": [
                  "input_tokens",
                  "output_tokens"
                ]
              }
            }
          },
          "example": {
            "model": "jev-1.13.0",
            "answers": {
              "is_refund": {
                "type": "noul",
                "noul": 0.99
              }
            },
            "usage": {
              "input_tokens": 279,
              "output_tokens": 22
            }
          }
        }
      }
    },
    "400": {
      "description": "Invalid request, including stream: true.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "401": {
      "description": "No TypeSafe provider credentials are available, or TypeSafe rejected the provider API key.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "403": {
      "description": "Missing, invalid, or expired Respan API key.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "422": {
      "description": "TypeSafe rejected the request body or question format.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "429": {
      "description": "Rate limit exceeded. Retry with exponential backoff.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    },
    "529": {
      "description": "TypeSafe is temporarily overloaded. Retry with exponential backoff.",
      "content": {
        "application/json": {
          "schema": {
            "type": "object",
            "additionalProperties": true
          }
        }
      }
    }
  },
  "security": [
    {
      "RespanApiKey": []
    }
  ]
}

OpenAPI path metadata

{}

Referenced OpenAPI components

{
  "schemas": {
    "TypeSafeChoiceAnswer": {
      "type": "object",
      "required": [
        "type",
        "choice",
        "probabilities",
        "confidence"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "choice"
          ]
        },
        "choice": {
          "type": "string",
          "description": "Selected option name."
        },
        "probabilities": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "TypeSafeChoiceQuestion": {
      "type": "object",
      "description": "Select an option from the supplied criteria.",
      "required": [
        "type",
        "criteria"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "choice"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        },
        "criteria": {
          "type": "object",
          "description": "Option names mapped to descriptions. Use null for an option without a description.",
          "additionalProperties": {
            "$ref": "#/components/schemas/TypeSafeEntry"
          },
          "maxProperties": 255
        }
      }
    },
    "TypeSafeContent": {
      "description": "Text or structured context supplied to Jev.",
      "oneOf": [
        {
          "type": "string"
        },
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        }
      ]
    },
    "TypeSafeEntry": {
      "description": "Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.",
      "oneOf": [
        {
          "type": "string",
          "nullable": true
        },
        {
          "type": "object",
          "additionalProperties": true
        },
        {
          "type": "array",
          "items": {}
        }
      ]
    },
    "TypeSafeNoulAnswer": {
      "type": "object",
      "required": [
        "type",
        "noul"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "noul"
          ]
        },
        "noul": {
          "type": "number",
          "minimum": 0,
          "maximum": 1,
          "description": "Probability of yes: 0 means no, 1 means yes."
        }
      }
    },
    "TypeSafeNoulQuestion": {
      "type": "object",
      "description": "A yes/no judgment expressed as a probability.",
      "required": [
        "type"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "noul"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        },
        "criteria": {
          "type": "object",
          "description": "Optional guidance for yes and no.",
          "properties": {
            "true": {
              "$ref": "#/components/schemas/TypeSafeEntry"
            },
            "false": {
              "$ref": "#/components/schemas/TypeSafeEntry"
            }
          },
          "nullable": true
        }
      }
    },
    "TypeSafeRequestCredentials": {
      "type": "object",
      "required": [
        "respan_params",
        "model",
        "state",
        "questions"
      ],
      "properties": {
        "respan_params": {
          "type": "object",
          "description": "Request-scoped TypeSafe credentials. Respan removes these parameters before forwarding the request.",
          "properties": {
            "credential_override": {
              "type": "object",
              "description": "Map the model name without the `typesafe/` prefix, such as `jev-1.13.0`, to your TypeSafe credentials.",
              "additionalProperties": {
                "type": "object",
                "required": [
                  "api_key"
                ],
                "properties": {
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Your TypeSafe API key.",
                    "format": "password"
                  }
                }
              },
              "example": {
                "jev-1.13.0": {
                  "api_key": "YOUR_TYPESAFE_API_KEY"
                }
              },
              "minProperties": 1
            }
          },
          "additionalProperties": true,
          "required": [
            "credential_override"
          ]
        },
        "model": {
          "type": "string",
          "description": "Respan model ID, for example typesafe/jev-1.13.0.",
          "example": "typesafe/jev-1.13.0"
        },
        "state": {
          "$ref": "#/components/schemas/TypeSafeContent"
        },
        "questions": {
          "type": "object",
          "description": "Named questions evaluated against the same state.",
          "additionalProperties": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TypeSafeNoulQuestion"
              },
              {
                "$ref": "#/components/schemas/TypeSafeChoiceQuestion"
              },
              {
                "$ref": "#/components/schemas/TypeSafeScoreQuestion"
              }
            ]
          },
          "minProperties": 1
        }
      },
      "description": "Supply a TypeSafe API key with this request. Authenticate with your Respan key in Authorization.",
      "title": "Enter TypeSafe API key"
    },
    "TypeSafeSavedCredentials": {
      "type": "object",
      "required": [
        "model",
        "state",
        "questions"
      ],
      "properties": {
        "respan_params": {
          "type": "object",
          "description": "Optional Respan parameters, removed before forwarding the request.",
          "properties": {
            "credential_override": {
              "type": "object",
              "description": "Override the saved key for this request. Use the model name without the `typesafe/` prefix, such as `jev-1.13.0`.",
              "additionalProperties": {
                "type": "object",
                "required": [
                  "api_key"
                ],
                "properties": {
                  "api_key": {
                    "type": "string",
                    "writeOnly": true,
                    "description": "Your TypeSafe API key.",
                    "format": "password"
                  }
                }
              },
              "example": {
                "jev-1.13.0": {
                  "api_key": "YOUR_TYPESAFE_API_KEY"
                }
              }
            }
          },
          "additionalProperties": true
        },
        "model": {
          "type": "string",
          "description": "Respan model ID, for example typesafe/jev-1.13.0.",
          "example": "typesafe/jev-1.13.0"
        },
        "state": {
          "$ref": "#/components/schemas/TypeSafeContent"
        },
        "questions": {
          "type": "object",
          "description": "Named questions evaluated against the same state.",
          "additionalProperties": {
            "oneOf": [
              {
                "$ref": "#/components/schemas/TypeSafeNoulQuestion"
              },
              {
                "$ref": "#/components/schemas/TypeSafeChoiceQuestion"
              },
              {
                "$ref": "#/components/schemas/TypeSafeScoreQuestion"
              }
            ]
          },
          "minProperties": 1
        }
      },
      "description": "Use a TypeSafe key saved in Respan Settings > Providers.",
      "title": "Use saved TypeSafe key"
    },
    "TypeSafeScoreAnswer": {
      "type": "object",
      "required": [
        "type",
        "score",
        "legend",
        "probabilities",
        "confidence"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "score"
          ]
        },
        "score": {
          "type": "number",
          "description": "Probability-weighted level index; may be fractional."
        },
        "legend": {
          "type": "object",
          "additionalProperties": {
            "$ref": "#/components/schemas/TypeSafeContent"
          },
          "description": "Level indices mapped to rubric descriptions."
        },
        "probabilities": {
          "type": "object",
          "additionalProperties": {
            "type": "number",
            "minimum": 0,
            "maximum": 1
          }
        },
        "confidence": {
          "type": "number",
          "minimum": 0,
          "maximum": 1
        }
      }
    },
    "TypeSafeScoreQuestion": {
      "type": "object",
      "description": "Evaluate the state on an ordered rubric.",
      "required": [
        "type",
        "criteria"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "score"
          ]
        },
        "instructions": {
          "$ref": "#/components/schemas/TypeSafeEntry"
        },
        "criteria": {
          "type": "array",
          "minItems": 2,
          "items": {
            "$ref": "#/components/schemas/TypeSafeContent"
          },
          "description": "Rubric levels in order, starting at index 0.",
          "maxItems": 10
        }
      }
    }
  },
  "securitySchemes": {
    "RespanApiKey": {
      "type": "http",
      "scheme": "bearer",
      "bearerFormat": "Respan API key",
      "description": "Use your Respan API key for Respan API authentication. Enter only the Respan API key value; clients send Authorization: Bearer <RESPAN_API_KEY>. For /api/responses, provider credentials such as Perplexity, OpenAI, or Azure OpenAI go in Settings -> Providers or respan_params.credential_override in the request body, not in this authentication field.",
      "x-fern-bearer": {
        "name": "respanApiKey",
        "env": "RESPAN_API_KEY"
      }
    }
  }
}