---
title: "Go"
description: "The Go client for typeship's own API. Generated by typeship from its own spec, so it is also a sample of what your Go users get."
url: https://typeship.dev/docs/sdks/go
markdown: https://typeship.dev/docs/sdks/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 Go client for typeship's own API. Generated by typeship from its own spec, so it is also a sample of what your Go users get.

`github.com/typeship-ax/go` is the Go SDK for the typeship API, generated by typeship from [its own OpenAPI spec](https://typeship.dev/openapi.yaml). It has the same shape as every Go SDK typeship generates: `net/http` only, context-first methods, `(T, error)` returns, typed error structs, iterators for pagination, and gofmt-clean source. If you want to see what your Go users will get before you generate anything, read this module.

## Install

```bash
go get github.com/typeship-ax/go
```

Go 1.21 or newer. `go.mod` has no `require` block.

## Create a client

The module path ends in `go`, but the package it declares is `typeship`, which is the identifier the import binds and the one you type:

```go
import "github.com/typeship-ax/go"

client, err := typeship.New(typeship.WithBearerToken(os.Getenv("TYPESHIP_TOKEN")))
if err != nil {
	return err
}
```

The key comes from the console under **api keys**. Pass it, or set `TYPESHIP_TOKEN`. `New` takes the same options as any generated Go client: `WithBaseURL`, `WithTimeout`, `WithMaxRetries`, `WithHTTPClient`, `WithOnRequest`, `WithOnResponse`, `WithOnError`, `WithDebug`, and `WithValidation`. See [Go](https://typeship.dev/docs/platforms/sdk/go).

## Generate a package

`Generate.Run` runs the generator on a spec and returns the files. Nothing is stored. The free plan generates the first 25 operations; paid plans generate the whole spec:

```go
result, err := client.Generate.Run(ctx, &typeship.GenerateRunParams{
	Spec:      typeship.SpecInput{URL: typeship.Ptr("https://api.acme.example.com/openapi.json")},
	Platforms: []string{"sdk", "cli"},
	Language:  typeship.Ptr("go"),
})
if err != nil {
	return err
}
for _, file := range result.Files {
	path := filepath.Join("out", file.Path)
	os.MkdirAll(filepath.Dir(path), 0o755)
	os.WriteFile(path, []byte(file.Content), 0o644)
}
fmt.Println(*result.Meta.OperationCount, "operations")
```

## Work with projects

```go
project, err := client.Projects.Create(ctx, &typeship.ProjectsCreateParams{
	Name:      "Acme API",
	SpecURL:   typeship.Ptr("https://api.acme.example.com/openapi.json"),
	Platforms: []string{"sdk", "cli", "mcp"},
	Languages: []string{"typescript", "go"},
	Destinations: map[string]typeship.Destination{
		"typescript": {Repo: typeship.Ptr("acme/acme-node")},
		"go":         {Repo: typeship.Ptr("acme/acme-go")},
	},
	AutoRegen: typeship.Ptr(true),
})
if err != nil {
	return err
}

// Regenerate on demand. Each entry is a Generation or a GenerationFailure,
// so the item is a union with an accessor per variant.
generations, err := client.Projects.Generate(ctx, project.ID)
if err != nil {
	return err
}
for _, item := range generations.Data {
	if generation, err := item.AsGeneration(); err == nil && generation.Status == "succeeded" {
		fmt.Println(*generation.Language, *generation.Meta.FileCount)
	}
}

// Walk history: the iterator fetches every page.
it := client.Projects.ListGenerations(ctx, project.ID, nil)
for it.Next() {
	generation := it.Value()
	fmt.Println(generation.CreatedAt, generation.Trigger, generation.Status)
}
if err := it.Err(); err != nil {
	return err
}
```

## Every method

| Service        | Methods                                                                                                                                                           |
| -------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Generate`     | `Run(ctx, params)`                                                                                                                                                |
| `Projects`     | `List(ctx, params)`, `Create(ctx, params)`, `Get(ctx, id)`, `Update(ctx, id, params)`, `Delete(ctx, id)`, `Generate(ctx, id)`, `ListGenerations(ctx, id, params)` |
| `Generations`  | `Get(ctx, id)`, `GetFile(ctx, id, params)`                                                                                                                        |
| `SpecVersions` | `List(ctx, projectID, params)`, `Get(ctx, id)`, `GetContent(ctx, id)`                                                                                             |
| `Account`      | `Me(ctx)`                                                                                                                                                         |
| `Usage`        | `Retrieve(ctx)`                                                                                                                                                   |
| `APIKeys`      | `List(ctx, params)`, `Revoke(ctx, id)`                                                                                                                            |

Every method takes variadic `RequestOption`s last. Struct fields carry the API's `snake_case` names in their JSON tags. `api.md` inside the module is the complete reference, and the [API reference](https://typeship.dev/docs/api) has every schema.

## Errors

Every method returns `(T, error)`. Each documented status has its own type, and all of them unwrap to `*APIError`:

```go
_, err := client.Projects.Generate(ctx, "prj_...")

var payment *typeship.PaymentRequiredError
var notFound *typeship.NotFoundError
switch {
case errors.As(err, &payment):
	// free plan allowance used up; payment.Message says so
case errors.As(err, &notFound):
	// no such project on this account
}
```

See [Errors](https://typeship.dev/docs/typeship-api/api/errors) for the envelope and codes.

## Sitemap

[Every page of these docs](https://typeship.dev/llms.txt)