Make the first Gcore API call

Three values are needed before any Cloud API call works: an API token, a project ID, and a region ID.

A terminal must be open and curl must be installed. If either is unfamiliar, read API basics first — it covers both in a few minutes.

Step 1. Set up the API token

If the token has not been created yet, follow Authentication to create one in the Gcore Customer Portal and copy the value. Then set it as an environment variable in the terminal:

export GCORE_API_KEY="29841_c767..."

Replace 29841_c767... with the actual token value copied in Step 1. Verify the variable was set correctly:

curl "https://api.gcore.com/iam/clients/me" \
  -H "Authorization: APIKey $GCORE_API_KEY"

The terminal will display a response. A working token returns something like:

{
  "id": 7350925,
  "email": "user@example.com",
  "status": "active"
}

If the terminal shows an error message instead, check Authentication errors.

Step 2. Find the project ID

Cloud API URLs include a project ID — a number that identifies the account’s project. List the projects to find it:

curl
Python SDK
Go SDK
JavaScript

curl "https://api.gcore.com/cloud/v1/projects" \
  -H "Authorization: APIKey $GCORE_API_KEY"

import os
from gcore import Gcore
client = Gcore(api_key=os.environ["GCORE_API_KEY"])
projects = client.cloud.projects.list()
for p in projects.results:
    print(p.id, p.name, p.is_default)

projects, err := client.Cloud.Projects.List(context.TODO(), cloud.ProjectListParams{})
if err != nil { panic(err) }
for _, p := range projects.Results {
    fmt.Println(p.ID, p.Name, p.IsDefault)
}

const res = await fetch("https://api.gcore.com/cloud/v1/projects", {
  headers: { Authorization: `APIKey ${process.env.GCORE_API_KEY}` },
});
const { results } = await res.json();
results.forEach(p => console.log(p.id, p.name));

The terminal outputs:

{
  "count": 1,
  "results": [
    {
      "id": 1234567,
      "name": "Default",
      "is_default": true,
      "state": "ACTIVE"
    }
  ]
}

Find the "id" value in the results array — that number is the project ID. Copy it and set it as a variable:

export PROJECT_ID=1234567

Replace 1234567 with the actual ID from the response. Most accounts have one project named “Default”, while multiple projects are used to separate environments (production, staging) or billing.

Step 3. Choose a region

Cloud resources — VMs, volumes, networks — exist in a specific region (a data center location), and different regions support different features. List all available regions:

curl
Python SDK
Go SDK
JavaScript

curl "https://api.gcore.com/cloud/v1/regions?limit=50" \
  -H "Authorization: APIKey $GCORE_API_KEY"

regions = client.cloud.regions.list(limit=50)
for r in regions.results:
    if r.state == "ACTIVE":
        print(r.id, r.display_name, r.access_level)

regions, err := client.Cloud.Regions.List(context.TODO(), cloud.RegionListParams{
    Limit: gcore.Int(50),
})
if err != nil { panic(err) }
for _, r := range regions.Results {
    fmt.Println(r.ID, r.DisplayName, r.State)
}

const res = await fetch("https://api.gcore.com/cloud/v1/regions?limit=50", {
  headers: { Authorization: `APIKey ${process.env.GCORE_API_KEY}` },
});
const { results } = await res.json();
results.filter(r => r.state === "ACTIVE")
       .forEach(r => console.log(r.id, r.display_name));

The terminal outputs a list of regions. Each entry looks like:

{
  "id": 148,
  "display_name": "Luxembourg-3",
  "state": "ACTIVE",
  "access_level": "core",
  "zone": "EMEA",
  "has_kvm": true,
  "has_baremetal": true,
  "has_k8s": false,
  "available_volume_types": ["ssd_hiiops", "standard", "ssd_lowlatency"]
}

The fields that matter for choosing:

Field	Meaning
`display_name`	Human-readable location name
`state`	Only use regions where `state` is `"ACTIVE"`
`access_level`	`"core"` = latest hardware; `"edge"` = lower cost
`has_kvm`	`true` means VMs are available
`has_k8s`	`true` means Managed Kubernetes is available
`has_dbaas`	`true` means Managed PostgreSQL is available

Find a region close to the target users, confirm it has "has_kvm": true for VM workloads, and note its "id". Then set it:

export REGION_ID=148

Replace 148 with the chosen region’s id.

Step 4. Make a resource call

With all three variables set, run a real Cloud API call — list all VMs in the project and region:

curl
Python SDK
Go SDK
JavaScript

curl "https://api.gcore.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY"

instances = client.cloud.instances.list(
    project_id=int(os.environ["PROJECT_ID"]),
    region_id=int(os.environ["REGION_ID"]),
)
print(f"{instances.count} instances")

var projectID int64 = 1234567
var regionID  int64 = 148
instances, err := client.Cloud.Instances.List(context.TODO(), cloud.InstanceListParams{
    ProjectID: gcore.Int(projectID),
    RegionID:  gcore.Int(regionID),
})
if err != nil { panic(err) }
fmt.Printf("%d instances\n", instances.Count)

const res = await fetch(
  `https://api.gcore.com/cloud/v1/instances/${process.env.PROJECT_ID}/${process.env.REGION_ID}`,
  { headers: { Authorization: `APIKey ${process.env.GCORE_API_KEY}` } }
);
const data = await res.json();
console.log(`${data.count} instances`);

The terminal outputs:

{
  "count": 0,
  "results": []
}

An empty list is expected on a new project — no VMs have been created yet. A 200 OK response with valid JSON confirms the token, project ID, and region ID are all correct.

API URL structure

These three environment variables appear in every Cloud API call throughout these guides:

export GCORE_API_KEY="..."    # Who is making the request (authentication)
export PROJECT_ID=1234567     # Which project the resource belongs to
export REGION_ID=148          # Which data center location to use

The API URL always follows this pattern:

https://api.gcore.com/cloud/v1/{resource_type}/{PROJECT_ID}/{REGION_ID}

With the three variables exported, the shell substitutes them automatically in every call:

$ curl "https://api.gcore.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID" \
    -H "Authorization: APIKey $GCORE_API_KEY"

# Shell sends:
# GET https://api.gcore.com/cloud/v1/instances/1234567/148
# Authorization: APIKey 29841$c767...

Resource creation is asynchronous — the response returns a task ID, not the finished resource.

​Step 1. Set up the API token

​Step 2. Find the project ID

​Step 3. Choose a region

​Step 4. Make a resource call

​API URL structure

Step 1. Set up the API token

Step 2. Find the project ID

Step 3. Choose a region

Step 4. Make a resource call

API URL structure