Documentation Index
Fetch the complete documentation index at: https://gcore.com/docs/llms.txt
Use this file to discover all available pages before exploring further.
Gcore publishes official SDKs for Python and Go, both auto-generated from the OpenAPI specification — method names and parameter names match the API reference exactly.
Python SDK
Package: gcore on PyPI · Source: gcore-python on GitHub
Requirements
Python 3.8 or higher is required. Check the installed version:
Install
Install the package with pip:
Using a virtual environment avoids dependency conflicts with other projects:
python3 -m venv .venv
source .venv/bin/activate # On Windows: .venv\Scripts\activate
pip install gcore
Initialize the client
Always read the API key from an environment variable — never hardcode it in source files:
import os
from gcore import Gcore
client = Gcore(api_key=os.environ["GCORE_API_KEY"])
First call
These calls verify authentication, list projects, and list regions with VM support:
# Verify authentication
me = client.iam.get_account_overview()
print(me.id, me.email)
# List projects
for project in client.cloud.projects.list().results:
print(project.id, project.name)
# List regions
for region in client.cloud.regions.list().results:
if region.state == "ACTIVE" and region.has_kvm:
print(region.id, region.display_name)
Method naming pattern
SDK methods map directly to API endpoints:
| Endpoint | SDK method |
|---|
GET /cloud/v1/instances/{project_id}/{region_id} | client.cloud.instances.list(project_id=..., region_id=...) |
POST /cloud/v2/instances/{project_id}/{region_id} | client.cloud.instances.create(project_id=..., region_id=..., ...) |
GET /cloud/v1/instances/{project_id}/{region_id}/{instance_id} | client.cloud.instances.get(instance_id=..., project_id=..., region_id=...) |
DELETE /cloud/v1/instances/{project_id}/{region_id}/{instance_id} | client.cloud.instances.delete(instance_id=..., project_id=..., region_id=...) |
GET /cloud/v1/flavors/{project_id}/{region_id} | client.cloud.instances.flavors.list(project_id=..., region_id=...) |
POST /cloud/v2/volumes/{project_id}/{region_id}/{volume_id}/attach | client.cloud.volumes.attach_to_instance(volume_id=..., ...) |
GET /cloud/v1/tasks/{task_id} | client.cloud.tasks.get(task_id) |
Polling task completion
The SDK includes a built-in blocking poll — no manual loop needed:
result = client.cloud.instances.create(
project_id=int(os.environ["PROJECT_ID"]),
region_id=int(os.environ["REGION_ID"]),
flavor="g1-standard-2-4",
ssh_key_name="my-key",
interfaces=[{"type": "external"}],
volumes=[{"source": "image", "image_id": os.environ["IMAGE_ID"],
"size": 20, "boot_index": 0}],
name="my-vm",
)
# tasks.poll() blocks until state is FINISHED or ERROR
task = client.cloud.tasks.poll(
result.tasks[0],
polling_interval_seconds=5,
polling_timeout_seconds=300,
)
# Access created resource IDs via attributes, not dict keys
instance_id = task.created_resources.instances[0]
volume_id = task.created_resources.volumes[0]
Async and sync support
The gcore package supports both sync and async usage:
# Sync (default)
from gcore import Gcore
client = Gcore(api_key=os.environ["GCORE_API_KEY"])
# Async
import asyncio
from gcore import AsyncGcore
async def main():
async with AsyncGcore(api_key=os.environ["GCORE_API_KEY"]) as client:
me = await client.iam.get_account_overview()
print(me.email)
asyncio.run(main())
Go SDK
Module: github.com/G-Core/gcore-go · Source: gcore-go on GitHub
Install
Add the module to the project:
go get github.com/G-Core/gcore-go
Initialize the client
Construct the client using the API key from the environment:
package main
import (
"context"
"fmt"
"os"
"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(os.Getenv("GCORE_API_KEY")),
)
}
First call
This example lists all instances in a given project and region:
// Replace these with the actual project and region IDs
var projectID int64 = 1234567
var regionID int64 = 76
page, err := client.Cloud.Instances.List(context.TODO(), cloud.InstanceListParams{
ProjectID: gcore.Int(projectID),
RegionID: gcore.Int(regionID),
})
if err != nil {
panic(err)
}
for _, inst := range page.Results {
fmt.Println(inst.ID, inst.Name)
}
JavaScript
No dedicated JavaScript SDK is published, so use the built-in fetch API (Node.js 18+, all modern browsers) or the popular axios library.
The $ character in Gcore tokens requires no escaping in JavaScript — template literals handle it correctly.
Node.js fetch (built-in, Node 18+)
Both GET and POST requests follow the same pattern — add the Authorization header to every request:
const BASE_URL = 'https://api.gcore.com';
const TOKEN = process.env.GCORE_API_KEY; // no escaping needed
// GET — verify token
const res = await fetch(`${BASE_URL}/iam/clients/me`, {
headers: { Authorization: `APIKey ${TOKEN}` },
});
const account = await res.json();
console.log(account.id, account.email);
// POST — create a network
const netRes = await fetch(
`${BASE_URL}/cloud/v1/networks/${process.env.PROJECT_ID}/${process.env.REGION_ID}`,
{
method: 'POST',
headers: {
Authorization: `APIKey ${TOKEN}`,
'Content-Type': 'application/json',
},
body: JSON.stringify({ name: 'my-network' }),
}
);
const { tasks } = await netRes.json();
console.log('Task ID:', tasks[0]);
axios
Install axios, then create a pre-configured client instance with the authorization header set once:
const axios = require('axios');
const client = axios.create({
baseURL: 'https://api.gcore.com',
headers: { Authorization: `APIKey ${process.env.GCORE_API_KEY}` },
});
// GET
const { data: account } = await client.get('/iam/clients/me');
console.log(account.id, account.email);
// POST
const { data } = await client.post(
`/cloud/v1/networks/${process.env.PROJECT_ID}/${process.env.REGION_ID}`,
{ name: 'my-network' }
);
console.log('Task ID:', data.tasks[0]);
Handle async operations in JavaScript
Cloud API write operations return a task ID. Poll it until state is FINISHED:
async function waitForTask(taskId, intervalMs = 5000) {
const headers = { Authorization: `APIKey ${process.env.GCORE_API_KEY}` };
while (true) {
const res = await fetch(`https://api.gcore.com/cloud/v1/tasks/${taskId}`, { headers });
const task = await res.json();
if (task.state === 'FINISHED') return task.created_resources;
if (task.state === 'ERROR') throw new Error(`Task failed: ${task.error}`);
await new Promise(r => setTimeout(r, intervalMs));
}
}
// Usage
const { tasks } = await netRes.json();
const resources = await waitForTask(tasks[0]);
console.log('Network ID:', resources.networks[0]);
Choosing a client
All options call the same API — the choice depends on the context:
| Situation | Recommendation |
|---|
| Scripting, automation, CI/CD | Python SDK or Go SDK |
| One-off inspection, debugging | curl or HTTPie |
| Shell scripts | curl |
| Production Node.js services | JavaScript fetch or axios |
| Production Python services | Python SDK (sync or async) |
| Production Go services | Go SDK |
| Terraform-managed infrastructure | Terraform provider |
SDK coverage
The Python and Go SDKs cover the full API surface: Cloud (instances, volumes, networking, Kubernetes, load balancers, and more), IAM, CDN, DNS, Object Storage, FastEdge, Streaming, and WAAP.
All 298 Cloud API endpoints have auto-generated SDK methods. The API reference code samples show the exact method name for each endpoint.
