> ## Documentation Index
> Fetch the complete documentation index at: https://typesafe-sdk-go.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# API Reference

> Client, questions, answers, and errors

Full generated reference: [pkg.go.dev](https://pkg.go.dev/github.com/atharvamhaske/typesafe-sdk-go). The upstream contract is in [openapi.json](https://github.com/atharvamhaske/typesafe-sdk-go/blob/main/openapi.json), fetched from `https://api.typesafe.ai/openapi.json`.

## Client

```go theme={null}
client, err := typesafe.NewClient(opts ...Option)
```

<ParamField path="WithAPIKey" type="Option">
  Sets the API key, overriding `TYPESAFE_API_KEY`.
</ParamField>

<ParamField path="WithBaseURL" type="Option">
  Sets the base URL, overriding `TYPESAFE_BASE_URL`.
</ParamField>

<ParamField path="WithModel" type="Option">
  Sets the default model, overriding `TYPESAFE_DEFAULT_MODEL`.
</ParamField>

<ParamField path="WithHTTPClient" type="Option">
  Sets the underlying `*http.Client`.
</ParamField>

<ParamField path="WithMaxRetries" type="Option">
  Sets the retry count for network errors, 429s, and 5xxs. Default 3.
</ParamField>

<ParamField path="WithCache" type="Option">
  Turns on an in-memory cache for `SystemOne` responses. Off by default.
</ParamField>

## Caching, from first principles

A decision has a shelf life. The same question, asked about the same state, has one right answer until the state changes. A cache stores that answer, keyed on the full request, not on the words used to ask for it.

The cache is off by default. A stale decision looks exactly like a fresh one, and the cost of acting on a wrong decision is usually higher than the cost of one repeated API call. Turn the cache on only when you know a state repeats, and a few seconds of staleness is acceptable.

The cache check runs before the network call, not after. A cache hit skips the retry loop too, since there is no network call to retry.

`SystemOne` is the only cached call. `ListModels` rarely changes and is rarely called, so it is not worth a cache entry. An error response is never cached: an error is not a decision.

<CodeGroup>
  ```go client.go theme={null}
  client, err := typesafe.NewClient(
      typesafe.WithCache(1000, 5*time.Minute), // 1000 entries, 5-minute TTL
  )
  ```
</CodeGroup>

## SystemOne

`POST /v1/systemone`

```go theme={null}
resp, err := client.SystemOne(ctx, state string, questions map[string]Question, opts ...SystemOneOption)
```

`typesafe.WithRequestModel(model string)` overrides the model for a single call.

### Question types

All three implement the `Question` interface.

<ParamField path="Choice" type="struct">
  `Instructions string`, `Criteria map[string]string`. Picks one named option.
</ParamField>

<ParamField path="Score" type="struct">
  `Instructions string`, `Criteria []string`. Rates on an ordered scale.
</ParamField>

<ParamField path="Noul" type="struct">
  `Instructions string`, `Criteria map[string]string`. Answers true or false with a probability.
</ParamField>

### Response

<ResponseField name="Model" type="string" />

<ResponseField name="Usage" type="Usage">
  `InputTokens`, `OutputTokens`
</ResponseField>

<ResponseField name="Choices()" type="map[string]ChoiceAnswer">
  `Choice`, `Confidence`, `Probabilities`
</ResponseField>

<ResponseField name="Scores()" type="map[string]ScoreAnswer">
  `Score`, `Confidence`, `Legend`, `Probabilities`
</ResponseField>

<ResponseField name="Nouls()" type="map[string]NoulAnswer">
  `Noul`
</ResponseField>

## ListModels

`GET /v1/models`

```go theme={null}
models, err := client.ListModels(ctx)
```

Returns `[]Model`, each with `Name`, `Description`, `ReleaseDate`.

## Errors

Non-2xx responses return `*typesafe.Error`:

<ResponseField name="StatusCode" type="int" />

<ResponseField name="Detail" type="json.RawMessage">
  Validation detail, when the API returns one.
</ResponseField>

<ResponseField name="Body" type="[]byte">
  The raw response body.
</ResponseField>