---
title: "Services (all products) — API reference"
description: "Generic bridge to every product line (cloud server, VDS, dedicated, mail, monitor, storage, license, ...). Everything a customer can do on a service i"
url: https://www.gyrohosting.com/developers/en/api/services-all-products.html
language: en
openapi: https://www.gyrohosting.com/developers/openapi.json
api_version: 2.30.0
---

# Services (all products)

Generic bridge to every product line (cloud server, VDS, dedicated, mail, monitor, storage, license, ...).
Everything a customer can do on a service in the client area is a module tool or method and is reachable here.
Start with `GET /cloud/services/{id}/tools`: it lists the tools, their actions and our safety policy
(`read`, `confirm`, `secret`) for that very service.


Base URL: `https://www.gyrohosting.com/api/v1/client` · OpenAPI: https://www.gyrohosting.com/developers/openapi.json


## GET /cloud/services

**List services of every product line** · operationId `listServices` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/listServices.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `product_line` | query | string (cloud_server, vds, dedicated_server, mail, monitor, storage, license, app) |  |
| `status` | query | string |  |
| `customer_id` | query | integer | Reseller main key only |
| `page` | query | integer |  |
| `limit` | query | integer |  |
| `project` | query | integer | Only services in this project (0 = default project). Unknown project: 404 `project_not_found`. |

### Responses

- **200**: Services
- **401**: Missing, invalid or revoked key

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/services' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro service list
```
```hcl
# data source gyro_services: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/data-sources/services
data "gyro_services" "mail" {
  product_line = "mail"
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/services", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/services/{id}

**Get a service (renewal, cancellation, access details)** · operationId `getService` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getService.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Responses

- **200**: Service
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro service get 12345
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/services/12345", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/services/{id}/tools

**Discover tools, actions and safety policy of a service** · operationId `listServiceTools` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/listServiceTools.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |

### Responses

- **200**: Tools
- **404**: Not found — also returned for objects owned by someone else
- **409**: State conflict (`server_locked`, `not_actionable`, `ssh_key_exists`, `server_limit`, `idempotency_in_flight`)

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro service tool list 12345
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/services/{id}/tools/{tool}

**Read a tool (list mailboxes, snapshots, DNS records, ...)** · operationId `getServiceToolData` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getServiceToolData.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |
| `tool` (required) | path | string |  |

### Responses

- **200**: Tool data (module specific)
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools/1' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro service tool get 12345
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools/1", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools/1", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## POST /cloud/services/{id}/tools/{tool}/{action}

**Run a tool action (create a mailbox, restore a snapshot, ...)** · operationId `runServiceToolAction` · scope `services_write` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/runServiceToolAction.json

Body fields are the tool's own fields (see the tool data and the per-module table in the guide). Actions flagged `confirm` in the discovery answer need `"confirm": true`.


### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |
| `tool` (required) | path | string |  |
| `action` (required) | path | string |  |

### Request body

| Field | Type | Description |
|---|---|---|
| `confirm` | boolean |  |

### Responses

- **202**: Accepted
- **404**: Not found — also returned for objects owned by someone else
- **409**: State conflict (`server_locked`, `not_actionable`, `ssh_key_exists`, `server_limit`, `idempotency_in_flight`)
- **422**: Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools/1/reboot' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"email": "info@example.com", "password": "S3cure-pass!", "quota": 2048}'
```
```bash
gyro service tool run 12345 --help    # all flags
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.post("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools/1/reboot", headers=h, json={"email": "info@example.com", "password": "S3cure-pass!", "quota": 2048}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/tools/1/reboot", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"email": "info@example.com", "password": "S3cure-pass!", "quota": 2048}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## POST /cloud/services/{id}/methods/{method}

**Call a client-callable module method (e.g. license change_ip)** · operationId `callServiceMethod` · scope `services_write` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/callServiceMethod.json




### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer |  |
| `method` (required) | path | string |  |

### Request body

| Field | Type | Description |
|---|---|---|

### Responses

- **200**: Result
- **404**: Not found — also returned for objects owned by someone else
- **422**: Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345/methods/1' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"ip": "203.0.113.10"}'
```
```bash
gyro service method call 12345 --help    # all flags
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.post("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/methods/1", headers=h, json={"ip": "203.0.113.10"}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/methods/1", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"ip": "203.0.113.10"}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/services/{id}/label

**Get the nickname and tags of a service** · operationId `getServiceLabel` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getServiceLabel.json

Customer-defined nickname and colour tags of one of your services (any product line). A service without a label answers `"nickname": null` and `"tags": []`. Labels are private to the service owner; after a transfer the old owner's label is not shown.


### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer | Service id |

### Responses

- **200**: Label
- **401**: Missing, invalid or revoked key
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **404**: Not found — also returned for objects owned by someone else
- **429**: Too many requests (`rate_limited`); see the `Retry-After` and `X-RateLimit-*` headers

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345/label' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro service label get 12345
```
```hcl
# resource gyro_service_label: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/service_label
# Give any service a nickname and colour tags. The nickname becomes the service title in the
# client area; the product name and service number stay below it.
resource "gyro_server" "api" {
  plan          = "standart-2-4"
  region        = "tr-ist-1"
  image         = "ubuntu-24.04"
  confirm_order = true
}

resource "gyro_service_label" "api" {
  service_id = tonumber(gyro_server.api.id)
  nickname   = "api-gateway"
  tags = [
    { name = "production", color = "green" },
    { name = "api" }, # colour omitted: a stable default is chosen by the API
  ]
}

# An existing service (e.g. a container environment) by its number.
resource "gyro_service_label" "ecs" {
  service_id = 12345
  nickname   = "gyro-ecs-1"
  tags       = [{ name = "staging", color = "orange" }]
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/label", headers=h, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/label", {
  method: "GET",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
  },
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## PUT /cloud/services/{id}/label

**Set the nickname and/or tags of a service** · operationId `updateServiceLabel` · scope `services_write` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/updateServiceLabel.json

Send `nickname`, `tags` or both; a field that is not sent stays unchanged. `nickname` "" or null clears it; `tags` replaces all tags and `[]` clears them. A tag is `"name"` or `{"name", "color"}`; an unknown or missing colour gets a stable default. Duplicate names (case-insensitive) are merged. Limit: 30 label writes per minute per key (429 `rate_limited`). Sub-account keys need the `label:edit` action. Errors: 422 `nothing_to_update`, `invalid_nickname`, `invalid_tags`; 404 `service_not_found` (also for services of other accounts) or `feature_unavailable`.


### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer | Service id |

### Request body

| Field | Type | Description |
|---|---|---|
| `nickname` | string / null | "" or null clears the nickname. No control characters. |
| `tags` | array / null | Replaces all tags; [] or null clears them. Item: a tag name, or {"name", "color"} (CLI: use --data for colours). |

### Responses

- **200**: Saved label
- **401**: Missing, invalid or revoked key
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **404**: Not found — also returned for objects owned by someone else
- **422**: Validation or business rule failure (`confirm_required`, `invalid_image`, `tool_action_failed` ...)
- **429**: Too many requests (`rate_limited`); see the `Retry-After` and `X-RateLimit-*` headers

### Examples

```bash
curl -s -X PUT 'https://www.gyrohosting.com/api/v1/client/cloud/services/12345/label' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"nickname": "Accounting server", "tags": [{"name": "production", "color": "green"}, "customer-A"]}'
```
```bash
gyro service label set 12345 --help    # all flags
```
```hcl
# resource gyro_service_label: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/service_label
# Give any service a nickname and colour tags. The nickname becomes the service title in the
# client area; the product name and service number stay below it.
resource "gyro_server" "api" {
  plan          = "standart-2-4"
  region        = "tr-ist-1"
  image         = "ubuntu-24.04"
  confirm_order = true
}

resource "gyro_service_label" "api" {
  service_id = tonumber(gyro_server.api.id)
  nickname   = "api-gateway"
  tags = [
    { name = "production", color = "green" },
    { name = "api" }, # colour omitted: a stable default is chosen by the API
  ]
}

# An existing service (e.g. a container environment) by its number.
resource "gyro_service_label" "ecs" {
  service_id = 12345
  nickname   = "gyro-ecs-1"
  tags       = [{ name = "staging", color = "orange" }]
}
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.put("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/label", headers=h, json={"nickname": "Accounting server", "tags": [{"name": "production", "color": "green"}, "customer-A"]}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/services/12345/label", {
  method: "PUT",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"nickname": "Accounting server", "tags": [{"name": "production", "color": "green"}, "customer-A"]}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```