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

# Go

> The Go server SDK, package paddock: install, authenticate, and call every operation.

Package `paddock` is the Go client of paddock's API, for your backend. It needs Go 1.24 or later. Outside the standard library and its own module, it depends only on `github.com/google/uuid` and `google.golang.org/protobuf`.

## Install

```bash theme={null}
go get github.com/wenfengwang/paddock/sdk/go/paddock
```

> [!NOTE]
>
> The SDK lives in the `github.com/wenfengwang/paddock` module, beside `cloudagent`, the local runtime that runs Claude Code and Codex on your own machine. Package `paddock` never starts a harness; it only calls the hosted API.

## Create a client

```go theme={null}
import "github.com/wenfengwang/paddock/sdk/go/paddock"

client, err := paddock.NewClient(paddock.Options{}) // PADDOCK_API_KEY, PADDOCK_BASE_URL
if err != nil {
	return err
}
```

| `Options` field | Default |
| - | - |
| `APIKey` | `PADDOCK_API_KEY`, then `apiKey` of the [credentials file](https://docs.paddock.build/platform/authentication.md#api-keys) when the base URL is unset or the file's; `NewClient` fails when none is set |
| `BaseURL` | `PADDOCK_BASE_URL`, then `baseUrl` of the credentials file when the key is the file's, then `https://api.paddock.build/v1` |
| `MaxRetries` | 2 retries of idempotent requests; a pointer, so `paddock.Ptr(0)` turns them off |
| `Timeout` | 60 seconds per attempt; at least 10 minutes for files and memory. Streams have none |
| `HTTPClient` | A client with a 10-second connect timeout. Its own `Timeout` must be zero, or it ends streams |

A `Client` is safe for concurrent use.

## Conventions

* Every method takes a `context.Context` first. What it acts on and a value to store are plain arguments, as in `Get(ctx, id)`, `Send(ctx, text)`, and `Update(ctx, name, entry)`; options and filters are one struct named resource then verb, as in `paddock.SessionCreate` and `paddock.EventList`.
* `List` of a paged collection returns an `iter.Seq2[T, error]` over every item, fetching pages as you go; `ListPage` returns one page with `Data` and `NextCursor`. `Models.List` takes no parameters and is one page. Three lists are not paged this way: `Events.List` returns one `*EventPage` with `Data` and `HasMore`, paged by `After` and `Before`, and `Files.List` and `Memory.List` return a `[]FileEntry`.
* `Agent` and `Session` are data structs that also carry their sub-resources: `agent.MCP`, `agent.Sessions`, `agent.Files`, `session.Events`, `session.Turns`.
* Optional and nullable fields are pointers; `paddock.Ptr(v)` makes one.
* Message and tool types are the same types as package `cloudagent`'s: a `*paddock.ShellInput` from a remote message is a `*cloudagent.ShellInput`.

## The main flow

```go theme={null}
tpl, err := client.Templates.Create(ctx, "./agents/code-maintainer/template.yaml")
if err != nil {
	return err
}
agent, err := client.Agents.Create(ctx, paddock.AgentCreate{
	Template: fmt.Sprintf("%s@%d", tpl.Name, tpl.Version),
	Metadata: map[string]string{"teamId": "t_42"},
})
if err != nil {
	return err
}
session, err := agent.Sessions.Create(ctx, paddock.SessionCreate{Cwd: "repos/web"})
if err != nil {
	return err
}
sent, err := session.Send(ctx, "CI failed on main; fix it.")
if err != nil {
	return err
}

for ev, err := range session.Stream(ctx, paddock.StreamOptions{After: sent.Seq}) {
	if err != nil {
		return err // *paddock.Error, or an event that did not decode
	}
	if ev.Session != nil {
		continue // a snapshot of the session
	}
	switch e := ev.Event; {
	case e.Message != nil && e.Message.ToolCall != nil:
		if sh, ok := e.Message.ToolCall.Input.(*paddock.ShellInput); ok {
			fmt.Println("$", sh.Command)
		}
	case e.Message != nil && e.Message.Assistant != nil:
		fmt.Println(e.Message.Assistant.Text)
	case e.TurnEnded != nil:
		fmt.Println("turn", e.TurnEnded.Outcome)
		return nil
	}
}
```

A `StreamEvent` has exactly one of `Session` and `Event` set. An `Event` carries its envelope (`Seq`, `AgentID`, `SessionID`, `TurnID`, `CreatedAt`, `Type`) and one pointer field per event type: `Message`, `TurnStarted`, `TurnEnded`, `AgentUnavailable`, `DaemonOutdated`, `SessionStatus`, `ConfigApplied`, and `StatusUpdate`. A `Message` has a `Kind` and one non-nil payload: `User`, `Assistant`, `Reasoning`, `Streaming`, `ToolCall`, `ToolResult`, or `Unknown`. Cancel the context to close a stream.

## Operations

| Resource | Methods |
| - | - |
| `client.Templates` | `Create(ctx, path, ...TemplateCreate)`, `CreateDocument(ctx, doc, ...TemplateCreate)`, `Get(ctx, ref)`, `List`, `ListPage`, `Delete(ctx, "name@version")`. `TemplateCreate{DryRun: true}` checks without storing |
| `client.Models` | `List(ctx)`, `ListPage(ctx)` |
| `client.ModelProviders` | `List`, `ListPage`, `Get`, `Create`, `Update`, `Delete`, `Test(ctx, name, ProviderTestOptions)`, `TestDraft(ctx, ProviderDraft)` |
| `client.Agents` | `Create(ctx, AgentCreate)`, `Get(ctx, id)`, `List`, `ListPage`, `Delete(ctx, id)` |
| `agent.MCP`, `agent.Plugins`, `agent.Env` | `List`, `ListPage`, `Get`, `Add`, `Update`, `Delete` |
| `agent.Marketplaces` | The same, and `Refresh(ctx, name)` |
| `agent.ModelSetting`, `agent.SmallModelSetting`, `agent.SystemPrompt` | `Get`, `Set(ctx, value)`, `Delete` |
| `agent.Permissions` | `Get`, `Set(ctx, PermissionsSpec)` |
| `agent.Workflows` | `List`, `ListPage`, `Get` |
| `agent.Export(ctx)` | The agent's effective spec as a `TemplateDocument` |
| `agent.Memory` | `List`, `Read`, `Write`, `Delete` |
| `agent.Files` | `List(ctx, FileList)`, `Read`, `Write`, `Delete(ctx, path, FileDelete)` |
| `agent.Sessions` | `Create(ctx, SessionCreate)`, `List`, `ListPage` |
| `client.Sessions` | `Get(ctx, id)`, `List(ctx, ProjectSessionList)`, `ListPage`, `Delete(ctx, id)` |
| `session` | `Send(ctx, text)`, `Stop(ctx)`, `Stream(ctx, StreamOptions)`, `CreateToken(ctx, TokenCreate)` |
| `session.Events` | `List(ctx, EventList)` |
| `session.Turns` | `List`, `ListPage`, `Get(ctx, turnID)` |
| `client.Triggers` | `Create`, `Get`, `List`, `ListPage`, `Update`, `Delete`, `Test(ctx, TriggerTestRequest)` |
| `trigger.Secret` | `Get(ctx)`, `Rotate(ctx, SecretRotate)` |
| `trigger.Deliveries` | `List(ctx, DeliveryList)`, `ListPage`, `Get`, `Replay` |

What each operation does is in the guides: [Templates](https://docs.paddock.build/guides/templates.md), [Agents and sessions](https://docs.paddock.build/guides/agents-and-sessions.md), [Capabilities](https://docs.paddock.build/guides/capabilities.md), [Configuration](https://docs.paddock.build/guides/configuration.md), [Models](https://docs.paddock.build/guides/models.md), [Triggers](https://docs.paddock.build/guides/triggers.md), and [Files](https://docs.paddock.build/guides/files.md).

## Errors

A non-2xx answer is a `*paddock.Error` with `Status`, `Code`, `Message`, `Details`, and `RequestID`; codes are constants such as `paddock.CodeNotFound`. A request that got no answer is a `*paddock.ConnectionError` wrapping the cause, `context.DeadlineExceeded` on a timeout. Inspect both with `errors.As`. Idempotent requests are retried after a connection error, a timeout, or a `5xx`; a `POST` never is. See [Errors](https://docs.paddock.build/platform/errors.md).


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