> ## Documentation Index
> Fetch the complete documentation index at: https://openrouter.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Jev SDK for TypeScript and Python (TypeSafe SDK)

> Point the official TypeSafe JavaScript or Python SDK at OpenRouter to call Jev with your OpenRouter API key

## TypeSafe SDK

You can point an existing [TypeSafe](https://docs.typesafe.ai) client at OpenRouter by changing its base URL. Requests to System One models such as [Jev](https://openrouter.ai/typesafe/jev-1.13) are then billed to your OpenRouter account and routed through OpenRouter's System One API. The TypeSafe SDK is available for JavaScript and TypeScript (`@typesafe-ai/sdk`) and for Python (`typesafe_sdk`).

If you would rather call Jev without the TypeSafe SDK, use the [Decisions API](https://openrouter.ai/docs/api/api-reference/alphadecisions/submit-a-decisions-request.md) directly or through the OpenRouter [TypeScript](https://openrouter.ai/docs/client-sdks/typescript/sdks/decisions/README.md), [Python](https://openrouter.ai/docs/client-sdks/python/sdks/decisions/README.md), or [Go](https://openrouter.ai/docs/client-sdks/go/sdks/decisions/README.md) SDK. The [Jev tutorial](https://openrouter.ai/docs/guides/community/jev-tutorial.md) walks through that path from the first request to a threshold decision.

### Base URL

OpenRouter's System One API is available at the following base URL:

```text theme={null}
https://openrouter.ai/api
```

The SDK appends `/v1/systemone` to the base URL, so requests are sent to `https://openrouter.ai/api/v1/systemone`.

### Authentication

Use your [OpenRouter API key](https://openrouter.ai/settings/keys) as the `Authorization: Bearer <token>` header. The SDK sets this header from the `apiKey` option (`api_key` in Python) or the `TYPESAFE_API_KEY` environment variable.

### Migrating an existing client

Change the base URL and the API key. Everything else stays the same.

```typescript title="client.ts" lines theme={null}
import { TypeSafeClient } from '@typesafe-ai/sdk';

const client = new TypeSafeClient({
  apiKey: process.env.OPENROUTER_API_KEY,
  baseURL: 'https://openrouter.ai/api',
});
```

```python title="client.py" lines theme={null}
import os

from openai import OpenAI

# Point an existing OpenAI-compatible client at OpenRouter:
# only the base URL and the API key change.
client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1",
)

completion = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[{"role": "user", "content": "Say hello in one sentence."}],
)

print(completion.choices[0].message.content)

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"log"
	"net/http"
	"os"
)

// Point an existing OpenAI-compatible client at OpenRouter:
// only the base URL and the API key change.
const baseURL = "https://openrouter.ai/api/v1"

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "openai/gpt-4o-mini",
		"messages": []map[string]string{
			{"role": "user", "content": "Say hello in one sentence."},
		},
	})

	req, _ := http.NewRequest("POST", baseURL+"/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	var completion struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&completion); err != nil {
		log.Fatal(err)
	}
	if len(completion.Choices) == 0 {
		log.Fatalf("no choices returned (status %s)", resp.Status)
	}

	fmt.Println(completion.Choices[0].Message.Content)
}

```

```bash title="cURL" lines theme={null}
# Point an existing OpenAI-compatible request at OpenRouter:
# only the base URL and the API key change.
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [{"role": "user", "content": "Say hello in one sentence."}]
  }' | jq -r '.choices[0].message.content'

```

```text title="Output" theme={null}
Hello! How can I assist you today?
```

Both SDKs also read the base URL from the `TYPESAFE_BASE_URL` environment variable, so you can leave the constructor unchanged and set `TYPESAFE_BASE_URL=https://openrouter.ai/api` and `TYPESAFE_API_KEY=<your OpenRouter API key>` instead.

### Evaluating state against questions

```typescript title="triage.ts" lines theme={null}
// Evaluate a piece of state against typed questions using structured outputs.
const res = await fetch('https://openrouter.ai/api/v1/chat/completions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'openai/gpt-4o-mini',
    messages: [
      {
        role: 'system',
        content:
          'Evaluate the customer message. refund: probability (0 to 1) that the customer is asking for money back. ' +
          'department: which team should handle this (billing = charges and refunds, technical = bugs and outages).',
      },
      { role: 'user', content: 'I was charged twice for my subscription.' },
    ],
    response_format: {
      type: 'json_schema',
      json_schema: {
        name: 'answers',
        strict: true,
        schema: {
          type: 'object',
          properties: {
            refund: { type: 'number' },
            department: { type: 'string', enum: ['billing', 'technical'] },
          },
          required: ['refund', 'department'],
          additionalProperties: false,
        },
      },
    },
  }),
});

if (!res.ok) throw new Error(`HTTP ${res.status}: ${await res.text()}`);
const data: any = await res.json();
const answers = JSON.parse(data.choices[0].message.content);

console.log(answers); // e.g. { refund: 0.95, department: 'billing' }

```

```python title="triage.py" lines theme={null}
import json
import os

from openai import OpenAI

client = OpenAI(
    api_key=os.environ["OPENROUTER_API_KEY"],
    base_url="https://openrouter.ai/api/v1",
)

# Evaluate a piece of state against typed questions using structured outputs.
completion = client.chat.completions.create(
    model="openai/gpt-4o-mini",
    messages=[
        {
            "role": "system",
            "content": (
                "Evaluate the customer message. refund: probability (0 to 1) that the customer is asking for money back. "
                "department: which team should handle this (billing = charges and refunds, technical = bugs and outages)."
            ),
        },
        {"role": "user", "content": "I was charged twice for my subscription."},
    ],
    response_format={
        "type": "json_schema",
        "json_schema": {
            "name": "answers",
            "strict": True,
            "schema": {
                "type": "object",
                "properties": {
                    "refund": {"type": "number"},
                    "department": {"type": "string", "enum": ["billing", "technical"]},
                },
                "required": ["refund", "department"],
                "additionalProperties": False,
            },
        },
    },
)

answers = json.loads(completion.choices[0].message.content)

print(answers)  # e.g. {'refund': 0.95, 'department': 'billing'}

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

// Evaluate a piece of state against typed questions using structured outputs.
func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "openai/gpt-4o-mini",
		"messages": []map[string]string{
			{
				"role": "system",
				"content": "Evaluate the customer message. refund: probability (0 to 1) that the customer is asking for money back. " +
					"department: which team should handle this (billing = charges and refunds, technical = bugs and outages).",
			},
			{"role": "user", "content": "I was charged twice for my subscription."},
		},
		"response_format": map[string]any{
			"type": "json_schema",
			"json_schema": map[string]any{
				"name":   "answers",
				"strict": true,
				"schema": map[string]any{
					"type": "object",
					"properties": map[string]any{
						"refund":     map[string]any{"type": "number"},
						"department": map[string]any{"type": "string", "enum": []string{"billing", "technical"}},
					},
					"required":             []string{"refund", "department"},
					"additionalProperties": false,
				},
			},
		},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/chat/completions", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()
	if resp.StatusCode != http.StatusOK {
		b, _ := io.ReadAll(resp.Body)
		log.Fatalf("HTTP %d: %s", resp.StatusCode, b)
	}

	var data struct {
		Choices []struct {
			Message struct {
				Content string `json:"content"`
			} `json:"message"`
		} `json:"choices"`
	}
	if err := json.NewDecoder(resp.Body).Decode(&data); err != nil {
		log.Fatal(err)
	}
	if len(data.Choices) == 0 {
		log.Fatal("no choices returned")
	}

	var answers struct {
		Refund     float64 `json:"refund"`
		Department string  `json:"department"`
	}
	if err := json.Unmarshal([]byte(data.Choices[0].Message.Content), &answers); err != nil {
		log.Fatal(err)
	}

	out, _ := json.MarshalIndent(answers, "", "  ")
	fmt.Println(string(out)) // e.g. {"refund": 0.95, "department": "billing"}
}

```

```bash title="cURL" lines theme={null}
# Evaluate a piece of state against typed questions using structured outputs.
curl -s https://openrouter.ai/api/v1/chat/completions \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "openai/gpt-4o-mini",
    "messages": [
      {"role": "system", "content": "Evaluate the customer message. refund: probability (0 to 1) that the customer is asking for money back. department: which team should handle this (billing = charges and refunds, technical = bugs and outages)."},
      {"role": "user", "content": "I was charged twice for my subscription."}
    ],
    "response_format": {
      "type": "json_schema",
      "json_schema": {
        "name": "answers",
        "strict": true,
        "schema": {
          "type": "object",
          "properties": {
            "refund": {"type": "number"},
            "department": {"type": "string", "enum": ["billing", "technical"]}
          },
          "required": ["refund", "department"],
          "additionalProperties": false
        }
      }
    }
  }' | jq '.choices[0].message.content | fromjson'  # e.g. {"refund": 0.95, "department": "billing"}

```

```text title="Output" theme={null}
{
  refund: 0.9,
  department: "billing",
}
```

### Model IDs

The System One API accepts TypeSafe's bare System One model IDs and maps them onto OpenRouter's `typesafe/` namespace before routing:

* `jev-1.13` is routed as `typesafe/jev-1.13`.
* `jev-latest` is routed as `~typesafe/jev-latest`, OpenRouter's alias for the newest Jev release.
* IDs that already carry an author prefix, such as `typesafe/jev-1.13`, are used as-is.

The `model` field in the response contains the OpenRouter model ID of the System One model that served the request.

### Supported endpoints

* `POST /api/v1/systemone` sends state and typed questions to a System One model and returns its answers.

The TypeSafe SDK's model listing (`client.models.list()` in JavaScript) calls `GET /api/v1/models`, which is OpenRouter's [Models API](https://openrouter.ai/docs/api/api-reference/models/list-all-models-and-their-properties.md) and returns OpenRouter's response shape rather than TypeSafe's, so the SDK rejects it. Browse [OpenRouter's System One models](https://openrouter.ai/typesafe) or call the Models API directly instead.

### Request and response format

The System One API implements TypeSafe's request and response shapes. Requests require `model`, `state`, and `questions`, and responses contain `model`, `answers`, and `usage`. OpenRouter additionally returns `id`, `provider`, and `usage.cost`, which both SDKs pass through without error.

```bash title="systemone.sh" lines theme={null}
curl https://openrouter.ai/api/v1/systemone \
  -H "Authorization: Bearer $OPENROUTER_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "model": "jev-1.13",
    "state": "I was charged twice for my subscription.",
    "questions": {
      "refund": {
        "type": "noul",
        "instructions": "Is the customer asking for money back?"
      }
    }
  }'
```

```typescript title="TypeScript" lines theme={null}
const response = await fetch('https://openrouter.ai/api/v1/systemone', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.OPENROUTER_API_KEY}`,
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    model: 'jev-1.13',
    state: 'I was charged twice for my subscription.',
    questions: {
      refund: {
        type: 'noul',
        instructions: 'Is the customer asking for money back?',
      },
    },
  }),
});

console.log(JSON.stringify(await response.json()));

```

```python title="Python" lines theme={null}
import os
import requests

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

```

```go title="Go" lines theme={null}
package main

import (
	"bytes"
	"encoding/json"
	"fmt"
	"io"
	"log"
	"net/http"
	"os"
)

func main() {
	body, _ := json.Marshal(map[string]any{
		"model": "jev-1.13",
		"state": "I was charged twice for my subscription.",
		"questions": map[string]any{
			"refund": map[string]any{
				"type":         "noul",
				"instructions": "Is the customer asking for money back?",
			},
		},
	})

	req, _ := http.NewRequest("POST", "https://openrouter.ai/api/v1/systemone", bytes.NewReader(body))
	req.Header.Set("Authorization", "Bearer "+os.Getenv("OPENROUTER_API_KEY"))
	req.Header.Set("Content-Type", "application/json")

	resp, err := http.DefaultClient.Do(req)
	if err != nil {
		log.Fatal(err)
	}
	defer resp.Body.Close()

	out, err := io.ReadAll(resp.Body)
	if err != nil {
		log.Fatal(err)
	}
	if resp.StatusCode != http.StatusOK {
		log.Fatalf("HTTP %d: %s", resp.StatusCode, out)
	}
	fmt.Println(string(out))
}

```

```json title="Response" theme={null}
{
  "id": "gen-dec-1789738314-X5e5eKGQdvR9rblyX250",
  "model": "typesafe/jev-1.13-20260917",
  "provider": "TypeSafe",
  "answers": {
    "refund": { "type": "noul", "noul": 0.98 }
  },
  "usage": { "input_tokens": 275, "output_tokens": 20, "cost": 0.00003 }
}
```

### Jev resources on OpenRouter

* [Jev documentation hub](https://openrouter.ai/docs/guides/community/jev.md) for what Jev is, how it differs from a chat model, and every Jev page on OpenRouter
* [Jev model page](https://openrouter.ai/typesafe/jev-1.13) for pricing, context length, and provider details
* [Gate Agent Tool Calls with Jev](https://openrouter.ai/docs/cookbook/building-agents/gate-tool-calls-with-jev.md) for approving, blocking, or escalating agent tool calls
* [Cut LLM Cost with a Jev-Verified Cascade](https://openrouter.ai/docs/cookbook/evaluate-and-optimize/jev-verified-cascade.md) for verifying cheap-model answers before escalating
* [Classify and Tag Text at Scale with Jev](https://openrouter.ai/docs/cookbook/evaluate-and-optimize/jev-classification.md) for batch labeling with Choice categories and Noul tags
* [Classify Reddit and YouTube Comments with Jev](https://openrouter.ai/docs/cookbook/evaluate-and-optimize/classify-reddit-comments-with-jev.md) for scoring scraped comments on relevance and sentiment
* [Auto-Approve Coding Agent Permission Prompts with Jev](https://openrouter.ai/docs/cookbook/coding-agents/auto-approve-permission-prompts-with-jev.md) for answering Claude Code, Codex, Cursor, and OpenCode permission prompts with a Noul threshold
* [Jev Lab](https://openrouter.ai/labs/jev) for interactive demos of Jev's triage, extraction, and oversight patterns
* [TypeSafe documentation](https://docs.typesafe.ai) for System One concepts, question types, and SDK reference
