Go SDK
The Steel SDK for Go is the module github.com/steel-dev/sdk/go, imported as steel. It gives your code methods for the endpoints of the Steel API, and it retries failed requests and pages through lists for you. The API reference shows the call for each endpoint.
Install
Each Go program in these docs is the main.go of a module. Create the module, then add the SDK:
go mod init example
go get github.com/steel-dev/sdk/goThe SDK needs Go 1.22 or later. Import it as steel:
import (
"github.com/steel-dev/sdk/go"
)Create a client
steel.NewClient() reads your API key from the STEEL_API_KEY environment variable. To change the key or another setting, pass options from the option package.
import (
"os"
"github.com/steel-dev/sdk/go"
"github.com/steel-dev/sdk/go/option"
)
client := steel.NewClient(
option.WithSteelAPIKey(os.Getenv("STEEL_API_KEY")),
)| Option | Default | Meaning |
|---|---|---|
option. | STEEL_API_KEY | The API key. |
option. | STEEL_BASE_URL, then https:// | The URL of the API. Change it to use a self-hosted Steel Browser. |
option. | 2 | How many times the SDK retries a request that failed. |
option. | none | How long each attempt of a request can take. |
option. | none | A header to send with the request. |
option. | an http. that waits at most 10 minutes for response headers | The HTTP client that sends the requests. |
option. | none | A function that runs around each request, for example to log it. |
The STEEL_CUSTOM_HEADERS environment variable adds headers to every request. Write one Name: value pair on each line.
You can pass the same options to a single method call. An option on a call overrides the option on the client.
Create a session
This program creates a session, prints its ID, and releases it. A session runs until you release it or until it times out, so release it in a defer.
package main
import (
"context"
"fmt"
"log"
"github.com/steel-dev/sdk/go"
)
func main() {
if err := run(context.Background()); err != nil {
log.Fatal(err)
}
}
func run(ctx context.Context) error {
client := steel.NewClient()
session, err := client.Sessions.New(ctx, steel.SessionNewParams{})
if err != nil {
return err
}
defer func() {
if _, err := client.Sessions.Release(ctx, session.ID); err != nil {
log.Print(err)
}
}()
fmt.Println(session.ID)
return nil
}Run the program:
go run .The program prints the session's ID.
ee60f12b-35e5-49f1-9eb4-6a86766a190aTo drive the session's browser, connect a CDP (Chrome DevTools Protocol) client to session.WebsocketURL. The URL holds a token for the session, so the client needs no API key.
Wrap each request field in steel.F. The wrapper marks the field as set, so the SDK can tell a set field from a zero value. The SDK does not send a field without the wrapper. Use steel.Null[T]() to send null.
params := steel.SessionListParams{
Status: steel.F(steel.SessionListParamsStatusLive),
}Session configuration lists every option of a new session.
Retries and timeouts
The SDK retries a request twice, with a short exponential backoff, after one of these failures:
- a connection error
408 Request Timeout409 Conflict429 Too Many Requests- a status of 500 or higher
A response with the x-should-retry header overrides this rule.
A request has no time limit by default. Set one for the whole call, retries included, with the context. Set one for each attempt with option.WithRequestTimeout.
import (
"time"
"github.com/steel-dev/sdk/go/option"
)
ctx, cancel := context.WithTimeout(ctx, 5*time.Minute)
defer cancel()
session, err := client.Sessions.New(
ctx,
steel.SessionNewParams{},
option.WithRequestTimeout(20*time.Second),
option.WithMaxRetries(5),
)Handle errors
Every method returns an error as its last value. When the API returns a status outside 2xx, the error is a *steel.Error. It holds StatusCode, the *http.Request, the *http.Response and the response's JSON body. Use errors.As to read it:
import "errors"
_, err := client.Sessions.New(ctx, steel.SessionNewParams{})
if err != nil {
var apierr *steel.Error
if errors.As(err, &apierr) {
fmt.Println(apierr.StatusCode)
fmt.Println(string(apierr.DumpResponse(true)))
}
return err
}For other failures, the method returns the underlying error. When the network fails, for example, you get a *url.Error.
Errors lists the error codes and messages of the API.
Pagination
client.Sessions.List returns its results in pages. ListAutoPaging reads every item and fetches the next page when it needs it:
iter := client.Sessions.ListAutoPaging(ctx, steel.SessionListParams{
Status: steel.F(steel.SessionListParamsStatusLive),
})
for iter.Next() {
session := iter.Current()
fmt.Println(session.ID, "started at", session.CreatedAt)
}
if err := iter.Err(); err != nil {
return err
}To read one page at a time, call List, then GetNextPage() on each page:
page, err := client.Sessions.List(ctx, steel.SessionListParams{})
for page != nil {
for _, session := range page.Sessions {
fmt.Println(session.ID)
}
page, err = page.GetNextPage()
}
if err != nil {
return err
}Methods
The Go SDK has the methods of the other SDKs, with Go names. Groups of methods are fields of the client, such as client.Sessions and client.Profiles. create is New and retrieve is Get, so sessions.create is client.Sessions.New. Each method takes a context.Context, then the path parameters, then a params struct.
The API reference documents each endpoint and its parameters. The SDK's own list of methods is api.md, and the types are on pkg.go.dev.