Skip to main content
This guide will help you make your first API call using the Gcore Go SDK. We’ll create a simple application that creates a new Cloud project.

​
Prerequisites

Before you begin, make sure you have:
  • Go 1.22 or higher installed
  • A Gcore account with an API key
  • The Gcore Go SDK installed (see Installation)

​
Complete Example

Here’s a complete working example that creates a new Cloud project:
main.go
package main

import (
    "context"
    "fmt"

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

func main() {
    client := gcore.NewClient(
        option.WithAPIKey("My API Key"), // defaults to os.LookupEnv("GCORE_API_KEY")
    )
    project, err := client.Cloud.Projects.New(context.TODO(), cloud.ProjectNewParams{
        Name: "my-project",
    })
    if err != nil {
        panic(err.Error())
    }
    fmt.Printf("%+v\n", project.ID)
}

​
Step-by-Step Walkthrough

Let’s break down the example above into steps:
1

Import required packages

Import the Gcore SDK and related packages you’ll need:
import (
    "context"
    "fmt"

    "github.com/G-Core/gcore-go"
    "github.com/G-Core/gcore-go/cloud"
    "github.com/G-Core/gcore-go/option"
)
  • gcore - Main SDK package
  • cloud - Cloud services (projects, instances, volumes, etc.)
  • option - Request options for configuring the client and requests
2

Create a client instance

Initialize the Gcore client with your API key:
client := gcore.NewClient(
    option.WithAPIKey("My API Key"),
)
If you don’t provide an API key, the client will automatically look for the GCORE_API_KEY environment variable. This is the recommended approach for production applications.
Using environment variables (recommended):
// Reads GCORE_API_KEY from environment
client := gcore.NewClient()
3

Make your first API call

Use the client to create a new Cloud project:
project, err := client.Cloud.Projects.New(context.TODO(), cloud.ProjectNewParams{
    Name: "my-project",
})
if err != nil {
    panic(err.Error())
}
The SDK uses the standard Go context package for request lifecycle management. Use context.TODO() for simple examples, or pass a more specific context for production code.
4

Handle the response

Process the API response:
fmt.Printf("%+v\n", project.ID)
All response objects in the SDK are strongly typed structs with fields matching the API response. You can access any field directly:
fmt.Printf("Project ID: %d\n", project.ID)
fmt.Printf("Project Name: %s\n", project.Name)

​
Running Your Code

Save the code to a file (e.g., main.go) and run it: 
go run main.go
You should see output similar to: 
123456

​
Error Handling

The SDK returns detailed error information when requests fail. Here’s how to handle errors properly: 
import (
    "errors"
    "fmt"
    "github.com/G-Core/gcore-go"
)

project, err := client.Cloud.Projects.New(context.TODO(), cloud.ProjectNewParams{
    Name: "my-project",
})
if err != nil {
    // Check if it's an API error
    var apierr *gcore.Error
    if errors.As(err, &apierr) {
        fmt.Printf("API Error: %d - %s\n", apierr.StatusCode, apierr.Message)
        // Debug: print full request/response
        fmt.Println(string(apierr.DumpRequest(true)))
        fmt.Println(string(apierr.DumpResponse(true)))
        return
    }
    // Handle other errors (network, etc.)
    panic(err.Error())
}

​
Common Operations

Here are a few more examples of common operations:

​
List Resources

// List all projects
iter := client.Cloud.Projects.ListAutoPaging(context.TODO(), cloud.ProjectListParams{
    Limit: gcore.Int(10),
})
for iter.Next() {
    project := iter.Current()
    fmt.Printf("Project: %s (ID: %d)\n", project.Name, project.ID)
}
if err := iter.Err(); err != nil {
    panic(err.Error())
}

​
Using Context for Timeouts

import "time"

ctx, cancel := context.WithTimeout(context.Background(), 30*time.Second)
defer cancel()

project, err := client.Cloud.Projects.New(ctx, cloud.ProjectNewParams{
    Name: "my-project",
})

​
Configuring Request Options

// Add custom headers or override defaults per-request
project, err := client.Cloud.Projects.New(
    context.TODO(),
    cloud.ProjectNewParams{
        Name: "my-project",
    },
    option.WithHeader("X-Custom-Header", "value"),
    option.WithMaxRetries(5),
)

​
Next Steps

Now that you’ve made your first API call, explore more features:

Authentication

Learn about different authentication methods

Core Concepts

Understand pagination, error handling, and more

Cloud Services

Explore Cloud resources like instances and volumes

API Reference

Browse the complete API documentation

Build docs developers (and LLMs) love

Get started for freeTalk to us