Go SDK

The gcore-go module provides typed access to the Gcore REST API from Go 1.22+. Generated from the OpenAPI specification using Stainless, request structs use Go’s type system and mark JSON fields with omitzero, which takes effect in Go 1.24 and later. Responses are strongly typed structs with a .JSON metadata field for optional field inspection. Module: github.com/G-Core/gcore-go · Source: gcore-go on GitHub

Install

go get github.com/G-Core/gcore-go

To pin a version, use a tag from the gcore-go releases.

Initialize the client

gcore.NewClient() returns a value type (gcore.Client), not a pointer. The client reads GCORE_API_KEY, GCORE_CLOUD_PROJECT_ID, and GCORE_CLOUD_REGION_ID from the environment by default:

package main

import (
    "context"
    "fmt"

    gcore "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cloud"
)

func main() {
    client := gcore.NewClient()
}

First call

List all instances in a project and region:

// Uses GCORE_CLOUD_PROJECT_ID and GCORE_CLOUD_REGION_ID read by gcore.NewClient()
ctx := context.Background()
page, err := client.Cloud.Instances.List(ctx, cloud.InstanceListParams{})
if err != nil {
    panic(err)
}
for _, inst := range page.Results {
    fmt.Println(inst.ID, inst.Name)
}

Request parameters

Required primitive fields carry the tag `api:"required"` and are always serialized, even when zero. Optional fields are wrapped in param.Opt[T] and set using the provided constructors:

params := cloud.InstanceNewParams{
    Flavor: "g2-standard-2-4",         // required string - always serialized
    Name:   gcore.String("my-vm"),     // optional - use gcore.String(), gcore.Int(), etc.
}

To send null for an optional field instead of omitting it:

params.Name = param.Null[string]()

Flavor IDs are region-specific. Run client.Cloud.Instances.Flavors.List(ctx, params) to see what flavors are available in a given region before creating an instance.

Task polling

Cloud API write operations return a task ID. Use NewAndPoll methods where available - they submit the request and block until the resource is ready:

imageID := os.Getenv("IMAGE_ID")

instance, err := client.Cloud.Instances.NewAndPoll(ctx, cloud.InstanceNewParams{
    Flavor: "g2-standard-2-4",
    Name:   gcore.String("my-vm"),
    Interfaces: []cloud.InstanceNewParamsInterface{
        {Type: cloud.InstanceNewParamsInterfaceTypeExternal},
    },
    Volumes: []cloud.InstanceNewParamsVolume{{
        Source:    cloud.InstanceNewParamsVolumeSourceImage,
        ImageID:   gcore.String(imageID),
        Size:      gcore.Int(20),
        BootIndex: gcore.Int(0),
    }},
})
if err != nil {
    panic(err)
}
fmt.Println(instance.ID)

When NewAndPoll is not available for a resource, poll with client.Cloud.Tasks.Poll directly:

taskList, err := client.Cloud.SomeResource.New(ctx, params)
if err != nil {
    panic(err)
}

task, err := client.Cloud.Tasks.Poll(ctx, taskList.Tasks[0])
if err != nil {
    panic(err)
}

// task.CreatedResources is a typed struct
fmt.Println(task.CreatedResources.Instances[0])

task.CreatedResources is a typed struct. Access fields as task.CreatedResources.Instances[0], not as a map. The client.Cloud.Tasks.Get(ctx, taskID) method takes only the task ID string - no project or region parameters.

Pagination

Use ListAutoPaging() to iterate across all pages automatically:

iter := client.Cloud.Projects.ListAutoPaging(ctx, cloud.ProjectListParams{
    Limit: gcore.Int(10),
})
for iter.Next() {
    project := iter.Current()
    fmt.Printf("%+v\n", project)
}
if err := iter.Err(); err != nil {
    panic(err)
}

For manual page control:

page, err := client.Cloud.Projects.List(ctx, cloud.ProjectListParams{
    Limit: gcore.Int(10),
})
for page != nil {
    for _, project := range page.Results {
        fmt.Println(project.ID, project.Name)
    }
    page, err = page.GetNextPage()
}
if err != nil {
    panic(err)
}

Error handling

Use errors.As to inspect API errors:

import "errors"

_, err := client.Cloud.Projects.New(ctx, cloud.ProjectNewParams{
    Name: "my-project",
})
if err != nil {
    var apierr *gcore.Error
    if errors.As(err, &apierr) {
        fmt.Println(string(apierr.DumpRequest(true)))
        fmt.Println(string(apierr.DumpResponse(true)))
    }
    panic(err)
}

Retries and timeouts

The client retries connection errors, 408, 409, 429, and 5xx errors twice by default. Requests have no default timeout - use context to set one:

// Set a 5-minute budget for the request including all retries
ctx, cancel := context.WithTimeout(context.Background(), 5*time.Minute)
defer cancel()

client.Cloud.Projects.New(
    ctx,
    cloud.ProjectNewParams{Name: "my-project"},
    option.WithRequestTimeout(20*time.Second), // per-retry timeout
)

Disable or configure retries:

// Globally
client := gcore.NewClient(option.WithMaxRetries(0))

// Per request
client.Cloud.Projects.New(ctx, params, option.WithMaxRetries(5))

Middleware

Apply custom logic to all requests using option.WithMiddleware:

func Logger(req *http.Request, next option.MiddlewareNext) (*http.Response, error) {
    start := time.Now()
    res, err := next(req)
    fmt.Printf("%s %s %v\n", req.Method, req.URL, time.Since(start))
    return res, err
}

client := gcore.NewClient(
    option.WithMiddleware(Logger),
)

When multiple middleware functions are provided, they run left to right. Client-level middleware runs before per-request middleware.

Accessing raw response data

Use option.WithResponseInto() to capture the raw HTTP response alongside the parsed result:

var response *http.Response
project, err := client.Cloud.Projects.New(
    ctx,
    cloud.ProjectNewParams{Name: "my-project"},
    option.WithResponseInto(&response),
)
fmt.Printf("Status: %d\n", response.StatusCode)
fmt.Printf("Headers: %+v\n", response.Header)

Developer Tools

REST API

SDKs

MCP Server

Terraform

Grafana

Install

Initialize the client

First call

Request parameters

Task polling

Error handling

Retries and timeouts

Middleware

Accessing raw response data

​Install

​Initialize the client

​First call

​Request parameters

​Task polling

​Pagination

​Error handling

​Retries and timeouts

​Middleware

​Accessing raw response data

Install

Initialize the client

First call

Request parameters

Task polling

Pagination

Error handling

Retries and timeouts

Middleware

Accessing raw response data