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

# Go SDK

> The official generated EvalGate REST client for Go.

The Go client covers the public OpenAPI operations with generated method,
parameter, request model, and response types. It uses the Go standard library.
Requires Go 1.23 or newer.

```sh theme={null}
go get github.com/evalgate/evalgate-go/v3@v3.17.0
go list -m github.com/evalgate/evalgate-go/v3
```

Run these commands from your Go module. A person must approve an
organization-scoped API key with `eval:read` for this first request. Store it as
`EVALGATE_API_KEY`. `EVALGATE_ORGANIZATION_ID` is optional when you need an
explicit organization selector; the key still determines authorization.
See [authentication](https://evalgate.com/docs/authentication.md) for the supported credential handoff.

Save this as `main.go` and run `go run .`. It reads one evaluation page and
prints the HTTP status:

```go theme={null}
package main

import (
    "context"
    "log"
    "os"

    evalgate "github.com/evalgate/evalgate-go/v3"
)

func main() {
    client, err := evalgate.NewClient(evalgate.Config{
        APIKey: os.Getenv("EVALGATE_API_KEY"),
        OrganizationID: os.Getenv("EVALGATE_ORGANIZATION_ID"),
    })
    if err != nil { log.Fatal(err) }
    response, err := client.GetEvaluations(context.Background(), evalgate.GetEvaluationsParams{
        Query: evalgate.GetEvaluationsQuery{Limit: evalgate.Ptr[int64](1)},
    })
    if err != nil { log.Fatal(err) }
    log.Printf("HTTP %d", response.StatusCode)
}
```

The SDK base origin is `https://www.evalgate.com`; generated operation paths
already include `/api`. Set `Config.BaseURL` for your own qualified instance.
The organization selector must match the credential's authorization. Mutation
scope requirements appear in `evalgate.Operations()` and OpenAPI.

Operation methods expose typed bodies and parameters. Unions that cannot use a
single Go type preserve `json.RawMessage`; free-form schema values preserve
maps or `any`. Responses include `Data`, `StatusCode`, and `Headers`.

Optional fields use a pointer to preserve presence. Leave the pointer `nil` to
omit the field; use `evalgate.Ptr([]string{})` or a pointer to an empty map to
send an explicit empty collection. For an optional nullable string such as a
workflow description, `evalgate.Ptr((*string)(nil))` sends JSON `null`, while
`evalgate.Ptr(evalgate.Ptr("updated"))` sends a value. Integer path parameters and
JSON values keep their exact decimal representation through the transport.
Generated model decoders preserve these presence states through JSON
decode-and-encode round trips, including nullable arrays and maps.

Inspect `*evalgate.APIError` with `errors.As` for structured failures, request IDs,
and live rate-limit headers. Honor `Retry-After` on a 429. The client never retries
automatically or follows redirects. Set `params.Options.IdempotencyKey` when
rescheduling a mutation with the same logical payload, and pass context deadlines.

`client.Paginate(ctx, operationID, params, maxPages, visit)` follows the generated
pagination contract. It detects repeated cursors, no progress, and page-bound
exhaustion. Use a disposable local instance through `Config.BaseURL` for tests.

This package is a generated REST client. For trace ingestion, follow the
[OpenTelemetry/OpenInference and collector guide](https://evalgate.com/docs/help/telemetry/first-trace.md)
with a compatible exporter. Native local runners and framework wrappers retain
their [documented language support](https://evalgate.com/docs/guides/agent-framework-integrations.md).
Explore public documentation and assertion test mode over HTTP without a key;
the Go SDK constructor requires an approved API key.

[Package source](https://github.com/evalgate/evalgate-go) ·
[API authentication](https://evalgate.com/docs/authentication.md) · [Contact](mailto:hello@evalgate.com)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.