Opencode Go SDK

The SDK uses a generic Field[T] type for all request parameters. This distinguishes between a zero value (like 0, false, or "") and a field that is null or omitted.

• To send a value: Use opencode.F(value) or specific helpers like opencode.String(), opencode.Int(), or opencode.Float().
• To send null: Use opencode.Null[T]().
• To send a nonconforming type: Use opencode.Raw[T](value) (e.g., sending a float where an int64 is expected).

Any field not specified in the params struct is not sent in the request.

params := FooParams{
	Name: opencode.F("hello"),

	// Explicitly send `"description": null`
	Description: opencode.Null[string](),

	Point: opencode.F(opencode.Point{
		X: opencode.Int(0),
		Y: opencode.Int(1),

		// In cases where the API specifies a given type, but you want to send something else:
		Z: opencode.Raw[int64](0.01), // sends a float
	}),
}

Response fields are value types. If a field is null or missing in the API response, the SDK returns the Go zero value for that type.

To distinguish between a zero value and a missing/null field, use the .JSON property on the response struct. The .JSON field provides metadata about the raw response:

• res.JSON.Field.IsNull(): True if the field was explicitly null or not present.
• res.JSON.Field.IsMissing(): True if the key was not present in the JSON at all.
• res.JSON.Field.IsInvalid(): True if the data could not be coerced to the expected type. Use res.JSON.Field.Raw() to get the raw bytes for manual unmarshaling.
• res.JSON.ExtraFields(): Returns a map[string]Field containing properties present in the JSON that were not defined in the SDK's response struct.

if res.Name == "" {
	// true if `"name"` is either not present or explicitly null
	res.JSON.Name.IsNull()

	// true if the `"name"` key was not present in the response JSON at all
	res.JSON.Name.IsMissing()

	// When the API returns data that cannot be coerced to the expected type:
	if res.JSON.Name.IsInvalid() {
		raw := res.JSON.Name.Raw()

		legacyName := struct{
			First string `json:"first"`
			Last  string `json:"last"`
		}{}
		json.Unmarshal([]byte(raw), &legacyName)
		name = legacyName.First + " " + legacyName.Last
	}
}

// Accessing undocumented fields
body := res.JSON.ExtraFields["my_unexpected_field"].Raw()

The SDK uses the functional options pattern. You can provide RequestOption functions to the NewClient constructor (to apply to all requests) or to individual method calls.

Common options include:

• option.WithHeader(key, value): Adds or overrides an HTTP header.
• option.WithJSONSet(path, value): Adds an undocumented field to the request body using sjson syntax.
• option.WithMaxRetries(n): Sets the number of retries.
• option.WithResponseInto(&http.Response): Captures the raw HTTP response.

client := opencode.NewClient(
	// Adds a header to every request made by the client
	option.WithHeader("X-Some-Header", "custom_header_info"),
)

client.Session.List(context.TODO(), ...,
	// Override the header
	option.WithHeader("X-Some-Header", "some_other_custom_header_info"),
	// Add an undocumented field to the request body, using sjson syntax
	option.WithJSONSet("some.json.path", map[string]string{"my": "object"}),
)

If you need to interact with endpoints or parameters not explicitly defined in the SDK, you can use the following patterns:

Undocumented Endpoints

Use the client's HTTP verb methods (e.g., client.Get, client.Post). These respect client-level RequestOptions like retries.

Undocumented Parameters

Use option.WithQuerySet() for query parameters or option.WithJSONSet(path, value) for request body parameters (using sjson syntax).

Undocumented Response Properties

• Access the raw JSON string via result.JSON.RawJSON().
• Access a specific field's raw JSON via result.JSON.FieldName.Raw().
• Access extra fields via result.JSON.ExtraFields().

// Undocumented POST request
var result *http.Response
err := client.Post(context.Background(), "/unspecified", params, &result)

// Undocumented parameter via JSONSet
client.Foo.New(context.Background(), params, option.WithJSONSet("data.last_name", "Doe"))

Timeouts

Requests do not time out by default. Use context.Context to set a lifecycle timeout.

Note: If a request is retried, the context timeout does not reset. To set a timeout for each individual retry attempt, use option.WithRequestTimeout(duration).

Retries

By default, the SDK retries certain errors 2 times with exponential backoff. Retried errors include connection errors, 408 Request Timeout, 409 Conflict, 429 Rate Limit, and any error >= 500.

You can configure or disable retries using option.WithMaxRetries(n) at the client level or per-request.

// Set a global timeout for the entire operation (including retries)
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

client.Session.List(
	ctx,
	opencode.SessionListParams{},
	// Set a per-retry timeout
	option.WithRequestTimeout(20*time.Second),
)

// Configure max retries
client := opencode.NewClient(option.WithMaxRetries(0)) // Disable retries