> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://respan.ai/docs/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://respan.ai/docs/_mcp/server.

# Evaluate state with TypeSafe Jev

POST https://api.respan.ai/api/typesafe/v1/systemone
Content-Type: application/json

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](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.

Reference: https://respan.ai/docs/apis/gateway/evaluate-state-with-typesafe-jev

## Authentication

- `Authorization` header (bearer token, required) — 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.

## Request

### Body (application/json)

This endpoint expects a TypeSafe Gateway_typesafe_systemone_Request.

- `TypeSafe Gateway_typesafe_systemone_Request`

## Response

### 200

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

- `model` (string, required) — Model identifier returned by TypeSafe.
- `answers` (map from string to ApiTypesafeV1SystemonePostResponsesContentApplicationJsonSchemaAnswers, required) — Results keyed by the names supplied in questions.
- `usage` (ApiTypesafeV1SystemonePostResponsesContentApplicationJsonSchemaUsage, required)

## Errors

### 400 Bad Request Error

Invalid request, including stream: true.

- `map from string to any`

### 401 Unauthorized Error

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

- `map from string to any`

### 403 Forbidden Error

Missing, invalid, or expired Respan API key.

- `map from string to any`

### 422 Unprocessable Entity Error

TypeSafe rejected the request body or question format.

- `map from string to any`

### 429 Too Many Requests Error

Rate limit exceeded. Retry with exponential backoff.

- `map from string to any`

## Types

### TypeSafeRequestCredentials

Supply a TypeSafe API key with this request. Authenticate with your Respan key in Authorization.

- `respan_params` (TypeSafeRequestCredentialsRespanParams, required) — Request-scoped TypeSafe credentials. Respan removes these parameters before forwarding the request.
- `model` (string, required) — Respan model ID, for example typesafe/jev-1.13.0.
- `state` (TypeSafeContent, required) — Text or structured context supplied to Jev.
- `questions` (map from string to TypeSafeRequestCredentialsQuestions, required) — Named questions evaluated against the same state.

### TypeSafeSavedCredentials

Use a TypeSafe key saved in Respan Settings > Providers.

- `model` (string, required) — Respan model ID, for example typesafe/jev-1.13.0.
- `state` (TypeSafeContent, required) — Text or structured context supplied to Jev.
- `questions` (map from string to TypeSafeSavedCredentialsQuestions, required) — Named questions evaluated against the same state.
- `respan_params` (TypeSafeSavedCredentialsRespanParams, optional) — Optional Respan parameters, removed before forwarding the request.

### ApiTypesafeV1SystemonePostResponsesContentApplicationJsonSchemaAnswers

### ApiTypesafeV1SystemonePostResponsesContentApplicationJsonSchemaUsage

- `input_tokens` (integer, required)
- `output_tokens` (integer, required)

### TypeSafeRequestCredentialsRespanParams

Request-scoped TypeSafe credentials. Respan removes these parameters before forwarding the request.

- `credential_override` (map from string to TypeSafeRequestCredentialsRespanParamsCredentialOverride, required) — Map the model name without the `typesafe/` prefix, such as `jev-1.13.0`, to your TypeSafe credentials.

### TypeSafeContent

Text or structured context supplied to Jev.

### TypeSafeRequestCredentialsQuestions

### TypeSafeSavedCredentialsQuestions

### TypeSafeSavedCredentialsRespanParams

Optional Respan parameters, removed before forwarding the request.

- `credential_override` (map from string to TypeSafeSavedCredentialsRespanParamsCredentialOverride, optional) — Override the saved key for this request. Use the model name without the `typesafe/` prefix, such as `jev-1.13.0`.

### TypeSafeNoulAnswer

- `type` (enum, required)
  - Allowed values: `noul`
- `noul` (double, required) — Probability of yes: 0 means no, 1 means yes.

### TypeSafeChoiceAnswer

- `type` (enum, required)
  - Allowed values: `choice`
- `choice` (string, required) — Selected option name.
- `probabilities` (map from string to double, required)
- `confidence` (double, required)

### TypeSafeScoreAnswer

- `type` (enum, required)
  - Allowed values: `score`
- `score` (double, required) — Probability-weighted level index; may be fractional.
- `legend` (map from string to TypeSafeContent, required) — Level indices mapped to rubric descriptions.
- `probabilities` (map from string to double, required)
- `confidence` (double, required)

### TypeSafeRequestCredentialsRespanParamsCredentialOverride

- `api_key` (string, required) — Your TypeSafe API key.

### TypeSafeNoulQuestion

A yes/no judgment expressed as a probability.

- `type` (enum, required)
  - Allowed values: `noul`
- `instructions` (TypeSafeEntry, optional) — Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.
- `criteria` (TypeSafeNoulQuestionCriteria, optional, nullable) — Optional guidance for yes and no.

### TypeSafeChoiceQuestion

Select an option from the supplied criteria.

- `type` (enum, required)
  - Allowed values: `choice`
- `criteria` (map from string to TypeSafeEntry, required) — Option names mapped to descriptions. Use null for an option without a description.
- `instructions` (TypeSafeEntry, optional) — Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.

### TypeSafeScoreQuestion

Evaluate the state on an ordered rubric.

- `type` (enum, required)
  - Allowed values: `score`
- `criteria` (list of TypeSafeContent, required) — Rubric levels in order, starting at index 0.
- `instructions` (TypeSafeEntry, optional) — Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.

### TypeSafeSavedCredentialsRespanParamsCredentialOverride

- `api_key` (string, required) — Your TypeSafe API key.

### TypeSafeEntry

Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.

### TypeSafeNoulQuestionCriteria

Optional guidance for yes and no.

- `true` (TypeSafeEntry, optional) — Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.
- `false` (TypeSafeEntry, optional) — Question instructions or rubric descriptions. Accepts text, an object, an array, or null. See https://docs.typesafe.ai/primitives/advanced.

## Examples

**Request**

```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?"
    }
  }
}
```

**Response**

```json
{
  "model": "jev-1.13.0",
  "answers": {
    "is_refund": {
      "type": "noul",
      "noul": 0.99
    }
  },
  "usage": {
    "input_tokens": 279,
    "output_tokens": 22
  }
}
```

**SDK Code**

```python TypeSafe Gateway_typesafe_systemone_example
import requests

url = "https://api.respan.ai/api/typesafe/v1/systemone"

payload = {
    "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?"
        } }
}
headers = {
    "Authorization": "Bearer <respanApiKey>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript TypeSafe Gateway_typesafe_systemone_example
const url = 'https://api.respan.ai/api/typesafe/v1/systemone';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <respanApiKey>', 'Content-Type': 'application/json'},
  body: '{"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?"}}}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```

```go TypeSafe Gateway_typesafe_systemone_example
package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.respan.ai/api/typesafe/v1/systemone"

	payload := strings.NewReader("{\n  \"respan_params\": {\n    \"credential_override\": {\n      \"jev-1.13.0\": {\n        \"api_key\": \"YOUR_TYPESAFE_API_KEY\"\n      }\n    }\n  },\n  \"model\": \"typesafe/jev-1.13.0\",\n  \"state\": \"I want a refund.\",\n  \"questions\": {\n    \"is_refund\": {\n      \"type\": \"noul\",\n      \"instructions\": \"Is the customer asking for a refund?\"\n    }\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <respanApiKey>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(res)
	fmt.Println(string(body))

}
```

```ruby TypeSafe Gateway_typesafe_systemone_example
require 'uri'
require 'net/http'

url = URI("https://api.respan.ai/api/typesafe/v1/systemone")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <respanApiKey>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"respan_params\": {\n    \"credential_override\": {\n      \"jev-1.13.0\": {\n        \"api_key\": \"YOUR_TYPESAFE_API_KEY\"\n      }\n    }\n  },\n  \"model\": \"typesafe/jev-1.13.0\",\n  \"state\": \"I want a refund.\",\n  \"questions\": {\n    \"is_refund\": {\n      \"type\": \"noul\",\n      \"instructions\": \"Is the customer asking for a refund?\"\n    }\n  }\n}"

response = http.request(request)
puts response.read_body
```

```java TypeSafe Gateway_typesafe_systemone_example
import com.mashape.unirest.http.HttpResponse;
import com.mashape.unirest.http.Unirest;

HttpResponse<String> response = Unirest.post("https://api.respan.ai/api/typesafe/v1/systemone")
  .header("Authorization", "Bearer <respanApiKey>")
  .header("Content-Type", "application/json")
  .body("{\n  \"respan_params\": {\n    \"credential_override\": {\n      \"jev-1.13.0\": {\n        \"api_key\": \"YOUR_TYPESAFE_API_KEY\"\n      }\n    }\n  },\n  \"model\": \"typesafe/jev-1.13.0\",\n  \"state\": \"I want a refund.\",\n  \"questions\": {\n    \"is_refund\": {\n      \"type\": \"noul\",\n      \"instructions\": \"Is the customer asking for a refund?\"\n    }\n  }\n}")
  .asString();
```

```php TypeSafe Gateway_typesafe_systemone_example
<?php
require_once('vendor/autoload.php');

$client = new \GuzzleHttp\Client();

$response = $client->request('POST', 'https://api.respan.ai/api/typesafe/v1/systemone', [
  'body' => '{
  "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?"
    }
  }
}',
  'headers' => [
    'Authorization' => 'Bearer <respanApiKey>',
    'Content-Type' => 'application/json',
  ],
]);

echo $response->getBody();
```

```csharp TypeSafe Gateway_typesafe_systemone_example
using RestSharp;

var client = new RestClient("https://api.respan.ai/api/typesafe/v1/systemone");
var request = new RestRequest(Method.POST);
request.AddHeader("Authorization", "Bearer <respanApiKey>");
request.AddHeader("Content-Type", "application/json");
request.AddParameter("application/json", "{\n  \"respan_params\": {\n    \"credential_override\": {\n      \"jev-1.13.0\": {\n        \"api_key\": \"YOUR_TYPESAFE_API_KEY\"\n      }\n    }\n  },\n  \"model\": \"typesafe/jev-1.13.0\",\n  \"state\": \"I want a refund.\",\n  \"questions\": {\n    \"is_refund\": {\n      \"type\": \"noul\",\n      \"instructions\": \"Is the customer asking for a refund?\"\n    }\n  }\n}", ParameterType.RequestBody);
IRestResponse response = client.Execute(request);
```

```swift TypeSafe Gateway_typesafe_systemone_example
import Foundation

let headers = [
  "Authorization": "Bearer <respanApiKey>",
  "Content-Type": "application/json"
]
let parameters = [
  "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?"
    ]]
] as [String : Any]

let postData = JSONSerialization.data(withJSONObject: parameters, options: [])

let request = NSMutableURLRequest(url: NSURL(string: "https://api.respan.ai/api/typesafe/v1/systemone")! as URL,
                                        cachePolicy: .useProtocolCachePolicy,
                                    timeoutInterval: 10.0)
request.httpMethod = "POST"
request.allHTTPHeaderFields = headers
request.httpBody = postData as Data

let session = URLSession.shared
let dataTask = session.dataTask(with: request as URLRequest, completionHandler: { (data, response, error) -> Void in
  if (error != nil) {
    print(error as Any)
  } else {
    let httpResponse = response as? HTTPURLResponse
    print(httpResponse)
  }
})

dataTask.resume()
```