TypeSafe

Overview

TypeSafe is a specialized decision provider serving the jev family of System One judgment models. A decision request carries a state (what to evaluate) and a map of named questions; the response carries one typed answer per question. Bifrost performs conversions including:

Model ID mapping - Uses provider model identifier directly (jev-1.13.0, jev-1.14.0, jev-latest, jev-preview)
Question conversion - Maps Bifrost question types (predicate, choice, score, box) to TypeSafe’s native System One types (noul, choice, score, box), and choices and levels to its criteria
Images - Images placed by reference in the state, instructions, or criteria reach TypeSafe as its assets, as base64 JSON or multipart, with the TypeSafe-Danger-Zone-Images header added for you
Answer normalization - Native noul/choice/score value fields normalize to a unified value, with confidence, probabilities, and legend metadata preserved
Usage normalization - input_tokens/output_tokens map to Bifrost’s prompt_tokens/completion_tokens (TypeSafe bills input tokens only)
SDK-faithful validation - Unsupported kinds and malformed criteria are rejected locally with a 400; everything the official SDK types allow (null state, optional instructions, null descriptions, extra top-level fields) is forwarded so the endpoint gives its own verdict

Supported Operations

Operation	Non-Streaming	Streaming	Endpoint
Decisions	✅	-	`/v1/decisions`
List Models	✅	-	`/v1/models`
Chat Completions	❌	❌	-
Responses API	❌	❌	-
Text Completions	❌	❌	-
Embeddings	❌	❌	-

Unsupported Operations (❌): Chat Completions, Responses API, Text Completions, Embeddings, and every other operation return UnsupportedOperationError - TypeSafe serves judgment models only.Model listing: Bifrost calls the endpoint’s native GET /v1/models. Against api.typesafe.ai the live listing (aliases) is merged with the pinned versioned jev entries, and the pinned catalog stands in when the call fails; a custom base_url serves its own catalog as-is. Pricing and context length still come from the model datasheet.

Setup & Configuration

Configure TypeSafe as a provider with a bearer API key:

{
  "providers": {
    "typesafe": {
      "keys": [
        {
          "name": "TypeSafe API Key",
          "value": "env.TYPESAFE_API_KEY",
          "weight": 1,
          "models": ["*"]
        }
      ]
    }
  }
}

Custom TypeSafe Providers

A custom provider can use typesafe as its base_provider_type, for example to reach a second TypeSafe endpoint with its own keys alongside the standard typesafe provider:

{
  "providers": {
    "typesafe-eu": {
      "keys": [
        {
          "name": "TypeSafe EU Key",
          "value": "env.TYPESAFE_EU_API_KEY",
          "weight": 1,
          "models": ["*"]
        }
      ],
      "network_config": {
        "base_url": "https://typesafe-eu.example.com"
      },
      "custom_provider_config": {
        "base_provider_type": "typesafe",
        "allowed_requests": {
          "list_models": true,
          "decisions": true
        }
      }
    }
  }
}

The custom provider is addressed by its own name: typesafe-eu/jev-latest on /v1/decisions, and on the native /typesafe/v1/systemone route. Responses, logs, and key selection report typesafe-eu. It supports the usual custom provider options:

allowed_requests - set decisions (and list_models) to true. When allowed_requests is present, an operation that is not listed is refused with unsupported_operation.
request_path_overrides - decisions and list_models accept a path on base_url or a full URL in place of /v1/systemone and /v1/models.
is_key_less - for endpoints that need no bearer token.

To list a custom provider’s models on the native /typesafe/v1/models route, send x-bf-model-provider: typesafe-eu. Model names come back bare (jev-latest), as on the standard provider. The pinned jev catalog is only merged in when no base_url is set. To run Laya or Nimble on your own infrastructure this way, follow Self-Hosted Decision Models, which covers model listing, allowed models, pricing, and the settings that otherwise make the provider look broken.

Decisions API

POST /v1/decisions asks a list of questions about an input. Each question has a type, optional name, instructions (string or structured data), and type-specific details:

Type	TypeSafe kind	Answer	Details
`predicate`	`noul`	`probability` between 0 and 1	Optional `criteria`: `true`/`false` descriptions
`choice`	`choice`	`choice`: one of the values	Required `choices` (max 255)
`score`	`score`	`score`: rubric score, including fractions	Required ordered `levels` (2-10 on TypeSafe)
`box`	`box`	`box`: `top`, `bottom`, `left`, `right` edges, each a fraction from 0 to 1 of the image, measured from its top-left	`instructions` only; needs Jev 1.14 (see Images and Box)

curl http://localhost:8080/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-1.13.0",
    "input": "Customer message: I was double charged and nobody replied. I want a refund today.",
    "questions": [
      { "type": "predicate", "name": "is_frustrated", "instructions": "Is the customer frustrated?" },
      {
        "type": "choice",
        "name": "category",
        "instructions": "Pick the ticket category",
        "choices": [
          { "value": "billing", "description": "charges and refunds" },
          { "value": "bug", "description": "product defects" },
          { "value": "other", "description": "anything else" }
        ]
      },
      {
        "type": "score",
        "name": "urgency",
        "instructions": "Rate how urgently this needs a human reply",
        "levels": [
          { "label": "0", "description": "can wait a week" },
          { "label": "1", "description": "should be answered soon" },
          { "label": "2", "description": "needs a reply today" }
        ]
      }
    ]
  }'

The response lists one answer per question, in order. The earlier map-form body (state plus questions keyed by name, with kind and criteria) is still served and answered in the map form; see Decisions.

Images and Box

TypeSafe reads images placed by reference. Each image is listed once with an ID, and the image is placed wherever that ID is written: in the input, in a question’s instructions, or in choice, score, and noul criteria, as a whole value or inside a sentence. An image in the input is evidence every question judges; an image in a question is only that question’s reference material, such as an example that defines a choice option. A box question answers where something is in an image, and needs Jev 1.14: send jev-preview or jev-1.14.0 until jev-latest resolves to 1.14. Bifrost adds the TypeSafe-Danger-Zone-Images: true header that TypeSafe requires whenever a request carries images or a box question, so clients do not send it. It is listed in the provider’s Beta Headers settings, supported by default; overriding it to unsupported, or setting network_config.beta_header_overrides to {"typesafe-danger-zone-images": false}, stops Bifrost from sending it, so TypeSafe rejects image and box requests.

/v1/decisions
/typesafe/v1/systemone

An image sent by reference is an input_image part with an id and its file base64-encoded in data; Bifrost reads the format from the bytes, as TypeSafe does. A single message with one input_text part plus such parts is sent to TypeSafe as that text for the state, and the text may be a string, an object, or an array, so a structured state stays structured:

curl http://localhost:8080/v1/decisions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe/jev-preview",
    "input": [{
      "role": "user",
      "content": [
        { "type": "input_text", "text": { "camera": "r-cam" } },
        { "type": "input_image", "id": "r-cam", "data": "/9j/4AAQ..." },
        { "type": "input_image", "id": "r-thumb", "data": "iVBORw0..." }
      ]
    }],
    "questions": [
      {
        "type": "choice",
        "name": "gesture",
        "instructions": "Which gesture is the hand in `camera` making?",
        "choices": [
          { "value": "thumbs_up", "description": "r-thumb" },
          { "value": "none", "description": "No hand." }
        ]
      },
      { "type": "box", "name": "hand", "instructions": "the hand in `camera`" }
    ]
  }'

The same request can also be sent as multipart, with each image in its own file part named by the image part’s name instead of data; see Images by Reference. TypeSafe receives {"state": {"camera": "r-cam"}, "assets": {"r-cam": {...}, "r-thumb": {...}}, ...}: the example image r-thumb appears only in the gesture criteria, never in the state. The box answer reads:

{ "type": "box", "name": "hand", "box": { "top": 0.25, "bottom": 0.82, "left": 0.44, "right": 0.84 }, "confidence": 0.92 }

The native route takes TypeSafe’s own request: an assets map of base64 images in JSON, or, as TypeSafe recommends, a multipart request with the JSON in a part named request and each image in its own file part. A multipart request reaches TypeSafe as multipart, each image under its part name, with its content type read from the bytes as TypeSafe reads them:

curl http://localhost:8080/typesafe/v1/systemone \
  -F 'request={
    "model": "jev-latest",
    "state": {"door": "a3f1c2e8-door"},
    "assets": {"a3f1c2e8-door": {"type": "image", "part": "door-photo"}},
    "questions": {"person_present": {"type": "noul", "instructions": "Is there a person in `door`?"}}
  };type=application/json' \
  -F '[email protected];type=image/jpeg'

TypeSafe judges the images themselves: an image that is not PNG or JPEG, and size, dimension, and unreferenced-asset limits, return TypeSafe’s own 400 or 413, passed through unchanged. Bifrost rejects only a request it cannot build: an asset naming a file part the request does not carry, a file part or form field no asset names, a repeated part name, a part outside a multipart request, an asset type other than image, data_base64 that is not valid base64, an image part with an id but no data (TypeSafe does not fetch URLs), an image part’s name in a JSON request or with no matching file part, and an id used twice. Images sent by reference work only with TypeSafe and Databricks’ System One models. Bifrost does not refuse them for other providers, but those providers do not read them: a provider that needs an image_url rejects the part, and one that receives TypeSafe’s request shape as is, such as Azure, returns its own error for assets. Inline input_image parts without an id keep working on the providers that read inline images.

Large-payload mode streams an oversized request body to TypeSafe without parsing it, so Bifrost cannot see its images. To send one, forward the client’s own TypeSafe-Danger-Zone-Images header by adding it to the header allowlist, or send it as x-bf-eh-typesafe-danger-zone-images.

Field Mapping Reference

How Bifrost’s /v1/decisions request reaches TypeSafe’s native /v1/systemone API, and how the answers come back.

Request

Bifrost field	Native field	Notes
`model`	`model`	`typesafe/<id>` (routing prefix stripped)
`input` (string)	`state` (string)	Sent unchanged
`input` (object)	`state` (object)	Sent unchanged
`input` (messages)	`state` (array of `{role, content}`)	Text parts only; an image part without an `id` is rejected with 400 for this attempt, so a fallback can serve it
`input` (one message: one `input_text` plus `input_image` parts with an `id`)	`state` and `assets`	The text, as a string, object, or array, is the `state`; each part becomes `assets[id]`: `data` as `data_base64`, with the `format` read from the bytes
`input_image` part with an `id` (other inputs)	`assets[id]`	Removed from the message `state`
`input` (null)	`state: null`	Forwarded (api.typesafe.ai answers 422)
`questions[]`	`questions` keyed by name	An unnamed question is sent as `question_<position>`; a repeated name is rejected with 400
`questions[].type`	`type`	`predicate` → `noul`; `choice`, `score`, `box` unchanged
`questions[].instructions`	`instructions`	string, object, array (lossless); null or absent is forwarded
`questions[].criteria`	`criteria`	Predicate only: optional map with only `"true"` and `"false"` keys
`questions[].choices`	`criteria` map of option → description	A boolean value is keyed `"true"`/`"false"`; missing, empty, or more than 255 choices rejected with 400
`questions[].levels`	`criteria` array of descriptions	A label other than the level’s index is folded in (`"label: description"`, or the label alone); the level count is checked upstream (TypeSafe accepts 2-10 and rejects other counts with its own error)
`safety_identifier`	-	Not sent; TypeSafe has no end-user identifier
`fallbacks`	-	Bifrost-only; consumed by fallback routing, never sent upstream

Descriptions may be a string, object, array, or null, and pass through to TypeSafe unchanged. The conversion path re-encodes JSON, so whitespace and object-key ordering can differ; raw-request passthrough bypasses conversion and preserves the original request bytes.

Response

Bifrost field	Built from native	Notes
`model`	`model`	Aliases resolve upstream: a `jev-latest` request reports the version it resolved to, such as `jev-1.13.0`
`answers[]`	`answers` keyed by name	In question order; `name` as asked (absent for an unnamed question)
`answers[].type`	`answers.<name>.type`	`noul` → `predicate`
`answers[].probability` \| `.choice` \| `.score`	`.noul` \| `.choice` \| `.score`	A noul outside [0,1] is rejected; a boolean choice answers with its boolean
`answers[].probabilities`	`probabilities`	Listed in choice or level order; score entries carry the level’s label
`answers[].box`	`.box`	`top`, `bottom`, `left`, `right`
`answers[].confidence`, `.legend`	`confidence`, `legend`	When supplied
`usage.prompt_tokens`	`usage.input_tokens`	TypeSafe bills input tokens only
`usage.completion_tokens`	`usage.output_tokens`	Output rate is $0
`usage.total_tokens`	-	Computed: input + output
`extra_fields`	-	Bifrost-only: request type, routing info, latency, raw request/response capture

Every requested question must produce an answer of its declared type; a missing answer, a type mismatch, or a missing value fails the request rather than returning partial results.

Errors

Upstream status	Meaning	Bifrost behavior
400	Request rejected upstream, including images (invalid format, dimensions, unreferenced asset)	Status and message preserved
401	Invalid or missing API key	Status and message preserved; key marked failed, other keys rotate in
413	Request over an image size limit	Status and message preserved
422	Request validation failed upstream	Status and validation detail preserved
429	Rate limited	Retried with backoff; keys rotate (per-key limit)
529	Service overloaded	Retried with backoff on the same key (capacity, not credential)

Requests rejected by Bifrost’s own validation (see tables above) return 400 with caller_invalid_request before any upstream call is made.

Native Integration

Bifrost also exposes TypeSafe’s native API 1:1 under the /typesafe prefix, for clients written against TypeSafe directly:

Native Endpoint	Method	Notes
`/typesafe/v1/systemone`	POST	Native request/response shape: a `state` and questions keyed by name, with `assets` as JSON or multipart
`/typesafe/v1/models`	GET	Native `{"models": [{"name", "description", "release_date"}]}` shape from the endpoint’s own listing

The native route accepts bare model IDs (jev-1.13.0) exactly as TypeSafe does, and additionally accepts typesafe/-prefixed IDs.

Success and error responses from the TypeSafe provider are relayed byte-for-byte (answer and usage metadata outside the shared shape, and native detail values, all survive), together with upstream headers such as x-typesafe-request-id and Retry-After. Cached and fallback responses are rebuilt in the native shape. Additional top-level request fields the SDK forwards (for example a compatible endpoint’s images) reach the endpoint unchanged; a fallback to an LLM refuses such a request with 400 instead of answering it text-only. Requests rejected by Bifrost’s local validation use the {"detail": {"error_type", "message"}} envelope with 400.

Model Naming

Model	Notes
`jev-1.13.0`	Versioned release; reads images
`jev-1.14.0`	Versioned release; reads images and answers box questions
`jev-latest`	Alias for the latest release
`jev-preview`	Alias for the preview release

Aliases resolve upstream, and responses always report the resolved versioned model. TypeSafe bills input tokens only; the jev pricing, 64k context window, and rate limits are documented at docs.typesafe.ai/models.

Overview

Quick Start

Release Cadence

Migration Guides

Migrate from other Gateway

SDK Integrations

Providers & Guides

MCP Gateway

Agent Gateway

Relays

Custom plugins

Open Source Features

Overview

Supported Operations

Setup & Configuration

Custom TypeSafe Providers

Decisions API

Images and Box

Field Mapping Reference

Request

Response

Errors

Native Integration

Model Naming

​Overview

​Supported Operations

​Setup & Configuration

​Custom TypeSafe Providers

​Decisions API

​Images and Box

​Field Mapping Reference

​Request

​Response

​Errors

​Native Integration

​Model Naming

Overview

Supported Operations

Setup & Configuration

Custom TypeSafe Providers

Decisions API

Images and Box

Field Mapping Reference

Request

Response

Errors

Native Integration

Model Naming