Go SDK

Typed API requests and incremental run streams using Go's standard HTTP client. Requires Go 1.23 or later.

Install from source

In your application's go.mod, require github.com/Macrofold/Macrofold/sdk/go v0.0.0 and add a local replacement:

go mod edit -require=github.com/Macrofold/Macrofold/sdk/go@v0.0.0
go mod edit -replace=github.com/Macrofold/Macrofold/sdk/go=/absolute/path/to/Macrofold/sdk/go

Connect and stream

Set AGENT_HOST, AGENT_API_KEY, and an authorized RUN_ID in your environment.

package main

import (
    "context"
    "fmt"
    "os"
    macrofold "github.com/Macrofold/Macrofold/sdk/go"
)

func main() {
    client, err := macrofold.NewClient(os.Getenv("AGENT_HOST"), os.Getenv("AGENT_API_KEY"))
    if err != nil { panic(err) }
    ctx := context.Background()
    projects, _, err := client.ProjectsAPI.ListProjects(ctx).Limit(20).Execute()
    if err != nil { panic(err) }
    fmt.Println(projects.Data)
    err = client.Stream(ctx, os.Getenv("RUN_ID"), "0", func(event macrofold.Event) error {
        fmt.Println(event.Type, event.Data)
        return nil
    })
    if err != nil { panic(err) }
}

Create and recover requests

After adding the client import to your application, run go mod tidy, then go run ..

API groups expose typed builders such as client.RunsAPI.CreateRun(ctx).IdempotencyKey(key).RunCreate(body).Execute(). Generate and retain a unique key per intended mutation. REST requests are single-attempt; retry an uncertain request with the identical body and key. Execute() returns the typed result, HTTP response, and error, including structured API errors when available.

File PUT uses an open *os.File, a path, and If-Match. Close file handles when finished. Monetary fields remain strings. Use XOrganizationId when a user token must select a membership; API keys stay bound to their organization.

Stream resumes after server rotation. Cancel the context or return an error from the callback to detach; call CancelRun explicitly to stop the remote agent. Preserve the last event sequence to resume across application restarts.

See the SDK guide and API quickstart.