API basics

Gcore API calls are HTTP requests sent from a terminal or a script. Three things are needed before making the first call: a terminal application, the curl command-line tool, and an understanding of JSON — the format the API uses for both requests and responses. Environment variables and HTTP status codes are also covered below.

Choosing a tool

Different tools suit different workflows. All of them call the same Gcore API endpoints — the choice is about comfort and use case:

Tool	Interface	Best for
curl	Terminal	Universal, pre-installed, used in all examples in these guides
HTTPie	Terminal	Cleaner syntax than curl, color-formatted output
Postman	GUI app	Visual exploration, no terminal needed, import the full API spec
VS Code REST Client	IDE	.http files alongside code in VS Code
Python / Go SDK	Code	Production automation, any complexity
JavaScript fetch	Code	Node.js services, browser integrations

For those new to APIs: Postman removes the need to learn terminal syntax — the GUI has fields for everything. For those already comfortable in a terminal: curl is pre-installed on most systems and needs no setup.

Full setup instructions for each tool are in Tools.

These guides use curl in all code examples because it runs on every operating system without additional installation.

Tools needed

A terminal and curl are required to follow the curl examples. Python is needed only for SDK examples.

Terminal

A terminal is a text-based interface where commands are typed and executed. It’s where all curl commands in these guides are run.

Operating system	How to open
macOS	Press ⌘ Space, type Terminal, press Enter. Or open Applications → Utilities → Terminal.
Windows	Press Win, type Windows Terminal or PowerShell, press Enter. On older systems: Command Prompt.
Linux	Usually Ctrl+Alt+T, or search for “Terminal” in the applications menu.

Once a terminal is open, commands are typed at the prompt (usually a $ or > symbol) and run by pressing Enter.

curl

curl is a command-line tool for making HTTP requests. It comes pre-installed on macOS and most Linux distributions. On Windows, it has been pre-installed since Windows 10 version 1803.

To check if curl is available, open a terminal and run:

curl --version

If the output starts with curl 7.x.x or curl 8.x.x, it is installed. If the command is not found:

• On Windows: download the installer from curl.se/windows, or install via winget: winget install curl
• On macOS: install Homebrew, then run brew install curl
• On Linux (Debian/Ubuntu): run sudo apt-get install curl

Python (optional)

Python is needed only for the Python SDK examples. All guides show curl and Python SDK tabs — curl works without any additional installation.

To check if Python is installed:

python3 --version

The output should be Python 3.8 or higher. To install Python, download it from python.org or use a package manager.

Install the Gcore SDK with:

pip install gcore

---

curl command structure

Every curl command in these guides follows the same pattern:

curl -X POST "https://api.gcore.com/cloud/v1/volumes/{YOUR_PROJECT_ID}/{YOUR_REGION_ID}" \
  -H "Authorization: APIKey $GCORE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"name": "my-volume", "source": "new-volume", "type_name": "standard", "size": 20}'

Breaking this down:

Part	What it does
curl	The tool being run
-X POST	The HTTP method: GET (read), POST (create), DELETE (remove), PATCH (update)
"https://api.gcore.com/..."	The API endpoint URL
\	Line continuation — the command continues on the next line
-H "Authorization: APIKey ..."	A header: extra information sent with the request. The Authorization header carries the API token.
-H "Content-Type: application/json"	Tells the server the request body is JSON
-d '...'	The request body — data sent to the server (only for POST/PATCH requests)

For a GET request (reading data), -X GET, -H "Content-Type: ...", and -d are not needed:

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

-X GET is the default, so it can be omitted.

---

JSON responses

The Gcore API responds in JSON — a text format that represents structured data. Every response is either a single object ({...}) or a list of objects ([...]).

Example response from listing projects:

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

Reading this:

• "count": 1 — there is 1 project total
• "results": [...] — an array containing the projects
• "id": 1234567 — the project’s numeric ID
• "name": "Default" — the project’s display name

When a guide says “save the id from the response”, it means: find the id field in the terminal output and use that number in the next command.

---

Environment variables

An environment variable stores a value in the terminal session. Instead of pasting the API token into every command, it is set once and reused:

# Set the variable (run this once per terminal session)
export GCORE_API_KEY="29841_c767b250..."

# Use it in any command (the shell substitutes $GCORE_API_KEY with the token value)
curl "https://api.gcore.com/iam/clients/me" -H "Authorization: APIKey $GCORE_API_KEY"

Environment variables are session-scoped — closing the terminal window loses all variables set with export, so the next session requires setting them again. To persist across sessions on macOS/Linux, add the export line to ~/.zshrc (or ~/.bashrc) and restart the terminal. On Windows PowerShell, add it to the profile file.

---

HTTP status codes

The first thing the API sends back is a status code — a three-digit number indicating whether the request succeeded:

Code	Meaning
200 / 201	Success — the request worked
400	Bad request — the request body has errors
401	Unauthorized — the token is missing, wrong, or expired
403	Forbidden — the token does not have permission for this operation
404	Not found — the resource does not exist or is in a different region
429	Too many requests — slow down and retry
500	Server error — a temporary Gcore-side problem, retry after a few seconds