> ## Documentation Index
> Fetch the complete documentation index at: https://docs.gcore.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Make the first Gcore API call

> Set up a token, project ID, and region to make the first Gcore Cloud resource call.

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

> [!NOTE]
>
> A terminal must be open and `curl` must be installed. If either is unfamiliar, read [API basics](/developer-tools/rest-api/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](/developer-tools/rest-api/authentication) to create one in the [Gcore Customer Portal](https://portal.gcore.com) and copy the value.

Then set it as an environment variable in the terminal:

```bash theme={null}
export GCORE_API_KEY="29841_c767..."
```

Replace `29841_c767...` with the actual token value copied in Step 1.

Verify the variable was set correctly:

```bash theme={null}
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:

```json theme={null}
{
  "id": 7350925,
  "email": "user@example.com",
  "status": "active"
}
```

If the terminal shows an error message instead, check [Authentication errors](/developer-tools/rest-api/authentication#common-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**

```bash theme={null}
curl "https://api.gcore.com/cloud/v1/projects" \
  -H "Authorization: APIKey $GCORE_API_KEY"
```

The API returns:

```json theme={null}
{
  "count": 1,
  "results": [
    {
      "id": 1234567,
      "name": "Default",
      "is_default": true,
      "state": "ACTIVE"
    }
  ]
}
```

**Python SDK**

```python theme={null}
from gcore import Gcore
client = Gcore()
projects = client.cloud.projects.list()
for p in projects.results:
    print(p.id, p.name, p.is_default)
```

**Go SDK**

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

**JavaScript**

```javascript theme={null}
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));
```

Find the `"id"` value in the `results` array — that number is the project ID. Copy it and set the appropriate variable for the method being used:

```bash theme={null}
export PROJECT_ID=1234567              # curl and JavaScript
export GCORE_CLOUD_PROJECT_ID=1234567  # Python SDK and Go SDK
```

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. Select 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**

```bash theme={null}
curl "https://api.gcore.com/cloud/v1/regions?limit=50" \
  -H "Authorization: APIKey $GCORE_API_KEY"
```

The API returns a list of regions. Each entry looks like:

```json theme={null}
{
  "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"]
}
```

**Python SDK**

```python theme={null}
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)
```

**Go SDK**

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

**JavaScript**

```javascript theme={null}
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 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"`. Set the appropriate variable for the method being used:

```bash theme={null}
export REGION_ID=148              # curl and JavaScript
export GCORE_CLOUD_REGION_ID=148  # Python SDK and Go SDK
```

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**

```bash theme={null}
curl "https://api.gcore.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY"
```

The API returns:

```json theme={null}
{
  "count": 0,
  "results": []
}
```

**Python SDK**

```python theme={null}
# Uses GCORE_CLOUD_PROJECT_ID and GCORE_CLOUD_REGION_ID set in Step 2 and 3
instances = client.cloud.instances.list()
print(f"{instances.count} instances")
```

**Go SDK**

```go theme={null}
// Uses GCORE_CLOUD_PROJECT_ID and GCORE_CLOUD_REGION_ID set in Step 2 and 3
ctx := context.Background()
instances, err := client.Cloud.Instances.List(ctx, cloud.InstanceListParams{})
if err != nil { panic(err) }
fmt.Printf("%d instances\n", instances.Count)
```

**JavaScript**

```javascript theme={null}
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`);
```

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.

## Environment variables reference

The three values set in Steps 1–3 are required for every Cloud API call. The variable names differ depending on the method used.

**curl and JavaScript** — project and region IDs are embedded in the URL path:

```bash theme={null}
export GCORE_API_KEY="..."    # Authentication
export PROJECT_ID=1234567     # Goes into the URL path
export REGION_ID=148          # Goes into the URL path
```

The curl URL pattern:

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

Example:

```bash theme={null}
curl "https://api.gcore.com/cloud/v1/instances/$PROJECT_ID/$REGION_ID" \
  -H "Authorization: APIKey $GCORE_API_KEY"
# Sends: GET https://api.gcore.com/cloud/v1/instances/1234567/148
```

**Python SDK** — all three values are read automatically from environment variables:

```bash theme={null}
export GCORE_API_KEY="..."           # Read by Gcore() automatically
export GCORE_CLOUD_PROJECT_ID=1234567  # Read by Gcore() automatically
export GCORE_CLOUD_REGION_ID=148       # Read by Gcore() automatically
```

No project ID or region ID is passed to individual SDK calls — the client uses the values from the environment.

**Go SDK** — all three values are read automatically by `gcore.NewClient()`, the same way the Python SDK reads them:

```bash theme={null}
export GCORE_API_KEY="..."             # Read by gcore.NewClient() automatically
export GCORE_CLOUD_PROJECT_ID=1234567  # Read by gcore.NewClient() automatically
export GCORE_CLOUD_REGION_ID=148       # Read by gcore.NewClient() automatically
```

No project ID or region ID is passed to individual SDK calls — the client uses the values from the environment.

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