TypeSafe AI provider

You can proxy requests to TypeSafe AI AI models through AI Gateway by creating AI Model Provider and AI Model entities. This reference documents all supported AI capabilities, configuration requirements, and provider-specific details needed for proper integration.

AI Gateway automatically routes requests to the appropriate TypeSafe AI API endpoints. The following table shows the upstream paths used for each capability.

The following tables show the AI capabilities supported by the TypeSafe AI provider when configuring AI Models.

By default, AI Gateway uses the path templates shown in the tables below (e.g., /chat/completions, /embeddings, etc.). To customize these paths, configure the config.paths field in your AI Model entity. Custom paths take the form {configured_path}/{template_path} — for example, if you set a custom path of /v2, requests to /embeddings would be routed to /v2/embeddings.

Decisions

Support for TypeSafe AI decision capabilities:

¹ Requires formats: [{type: typesafe}] on the AI Model. See the TypeSafe AI provider page for request/response shape and limitations.

The base URL is https://api.typesafe.ai.

AI Gateway uses this URL automatically. You only need to configure a URL if you’re using a self-hosted or TypeSafe AI-compatible endpoint, in which case set the upstream_url option in your AI Model configuration.

By default, AI Gateway uses OpenAI-compatible request formats. Configure a native format in your AI Model to use TypeSafe AI-specific APIs and features.

The following native TypeSafe AI formats are supported:

To use TypeSafe AI with AI Gateway, configure a new AI Model Provider. You can then access supported AI Models from TypeSafe AI.

Here’s a minimal configuration for TypeSafe AI:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "TypeSafe AI Production",
      "name": "my-typesafe-account",
      "type": "typesafe",
      "config": {
        "auth": {
          "type": "basic",
          "headers": [
            {
              "name": "Authorization",
              "value": "'$TYPESAFE_API_KEY'"
            }
          ]
        }
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-typesafe-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: TypeSafe AI Production
    name: my-typesafe-account
    type: typesafe
    config:
      auth:
        type: basic
        headers:
        - name: Authorization
          value: !secret {source: !env TYPESAFE_API_KEY}

The decisions capability requires formats: [{type: typesafe}] on the AI Model. There’s no OpenAI-translated equivalent for this capability, so the native format is required here, unlike for other passthrough providers.

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/models \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "TypeSafe Jev",
      "name": "jev-decisions",
      "type": "model",
      "capabilities": [
        "decisions"
      ],
      "formats": [
        {
          "type": "typesafe"
        }
      ],
      "config": {
        "route": {
          "paths": [
            "/jev"
          ]
        }
      },
      "targets": [
        {
          "name": "jev-latest",
          "provider": "my-typesafe-account",
          "config": {
            "type": "typesafe"
          }
        }
      ]
    }
    '

ai_gateway_models:
  - ref: jev-decisions
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: TypeSafe Jev
    name: jev-decisions
    type: model
    capabilities:
    - decisions
    formats:
    - type: typesafe
    config:
      route:
        paths:
        - "/jev"
    targets:
    - name: jev-latest
      provider: my-typesafe-account
      config:
        type: typesafe

With this configuration, requests reach the AI Model at {route path}/v1/systemone. For this example, the path is /jev/v1/systemone. See Request and response shape for the request and response body.

Route a target to an alternate TypeSafe-compatible host

A target’s config.upstream_url can point at a different host serving the same Jev model, for example, a provider that re-hosts TypeSafe models behind its own endpoint. Because credentials differ per host, configure a separate typesafe-type AI Model Provider for it:

curl -X POST https://{region}.api.konghq.com/v1/ai-gateways/{AIGatewayId}/model-providers \
    --header "accept: application/json" \
    --header "Content-Type: application/json" \
    --header "Authorization: Bearer $KONNECT_TOKEN" \
    --data '
    {
      "display_name": "Jev via OpenRouter",
      "name": "my-openrouter-account",
      "type": "typesafe",
      "config": {
        "auth": {
          "type": "basic",
          "headers": [
            {
              "name": "Authorization",
              "value": "'$OPENROUTER_API_KEY'"
            }
          ]
        }
      }
    }
    '

ai_gateway_model_providers:
  - ref: my-openrouter-account
    ai_gateway: !lookup {id: !env AI_GATEWAY_ID}
    display_name: Jev via OpenRouter
    name: my-openrouter-account
    type: typesafe
    config:
      auth:
        type: basic
        headers:
        - name: Authorization
          value: !secret {source: !env OPENROUTER_API_KEY}

Then add a second target on the same AI Model, referencing that provider and overriding upstream_url:

targets:
  - name: jev-latest
    provider: my-typesafe-account
  - name: typesafe/jev-1.13-20260917
    provider: my-openrouter-account
    config:
      type: typesafe
      upstream_url: https://openrouter.ai/api/alpha/decisions

TypeSafe AI’s API takes a state string plus a map of typed questions, and returns typed decisions instead of generated text. AI Gateway passes this body through to TypeSafe AI unmodified. It doesn’t translate the body into the OpenAI chat shape, because there’s no messages or input field to translate. See TypeSafe’s API reference for the full request and response schema.

The model field is required and must match the AI Model entity’s name.

For example, this request:

curl -X POST "$KONNECT_PROXY_URL/jev/v1/systemone" \
     --no-progress-meter --fail-with-body  \
     -H "Accept: application/json"\
     -H "Content-Type: application/json" \
     --json '{
       "state": "Help! My payouts have been failing for 3 days.",
       "model": "jev-decisions",
       "questions": {
         "is_urgent": {
           "type": "noul",
           "instructions": "Does this convey urgency?"
         }
       }
     }'

Returns a response similar to:

{
  "model": "jev-1.13.0",
  "answers": {
    "is_urgent": {
      "type": "noul",
      "noul": 0.95
    }
  },
  "usage": {
    "input_tokens": 283,
    "output_tokens": 23
  }
}

Note the following:

• The response’s answers field is a map keyed by the question’s name, not an array.
• Answers to noul-type questions don’t carry a confidence or probabilities field. For that question type, the number itself is the belief.

• The decisions capability’s request body doesn’t carry an extractable prompt, so it doesn’t support:
  • Guardrails
  • Semantic caching
  • Semantic routing
  • ai-llm-as-judge
  • Prompt-based rate limiting
  • model_alias
• TypeSafe AI’s own API reference documents a 401 status for authentication failures, but a missing or invalid API key currently returns 403. Error bodies arrive under a detail field rather than an error field.