# Go SDK (/sdk/go)



The Go SDK is a thin, standard-library-only client. It covers the core create/append flow and
diagnostics; the broader surface (get/delete, native `/v2` responses, purge, billing) is reachable by
calling the [HTTP API](/api-reference/introduction) directly.

## Install [#install]

```bash
go get github.com/yethdev/Zumik/sdks/go
```

Go 1.22+. No third-party dependencies.

## Authenticate [#authenticate]

```go
import zumik "github.com/yethdev/Zumik/sdks/go"

client := zumik.NewClient("zk_live_...")
// BaseURL defaults to https://api.zumik.ai; override client.BaseURL or client.HTTP if needed.
```

The key is an explicit argument. To set a timeout, assign your own `*http.Client` to `client.HTTP`.

## Usage [#usage]

Every method returns `(map[string]any, error)`.

```go
art, err := client.CreateArtifact("policy", "Run the linter before every commit.")
if err != nil {
    log.Fatal(err)
}

bundle, _ := client.CreateBundle([]map[string]any{
    {"artifact_id": art["id"], "role": "system"},
})
session, _ := client.CreateSession([]string{bundle["id"].(string)})

// Append an event with compare-and-swap (pass the CAS guards in the body map).
event, _ := client.AppendEvent(session["id"].(string), session["default_branch_id"].(string), map[string]any{
    "expected_version":        float64(0),
    "expected_head_event_id":  nil,
    "event":                   map[string]any{"event_type": "user_message", "payload_ref": art["id"]},
})

client.CreateSnapshot(session["id"].(string), session["default_branch_id"].(string),
    []string{art["id"].(string), event["id"].(string)})

resp, _ := client.CreateResponse("code.balanced", "Review the latest patch.")
fmt.Println(resp["id"])
```

## Methods [#methods]

| Method                                                          | Endpoint               |
| --------------------------------------------------------------- | ---------------------- |
| `CreateResponse(model string, input any)`                       | `POST /v1/responses`   |
| `CreateArtifact(artifactType, content string)`                  | `POST /v2/artifacts`   |
| `CreateBundle(items []map[string]any)`                          | `POST /v2/bundles`     |
| `CreateSession(baseBundleIDs []string)`                         | `POST /v2/sessions`    |
| `AppendEvent(sessionID, branchID string, body map[string]any)`  | `POST .../events`      |
| `CreateSnapshot(sessionID, branchID string, manifest []string)` | `POST .../snapshots`   |
| `RunDiagnostic(traces []map[string]any)`                        | `POST /v2/diagnostics` |

## Error handling [#error-handling]

On any status ≥ 400 the method returns a plain error:

```go
zumik api error (409): {"error":{"message":"...","type":"invalid_request_error","code":"branch_version_conflict"}}
```

Match on the embedded status/code text, or decode the body. The SDK does not stream or retry.

<Note>
  This SDK does not yet expose native `/v2` responses, get/delete, purge, usage, or credentials. For
  those, build requests against the [HTTP API](/api-reference/introduction) with `client.HTTP`.
</Note>