> ## 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.

# 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.

<Info>
  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.
</Info>

## 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:

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

  <Tab title="Python SDK">
    ```python theme={null}
    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)
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    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)
    }
    ```
  </Tab>

  <Tab title="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));
    ```
  </Tab>
</Tabs>

The terminal outputs:

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

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

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

  <Tab title="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)
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    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)
    }
    ```
  </Tab>

  <Tab title="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));
    ```
  </Tab>
</Tabs>

The terminal outputs 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"]
}
```

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:

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

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

  <Tab title="Python SDK">
    ```python theme={null}
    instances = client.cloud.instances.list(
        project_id=int(os.environ["PROJECT_ID"]),
        region_id=int(os.environ["REGION_ID"]),
    )
    print(f"{instances.count} instances")
    ```
  </Tab>

  <Tab title="Go SDK">
    ```go theme={null}
    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)
    ```
  </Tab>

  <Tab title="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`);
    ```
  </Tab>
</Tabs>

The terminal outputs:

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

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

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