---
title: "Backup space — API reference"
description: "SFTP backup space with a hard quota, bound to ONE server of your account and reachable only from that server's IPv4 addresses (tr-ist-1). Order, conne"
url: https://www.gyrohosting.com/developers/en/api/backup-space.html
language: en
openapi: https://www.gyrohosting.com/developers/openapi.json
api_version: 2.44.0
---

# Backup space

SFTP backup space with a hard quota, bound to ONE server of your account and reachable only from that server's IPv4 addresses (tr-ist-1). Order, connection details, password reset, bind to another server, cancel. Size changes use the generic plan change endpoints.

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


## GET /cloud/backup-spaces/plans

**List backup space plans** · operationId `listBackupSpacePlans` · scope `cloud_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/listBackupSpacePlans.json

Orderable sizes (50 GB to 1 TB) with prices per billing cycle (fixed EUR, VAT excluded; `list_amount` = strike-through list price) and `servers`: the servers of the account a space can be bound to. Empty `plans` = not orderable for this account yet. `available: false` = no capacity right now.


### Responses

- **200**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/plans' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro backup-space plans
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/plans", 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/backup-spaces/plans", {
  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/backup-spaces

**List backup spaces** · operationId `listBackupSpaces` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/listBackupSpaces.json

Backup spaces of the account (same filters and paging as GET /cloud/services; `product_line=backup_space`).


### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `status` | query | string | service status filter (active, suspended, cancelled …) |
| `page` | query | integer |  |
| `limit` | query | integer |  |

### Responses

- **200**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro backup-space list
```
```hcl
# resource gyro_backup_space: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/backup_space
# 100 GB SFTP backup space bound to a server of the account, billed monthly from the balance.
# Only the server's IPv4 addresses can connect (sftp -P 2201 <user>@<host>, write into /veri).
resource "gyro_backup_space" "yedek" {
  plan      = "100gb"
  cycle     = "monthly"
  server_id = 12345
  name      = "gyro-proje-yedek"

  # destroy deletes the space and every file in it (cannot be undone)
  lifecycle {
    prevent_destroy = true
  }
}

output "sftp" {
  value = "sftp -P ${gyro_backup_space.yedek.port} ${gyro_backup_space.yedek.user}@${gyro_backup_space.yedek.host}"
}

# password is sensitive: pass it to a secret store / configuration, never print it
# gyro_backup_space.yedek.password
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces", 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/backup-spaces", {
  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/backup-spaces

**Order a backup space** · operationId `createBackupSpace` · scope `cloud_order` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/createBackupSpace.json

Orders ONE backup space and pays from the account balance (never a stored card). The space is bound to `server_id`, one of your active servers (Gyro Cloud tr-ist-1, TR VDS, managed or dedicated); it may be omitted when the account has exactly one. Only that server's IPv4 addresses can connect (SFTP, port 2201). Billed per `cycle` (fixed EUR prices charged in the account currency, VAT excluded) and renewed from the balance like other services. Send `"dry_run": true` for a quote; a real order needs `"confirm": true` and an `Idempotency-Key` header. The space is set up within about a minute (`backup_space.state` `pending` -> `active`); then read the password with `GET /cloud/backup-spaces/{id}/credentials`. Errors: 402 `insufficient_balance`; 403 `not_available` (not on sale for this account), `orders_disabled`; 409 `server_required` (no active server), `capacity_unavailable`; 422 `confirm_required` (with `quote`), `product_not_orderable`, `cycle_invalid`, `server_id_required`, `invalid_server`, `invalid_quantity`; 429 `daily_limit`.


### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `Idempotency-Key` (required) | header | string | Unique per logical request (e.g. a UUID). Replays within 24 hours return the stored answer. |

### Request body

| Field | Type | Description |
|---|---|---|
| `plan` | string | plan from GET /cloud/backup-spaces/plans (50gb, 100gb, 250gb, 500gb, 1tb) |
| `product_id` | integer | product id instead of plan |
| `cycle` | string (monthly, quarterly, semiannually, annually) | billing cycle |
| `server_id` | integer | server to bind the space to (optional when the account has one active server) |
| `name` | string | name (nickname) |
| `tags` | array<string> |  |
| `project_id` | integer / null | project (0 = default project) |
| `end_customer_id` | integer | reseller main key: assign to this end-customer |
| `confirm` | boolean |  |
| `dry_run` | boolean |  |

### Responses

- **201**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **404**: Not found — also returned for objects owned by someone else
- **200**: Dry-run quote (`dry_run`, `quote`)
- **402**: Account balance does not cover the order (`insufficient_balance`)
- **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` ...)
- **429**: Too many requests (`rate_limited`); see the `Retry-After` and `X-RateLimit-*` headers

### Examples

```bash
curl -s -X POST 'https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"plan": "100gb", "cycle": "monthly", "server_id": 12345, "name": "gyro-proje-yedek", "confirm": true}'
```
```bash
gyro backup-space create --help    # all flags
```
```hcl
# resource gyro_backup_space: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/backup_space
# 100 GB SFTP backup space bound to a server of the account, billed monthly from the balance.
# Only the server's IPv4 addresses can connect (sftp -P 2201 <user>@<host>, write into /veri).
resource "gyro_backup_space" "yedek" {
  plan      = "100gb"
  cycle     = "monthly"
  server_id = 12345
  name      = "gyro-proje-yedek"

  # destroy deletes the space and every file in it (cannot be undone)
  lifecycle {
    prevent_destroy = true
  }
}

output "sftp" {
  value = "sftp -P ${gyro_backup_space.yedek.port} ${gyro_backup_space.yedek.user}@${gyro_backup_space.yedek.host}"
}

# password is sensitive: pass it to a secret store / configuration, never print it
# gyro_backup_space.yedek.password
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
h["Idempotency-Key"] = str(uuid.uuid4())
r = requests.post("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces", headers=h, json={"plan": "100gb", "cycle": "monthly", "server_id": 12345, "name": "gyro-proje-yedek", "confirm": True}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
    "Idempotency-Key": crypto.randomUUID(),
  },
  body: JSON.stringify({"plan": "100gb", "cycle": "monthly", "server_id": 12345, "name": "gyro-proje-yedek", "confirm": true}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## GET /cloud/backup-spaces/{id}

**Get a backup space** · operationId `getBackupSpace` · scope `services_read` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getBackupSpace.json

Service row plus `backup_space`: SFTP host, port, user, writable path, size, usage, bound server, allowed IPs and state. The password is not included (see /credentials).


### Parameters

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

### Responses

- **200**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **404**: Not found — also returned for objects owned by someone else

### Examples

```bash
curl -s 'https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/12345' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro backup-space get 12345
```
```hcl
# resource gyro_backup_space: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/backup_space
# 100 GB SFTP backup space bound to a server of the account, billed monthly from the balance.
# Only the server's IPv4 addresses can connect (sftp -P 2201 <user>@<host>, write into /veri).
resource "gyro_backup_space" "yedek" {
  plan      = "100gb"
  cycle     = "monthly"
  server_id = 12345
  name      = "gyro-proje-yedek"

  # destroy deletes the space and every file in it (cannot be undone)
  lifecycle {
    prevent_destroy = true
  }
}

output "sftp" {
  value = "sftp -P ${gyro_backup_space.yedek.port} ${gyro_backup_space.yedek.user}@${gyro_backup_space.yedek.host}"
}

# password is sensitive: pass it to a secret store / configuration, never print it
# gyro_backup_space.yedek.password
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/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/backup-spaces/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}`);
```


## DELETE /cloud/backup-spaces/{id}

**Cancel (delete) a backup space** · operationId `deleteBackupSpace` · scope `cloud_delete` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/deleteBackupSpace.json

`confirm=true` is required. `immediate=true` cancels now: SFTP access stops and the space with EVERY file in it is deleted permanently within about a minute (no snapshot, no grace period; cannot be undone). Without `immediate` a cancellation request is filed and the space keeps working until it is processed. 403 `immediate_disabled` when the operator turned immediate deletion off.


### Parameters

| Field | in | Type | Description |
|---|---|---|---|
| `id` (required) | path | integer | Backup space (service) id |
| `confirm` (required) | query | boolean |  |
| `immediate` | query | boolean | delete the space and every file now (cannot be undone) |

### Responses

- **202**: OK
- **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` ...)

### Examples

```bash
curl -s -X DELETE 'https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/12345' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro backup-space delete 12345
```
```hcl
# resource gyro_backup_space: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/backup_space
# 100 GB SFTP backup space bound to a server of the account, billed monthly from the balance.
# Only the server's IPv4 addresses can connect (sftp -P 2201 <user>@<host>, write into /veri).
resource "gyro_backup_space" "yedek" {
  plan      = "100gb"
  cycle     = "monthly"
  server_id = 12345
  name      = "gyro-proje-yedek"

  # destroy deletes the space and every file in it (cannot be undone)
  lifecycle {
    prevent_destroy = true
  }
}

output "sftp" {
  value = "sftp -P ${gyro_backup_space.yedek.port} ${gyro_backup_space.yedek.user}@${gyro_backup_space.yedek.host}"
}

# password is sensitive: pass it to a secret store / configuration, never print it
# gyro_backup_space.yedek.password
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.delete("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/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/backup-spaces/12345", {
  method: "DELETE",
  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/backup-spaces/{id}/credentials

**SFTP connection with the password** · operationId `getBackupSpaceCredentials` · scope `services_write` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/getBackupSpaceCredentials.json

Host, port, user, path and the SFTP password (`Cache-Control: no-store`). Needs `services_write` because it reveals a secret. 409 `not_ready` while the space is being set up.


### Parameters

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

### Responses

- **200**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **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/backup-spaces/12345/credentials' \
  -H "Authorization: Bearer $GYRO_TOKEN"
```
```bash
gyro backup-space credentials 12345
```
```python
import os, uuid, requests

h = {"Authorization": "Bearer " + os.environ["GYRO_TOKEN"]}
r = requests.get("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/12345/credentials", 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/backup-spaces/12345/credentials", {
  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/backup-spaces/{id}/password

**Reset the SFTP password** · operationId `resetBackupSpacePassword` · scope `services_write` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/resetBackupSpacePassword.json

Creates a new random password and returns it once. The old password stops working at once and open SFTP sessions are closed; update your backup jobs. `"confirm": true` required. 409 `not_actionable` when the space is not active; 502 `backend_unavailable` = try again in a few minutes.


### Parameters

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

### Request body

| Field | Type | Description |
|---|---|---|
| `confirm` (required) | boolean (True) |  |

### Responses

- **200**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **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/backup-spaces/12345/password' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"confirm": true}'
```
```bash
gyro backup-space reset-password 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/backup-spaces/12345/password", headers=h, json={"confirm": True}, timeout=60)
r.raise_for_status()
print(r.json()["data"])
```
```js
const res = await fetch("https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/12345/password", {
  method: "POST",
  headers: {
    "Authorization": `Bearer ${process.env.GYRO_TOKEN}`,
    "Content-Type": "application/json",
  },
  body: JSON.stringify({"confirm": true}),
});
const { data, error } = await res.json();
if (!res.ok) throw new Error(`${error.code}: ${error.message}`);
```


## PUT /cloud/backup-spaces/{id}/server

**Bind the space to another server** · operationId `attachBackupSpaceServer` · scope `services_write` · OpenAPI fragment: https://www.gyrohosting.com/developers/spec/ops/attachBackupSpaceServer.json

Binds the space to `server_id` (one of your active servers; optional when the account has one). From then on only that server's IPv4 addresses can connect; the previous server loses access at once. Files are not touched. When the bound server's IP changes or the server is cancelled, access follows automatically.


### Parameters

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

### Request body

| Field | Type | Description |
|---|---|---|
| `server_id` | integer | server id |

### Responses

- **200**: OK
- **403**: Key lacks the scope, IP not allowed, or feature disabled
- **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 PUT 'https://www.gyrohosting.com/api/v1/client/cloud/backup-spaces/12345/server' \
  -H "Authorization: Bearer $GYRO_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"server_id": 1}'
```
```bash
gyro backup-space attach-server 12345 --help    # all flags
```
```hcl
# resource gyro_backup_space: https://registry.terraform.io/providers/gyro-hosting/gyro/latest/docs/resources/backup_space
# 100 GB SFTP backup space bound to a server of the account, billed monthly from the balance.
# Only the server's IPv4 addresses can connect (sftp -P 2201 <user>@<host>, write into /veri).
resource "gyro_backup_space" "yedek" {
  plan      = "100gb"
  cycle     = "monthly"
  server_id = 12345
  name      = "gyro-proje-yedek"

  # destroy deletes the space and every file in it (cannot be undone)
  lifecycle {
    prevent_destroy = true
  }
}

output "sftp" {
  value = "sftp -P ${gyro_backup_space.yedek.port} ${gyro_backup_space.yedek.user}@${gyro_backup_space.yedek.host}"
}

# password is sensitive: pass it to a secret store / configuration, never print it
# gyro_backup_space.yedek.password
```
```python
import os, uuid, requests

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