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

# plungeai-go

> The official Go SDK for the One API — typed resources, streaming, pagination, retries and errors, generated from the OpenAPI document; standard library only.


The official Go SDK for the PlungeAI One API (`https://api.plungeai.com`). Targets One API `2.4.0`; module version `1.0.0`. The resource methods and their types are generated from the API's own OpenAPI document (`GET /v1/openapi.json`). Standard library only.

Release status: `go list -m -versions github.com/PlungeAI/plungeai-go`; until it answers, use a `replace` directive to `sdk/one-api-go/` in the platform repository.

## Installation

```sh
go get github.com/PlungeAI/plungeai-go
```

## Usage

```go
import "github.com/PlungeAI/plungeai-go"

client := plungeai.NewClient() // reads PLUNGEAI_API_KEY; or plungeai.NewClient(plungeai.WithAPIKey("ozk_…"))
ctx := context.Background()

me, err := client.Whoami(ctx)
run, err := client.Agents.Execute(ctx, "calculator-agent", plungeai.AgentExecuteParams{Prompt: "6*7"})
hits, err := client.Discovery.Search(ctx, plungeai.DiscoverySearchParams{Q: "web search", Kind: "agents"})
```

Every method takes a `context.Context` first, then the path parameters, then a params struct (`plungeai.<Resource><Method>Params`), then optional request options. Responses are pointers to generated structs; nested resources are fields (`client.Workflows.Versions.List(ctx, workflowID)`).

## Streaming responses

```go
stream, err := client.Workflows.ExecuteInlineStream(ctx, plungeai.WorkflowExecuteInlineStreamParams{Workflow: workflow})
if err != nil {
    return err
}
defer stream.Close()
for stream.Next() {
    ev := stream.Current()
    if ev.Event == "token" {
        var token struct{ Delta string `json:"delta"` }
        _ = ev.JSON(&token)
        fmt.Print(token.Delta)
    }
}
if err := stream.Err(); err != nil {
    return err
}
```

`ev.Data` is the raw string of the server-sent event; `ev.JSON(&v)` decodes it. Cancelling `ctx` stops the stream. Methods that accept `stream: true` on the API have a `…Streaming` twin (`client.Agents.ExecuteStreaming`, `client.Chat.Completions.CreateStreaming`) returning the same `*Stream`.

## Auto-pagination

```go
pager := client.Workflows.ListAutoPaging(ctx, plungeai.WorkflowListParams{Kind: "bot"})
for pager.Next() {
    fmt.Println(pager.Current())
}
if err := pager.Err(); err != nil {
    return err
}

page, err := client.Workflows.List(ctx, plungeai.WorkflowListParams{Limit: 50})
for err == nil {
    for _, w := range page.Data {
        fmt.Println(w)
    }
    if !page.HasNextPage() {
        break
    }
    page, err = page.GetNextPage(ctx)
}
```

## Handling errors

```go
_, err := client.Agents.Execute(ctx, "calculator-agent", plungeai.AgentExecuteParams{Prompt: "6*7"})
var apiErr *plungeai.Error
if errors.As(err, &apiErr) {
    switch apiErr.StatusCode {
    case 424:
        fmt.Println(apiErr.Connect.Link)
    default:
        fmt.Println(apiErr.StatusCode, apiErr.Code, apiErr.RequestID)
    }
}
```

One error type, `*plungeai.Error`, carries `StatusCode`, `Code` (the envelope's `error.code`), `Message`, `RequestID` (the `x-request-id` header) and, on 424, `Connect` (`Provider`, `Method`, `Link` — where to connect the missing account). A request that never got a response returns the transport error (`errors.Is(err, context.DeadlineExceeded)` on timeout); a missing key returns `plungeai.ErrMissingAPIKey`.

## Retries

Failed requests are retried 2 times by default with short exponential backoff (honouring `Retry-After`): connection errors, timeouts, 408, 429 and ≥ 500. 409 and 424 are never retried — on the One API they are semantic answers (`approval_required`, `duplicate_execution_id`, a missing connection), and a retried execute would start a second run. Set the count on the client or per call:

```go
client := plungeai.NewClient(plungeai.WithMaxRetries(0))
client.Agents.Execute(ctx, "calculator-agent", plungeai.AgentExecuteParams{Prompt: "6*7"}, plungeai.WithMaxRetries(5))
```

`plungeai.WithIdempotencyKey(key)` is sent as `x-trace-id`, the API's idempotency key: it becomes the run's execution id, is re-sent on every retry of the call, and a replay answers 409 `duplicate_execution_id`.

## Timeouts

Each attempt times out after 10 minutes by default (retried as above). Set it on the client or per call: `plungeai.WithRequestTimeout(20 * time.Second)`. A deadline on `ctx` bounds the whole call, retries included.

## Raw responses

```go
var raw *http.Response
run, err := client.Agents.Execute(ctx, "calculator-agent", plungeai.AgentExecuteParams{Prompt: "6*7"}, plungeai.WithResponseInto(&raw))
fmt.Println(raw.StatusCode, raw.Header.Get("x-request-id"))
```

`plungeai.WithHeader(name, value)` and `plungeai.WithQuery(name, value)` add to any request; `client.Get(ctx, path, params, &out)`, `client.Post(ctx, path, body, &out)` and friends reach routes the generated layer does not cover; the root `POST /v1/execute` is `client.ExecuteCall` (the name `Execute` is the generic request method).

## Models plane

`client.Chat.Completions.Create` (plus `client.Embeddings` and `client.Models`) covers the OpenAI-compatible routes here; any OpenAI client also works with base URL `https://api.plungeai.com/v1` and the same key.

## Requirements

Go 1.24 or newer. The module is published from the public repository `github.com/PlungeAI/plungeai-go`; its source of truth is `sdk/one-api-go/` in the platform repository.