--- title: "Go" description: "The generated Go SDK: context-first methods, (T, error) returns, typed error structs, and gofmt-clean output on net/http alone." url: https://typeship.dev/docs/platforms/sdk/go markdown: https://typeship.dev/docs/platforms/sdk/go.md section: "Get started" --- > ## Documentation index > Fetch the complete documentation index at https://typeship.dev/llms.txt (every page, one line each) or the full text at https://typeship.dev/llms-full.txt. > Append .md to any docs URL, or send Accept: text/markdown, for the markdown twin of that page. # Go The generated Go SDK: context-first methods, (T, error) returns, typed error structs, and gofmt-clean output on net/http alone. The Go SDK shares the [SDK](https://typeship.dev/docs/platforms/sdk) feature set: typed payloads and errors, auto-pagination, retries, hooks, validation, webhooks, and streaming. This page covers what is specific to the Go module. Go packages are SDK-only. The CLI and MCP server are TypeScript platforms. ## Module * The module path comes from the project's Go destination repository: `github.com/acme/acme-go`. Configure it in the console, or override it per project under **package names**. Until a repository is set, the module path is a placeholder that `go get` cannot resolve. * The package name is read off the module path the way the Go ecosystem reads it. `github.com/stripe/stripe-go` is `package stripe`. A major-version suffix is ignored. * `go.mod` has no `require` block. The runtime is `net/http` and the standard library. * Every file passes `gofmt -l`. Every generation is gated on `go build`, `go vet`, and `gofmt`. ## Idioms * **Context first.** Every method takes a `context.Context`. Cancel it to abort a request, a paginated iteration, or a stream. * **`(T, error)` returns.** Methods with no response body return `error` alone. * **Params by pointer.** Query and header parameters, and the fields of an inline object body, live in one `XxxParams` struct passed by pointer. `nil` means no parameters. Optional fields are pointers so absent and zero stay distinct; `acme.Ptr(v)` makes one inline. * **Named bodies are arguments.** A request body that is a `$ref` to a named schema, an array, or plain text is a positional `body` argument with its own type (`AccountParams`, `[]AccountParams`, `string`), so a required body is enforced by the compiler. * **Functional options.** `acme.New(acme.WithBearerToken(...), acme.WithTimeout(...))` for the client, `acme.WithRequestTimeout(...)` and friends per call. * **Iterators.** `it := client.Accounts.List(ctx, nil)`, then `for it.Next() { it.Value() }` and `it.Err()`. * **Initialisms.** Identifiers follow Go's convention: `ID`, `AccountID`, `URL`, `HTTPStatus`. ## Environment variables `New` reads these before options apply, so options always win: | Variable | Sets | | --------------------------------- | --------------------------------------- | | `ACME_TOKEN` | bearer token | | `ACME_API_KEY` | the API key, when the spec declares one | | `ACME_USERNAME` / `ACME_PASSWORD` | basic auth | | `ACME_BASE_URL` | base URL | | `ACME_WEBHOOK_KEY` | webhook key | The prefix comes from your package name. ## Errors `APIError` carries `Status`, `Body []byte`, `RequestID`, and `Message`, plus a `Decode(v any) error` helper for the body. Per-status types such as `*NotFoundError` embed `APIError`, so `errors.As` matches at either precision. An undocumented status returns a bare `*APIError`. No response at all returns `*TransportError` with `Method`, `URL`, and a wrapped `Err`. A cancelled context returns `ctx.Err()`. ## Webhooks `client.Webhooks.Unwrap(payload, header)` verifies and returns a `*WebhookEvent` carrying `Type` and the raw `Data`. Go has no sum types, so each declared event gets an accessor: `event.AsAccountUpdated()` returns the typed payload or an error if the type does not match. Events your module has not seen yet still arrive intact. `VerifyWebhook` and `SignWebhook` are exported for handlers that do not hold a client. ## Streaming `client.Events.Stream(ctx)` returns a `*Stream`. Read it like `bufio.Scanner`: `Next`, `Event` (an `SSEEvent`), `Err`, and `Close`. The stream uses a copy of the HTTP client with no timeout, so cancel through the context. ## Uploads A `multipart/form-data` field is an `acme.Upload{Name, ContentType, Reader}` on the params struct: the name and content type the server sees, and an `io.Reader` for the bytes. The other fields travel alongside as form parts. A raw binary body (`application/octet-stream`, `image/png`, ...) is a positional `body io.Reader`, sent under the spec's content type. ## Unions Go has no sum types. A `oneOf`/`anyOf` becomes a named union type that holds the JSON as received and decodes on request: `As() (Variant, error)` and `From(v)` per variant, `Raw()` for the bytes, and `Discriminator()` when the spec names one. It is the same shape oapi-codegen generates, and the same accessor pattern the webhook events use. A struct that pretended to be a union would silently drop fields; `any` would drop the typing. ## Response metadata `WithAPIResponse(&meta)` on any call fills an `APIResponse{StatusCode, Header, RequestID}` from the last HTTP response (rate-limit headers, a `Location`, a request id to quote) without going through the global `WithOnResponse` hook. ## GraphQL A GraphQL schema generates one method per query and mutation field on `client.Query` and `client.Mutation`. Arguments are the params struct and become variables. Every scalar field to depth 2 is selected by default, with a fragment per concrete type for unions and interfaces, and `WithSelection("{ id name }")` overrides that per call on methods that return an object. Connection fields return an `*Iter[T]` like everything else. Errors in a `200` return `*GraphQLError` (which unwraps to `*APIError`) carrying the raw `Errors`. ## Sitemap [Every page of these docs](https://typeship.dev/llms.txt)