---
title: TypeSafe API with AI Gateway
product: vercel
url: /docs/ai-gateway/sdks-and-apis/typesafe
canonical_url: "https://vercel.com/docs/ai-gateway/sdks-and-apis/typesafe"
last_updated: 2018-10-20
type: conceptual
prerequisites:
  - /docs/ai-gateway/sdks-and-apis
  - /docs/ai-gateway
related:
  - /docs/ai-gateway/modalities/evaluation
  - /docs/ai-gateway/authentication-and-byok/byok
  - /docs/ai-gateway/models-and-providers
summary: Point an existing TypeSafe client at AI Gateway by changing its base URL to route System One evaluation requests through it.
install_vercel_plugin: npx plugins add vercel/vercel-plugin
---

# TypeSafe API with AI Gateway

Keep using the [TypeSafe SDK](https://docs.typesafe.ai/introduction) and route requests through AI Gateway by changing one setting.

Requests are billed through AI Gateway and appear in your usage and observability alongside every other model you call.

If you are writing new code rather than migrating, use the [evaluation API](/docs/ai-gateway/modalities/evaluation) instead. It is the same capability without TypeSafe-specific naming.

## Base URL

The TypeSafe-compatible API is available at the following base URL:

```
https://ai-gateway.vercel.sh/typesafe
```

## Authentication

The TypeSafe-compatible API supports the same authentication methods as the main AI Gateway:

- **API key**: Use your AI Gateway API key with the `Authorization: Bearer <token>` header
- **OIDC token**: Use your Vercel OIDC token with the `Authorization: Bearer <token>` header

You only need one of these. This is the credential AI Gateway authenticates you with, not the credential used to call the model.

To bill the provider directly instead of through AI Gateway, add a TypeSafe key under [BYOK](/docs/ai-gateway/authentication-and-byok/byok).

## Migrating an existing client

Change the base URL and the API key:

```diff filename="client.ts"
  import { TypeSafeClient } from '@typesafe-ai/sdk';

  const client = new TypeSafeClient({
-   apiKey: process.env.TYPESAFE_API_KEY,
+   apiKey: process.env.AI_GATEWAY_API_KEY,
+   baseURL: 'https://ai-gateway.vercel.sh/typesafe',
  });
```

Everything else stays the same:

```typescript filename="triage.ts"
const result = await client.systemOne({
  state: 'I was charged twice for my subscription.',
  questions: {
    refund: { type: 'noul', instructions: 'Is the customer asking for money back?' },
    department: {
      type: 'choice',
      instructions: 'Which team should handle this?',
      criteria: { billing: 'Charges and refunds', technical: 'Bugs and outages' },
    },
  },
});

console.log(result.answers.refund); // { type: 'noul', noul: 0.98 }
```

## Supported endpoints

- `POST /typesafe/v1/systemone` evaluates state against typed questions
- `GET /typesafe/v1/models` lists the evaluation models available to you

## Request and response format

This API implements the TypeSafe request and response shapes.

#### cURL

```bash filename="systemone.sh"
curl https://ai-gateway.vercel.sh/typesafe/v1/systemone \
  -H "Authorization: Bearer $AI_GATEWAY_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "typesafe-ai/jev",
    "state": "I was charged twice for my subscription.",
    "questions": {
      "refund": {
        "type": "noul",
        "instructions": "Is the customer asking for money back?"
      }
    }
  }'
```

#### TypeScript

```typescript filename="systemone.ts"
import { TypeSafeClient } from '@typesafe-ai/sdk';

const client = new TypeSafeClient({
  apiKey: process.env.AI_GATEWAY_API_KEY,
  baseURL: 'https://ai-gateway.vercel.sh/typesafe',
});

const result = await client.systemOne({
  model: 'typesafe-ai/jev',
  state: 'I was charged twice for my subscription.',
  questions: {
    refund: {
      type: 'noul',
      instructions: 'Is the customer asking for money back?',
    },
  },
});
```

#### Python

```python filename="systemone.py"
import os
import requests

response = requests.post(
    "https://ai-gateway.vercel.sh/typesafe/v1/systemone",
    headers={
        "Authorization": f"Bearer {os.environ['AI_GATEWAY_API_KEY']}",
        "Content-Type": "application/json",
    },
    json={
        "model": "typesafe-ai/jev",
        "state": "I was charged twice for my subscription.",
        "questions": {
            "refund": {
                "type": "noul",
                "instructions": "Is the customer asking for money back?",
            }
        },
    },
)

print(response.json()["answers"])
```

The response uses TypeSafe's field names:

```json
{
  "model": "typesafe-ai/jev",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "usage": { "input_tokens": 275, "output_tokens": 20 },
  "provider_metadata": {
    "gateway": {
      "routing": {
        "originalModelId": "typesafe-ai/jev",
        "resolvedProvider": "typesafe-ai",
        "canonicalSlug": "typesafe-ai/jev",
        "finalProvider": "typesafe-ai"
      },
      "cost": "0.00001155",
      "marketCost": "0.00001155",
      "surchargeCost": "0",
      "gatewayCost": "0.00001155",
      "generationId": "gen_..."
    }
  }
}
```

## Errors

Errors use TypeSafe's shape, with a machine-readable code alongside the message:

```json
{
  "message": "questions.refund.type: expected one of 'noul', 'choice', 'score'",
  "error_type": "invalid_request"
}
```

Errors returned by the model provider are passed through unchanged, so a client that already handles TypeSafe errors keeps working.

## Related

- [Evaluation](/docs/ai-gateway/modalities/evaluation) for the HTTP API and the AI SDK
- [Models and providers](/docs/ai-gateway/models-and-providers) for the full catalog


---

[View full sitemap](/docs/sitemap)