Evaluate state with TypeSafe Jev
https://api.respan.ai/api/typesafe/v1/systemoneEvaluate 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.
Authorization: Bearer $RESPAN_API_KEYRequest body
A request body is required.
application/json
$ object or object Required body
$ (anyOf 1) object Schema variant
Reference:
#/components/schemas/TypeSafeRequestCredentials$ (anyOf 1).respan_params object Required in parent
Additional properties are allowed
$ (anyOf 1).respan_params.credential_override object Required in parent
typesafe/ prefix, such as jev-1.13.0, to your TypeSafe credentials.Minimum properties:
1Example:
{"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 parentFormat:
passwordWrite only
$ (anyOf 1).model string Required in parentExample:
"typesafe/jev-1.13.0"$ (anyOf 1).state string or object or array<any> Required in parent
Reference:
#/components/schemas/TypeSafeContent$ (anyOf 1).state (oneOf 1) string Schema variant$ (anyOf 1).state (oneOf 2) object Schema variant$ (anyOf 1).state (oneOf 3) array<any> Schema variant
$ (anyOf 1).state (oneOf 3)[] any Array item$ (anyOf 1).questions object Required in parent
Minimum properties:
1$ (anyOf 1).questions.<key> object or object or object Map value
$ (anyOf 1).questions.<key> (oneOf 1) object Schema variant
Reference:
#/components/schemas/TypeSafeNoulQuestion$ (anyOf 1).questions.<key> (oneOf 1).type string Required in parent"noul"$ (anyOf 1).questions.<key> (oneOf 1).instructions string or null or object or array<any> Optional
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$ (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
$ (anyOf 1).questions.<key> (oneOf 1).criteria.true string or null or object or array<any> Optional
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$ (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
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$ (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
Reference:
#/components/schemas/TypeSafeChoiceQuestion$ (anyOf 1).questions.<key> (oneOf 2).type string Required in parent"choice"$ (anyOf 1).questions.<key> (oneOf 2).instructions string or null or object or array<any> Optional
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$ (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
Maximum properties:
255$ (anyOf 1).questions.<key> (oneOf 2).criteria.<key> string or null or object or array<any> Map value
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$ (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
Reference:
#/components/schemas/TypeSafeScoreQuestion$ (anyOf 1).questions.<key> (oneOf 3).type string Required in parent"score"$ (anyOf 1).questions.<key> (oneOf 3).instructions string or null or object or array<any> Optional
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$ (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
Minimum items:
2Maximum items:
10$ (anyOf 1).questions.<key> (oneOf 3).criteria[] string or object or array<any> Array item
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$ (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
Reference:
#/components/schemas/TypeSafeSavedCredentials$ (anyOf 2).respan_params object Optional
Additional properties are allowed
$ (anyOf 2).respan_params.credential_override object Optional
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 parentFormat:
passwordWrite only
$ (anyOf 2).model string Required in parentExample:
"typesafe/jev-1.13.0"$ (anyOf 2).state string or object or array<any> Required in parent
Reference:
#/components/schemas/TypeSafeContent$ (anyOf 2).state (oneOf 1) string Schema variant$ (anyOf 2).state (oneOf 2) object Schema variant$ (anyOf 2).state (oneOf 3) array<any> Schema variant
$ (anyOf 2).state (oneOf 3)[] any Array item$ (anyOf 2).questions object Required in parent
Minimum properties:
1$ (anyOf 2).questions.<key> object or object or object Map value
$ (anyOf 2).questions.<key> (oneOf 1) object Schema variant
Reference:
#/components/schemas/TypeSafeNoulQuestion$ (anyOf 2).questions.<key> (oneOf 1).type string Required in parent"noul"$ (anyOf 2).questions.<key> (oneOf 1).instructions string or null or object or array<any> Optional
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$ (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
$ (anyOf 2).questions.<key> (oneOf 1).criteria.true string or null or object or array<any> Optional
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$ (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
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$ (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
Reference:
#/components/schemas/TypeSafeChoiceQuestion$ (anyOf 2).questions.<key> (oneOf 2).type string Required in parent"choice"$ (anyOf 2).questions.<key> (oneOf 2).instructions string or null or object or array<any> Optional
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$ (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
Maximum properties:
255$ (anyOf 2).questions.<key> (oneOf 2).criteria.<key> string or null or object or array<any> Map value
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$ (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
Reference:
#/components/schemas/TypeSafeScoreQuestion$ (anyOf 2).questions.<key> (oneOf 3).type string Required in parent"score"$ (anyOf 2).questions.<key> (oneOf 3).instructions string or null or object or array<any> Optional
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$ (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
Minimum items:
2Maximum items:
10$ (anyOf 2).questions.<key> (oneOf 3).criteria[] string or object or array<any> Array item
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$ (anyOf 2).questions.<key> (oneOf 3).criteria[] (oneOf 3) array<any> Schema variant
$ (anyOf 2).questions.<key> (oneOf 3).criteria[] (oneOf 3)[] any Array itemOpenAPI request 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
TypeSafe evaluation result. The example is from the refund request; probabilities and token counts can vary.
application/json
$ object Body
model string Required in parentanswers object Required in parent
answers.<key> object or object or object Map value
answers.<key> (oneOf 1) object Schema variant
#/components/schemas/TypeSafeNoulAnsweranswers.<key> (oneOf 1).type string Required in parent"noul"answers.<key> (oneOf 1).noul number Required in parentMinimum:
0Maximum:
1answers.<key> (oneOf 2) object Schema variant
#/components/schemas/TypeSafeChoiceAnsweranswers.<key> (oneOf 2).type string Required in parent"choice"answers.<key> (oneOf 2).choice string Required in parentanswers.<key> (oneOf 2).probabilities object Required in parent
answers.<key> (oneOf 2).probabilities.<key> number Map value0Maximum:
1answers.<key> (oneOf 2).confidence number Required in parent0Maximum:
1answers.<key> (oneOf 3) object Schema variant
#/components/schemas/TypeSafeScoreAnsweranswers.<key> (oneOf 3).type string Required in parent"score"answers.<key> (oneOf 3).score number Required in parentanswers.<key> (oneOf 3).legend object Required in parent
answers.<key> (oneOf 3).legend.<key> string or object or array<any> Map value
Reference:
#/components/schemas/TypeSafeContentanswers.<key> (oneOf 3).legend.<key> (oneOf 1) string Schema variantanswers.<key> (oneOf 3).legend.<key> (oneOf 2) object Schema variantanswers.<key> (oneOf 3).legend.<key> (oneOf 3) array<any> Schema variant
answers.<key> (oneOf 3).legend.<key> (oneOf 3)[] any Array itemanswers.<key> (oneOf 3).probabilities object Required in parent
answers.<key> (oneOf 3).probabilities.<key> number Map value0Maximum:
1answers.<key> (oneOf 3).confidence number Required in parent0Maximum:
1usage object Required in parent
usage.input_tokens integer Required in parentusage.output_tokens integer Required in parentOpenAPI 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
{
"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
$ object BodyOpenAPI response schema
{
"type": "object",
"additionalProperties": true
}401
No TypeSafe provider credentials are available, or TypeSafe rejected the provider API key.
application/json
$ object BodyOpenAPI response schema
{
"type": "object",
"additionalProperties": true
}403
Missing, invalid, or expired Respan API key.
application/json
$ object BodyOpenAPI response schema
{
"type": "object",
"additionalProperties": true
}422
TypeSafe rejected the request body or question format.
application/json
$ object BodyOpenAPI response schema
{
"type": "object",
"additionalProperties": true
}429
Rate limit exceeded. Retry with exponential backoff.
application/json
$ object BodyOpenAPI response schema
{
"type": "object",
"additionalProperties": true
}529
TypeSafe is temporarily overloaded. Retry with exponential backoff.
application/json
$ object BodyOpenAPI 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"
}
}
}
}