plungeai-go

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

go get github.com/PlungeAI/plungeai-go

Usage

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

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

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

_, 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:

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

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.