Version: Develop

API V1 Endpoints

This section describes the usage and specifics of the available endpoints of the a9s Public API V1.

info

Before you can access any of the mentioned endpoints, you have to follow the steps mentioned in Accessing the a9s Public API.

List All Backups

This request lists all of the Service Service Instance's available backups.

Route

GET /v1/instances/:instance_id/backups

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl --insecure --header "Authorization: ${bearer_token}" "${url}/backups"

Response

Body

For success responses, an array is returned. The objects are composed of the following fields:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance.
`backup_id`	`string`	The ID of the backup within the Backup Manager and the storage itself. This can be used to Fork a Service Instance with a specific backup.
`size`	`integer`	The size of the backup, in bytes.
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`.
`triggered_at`	`datetime`	The date the task was triggered, in ISO 8601 UTC time.
`finished_at`	`datetime`	The date on which the status of the task was last changed, in ISO 8601 UTC time.
`downloadable`	`boolean`	Indicates if the backup can be downloaded via the a9s Service Dashboard.

Example

[
  {
    "id": 2,
    "backup_id": "8377f207-21b4-48fd-a75b-78c1bcdef8ca-1742693407644",
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-21T01:30:03.832Z",
    "finished_at": "2021-04-21T01:30:32.163Z",
    "downloadable": true
  },
  {
    "id": 1,
    "backup_id": "8377f207-21b4-48fd-a75b-78c1bcdef8ca-1742607006559",
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-20T01:30:02.898Z",
    "finished_at": "2021-04-20T01:30:31.883Z",
    "downloadable": false
  }
]

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Get a Specific Backup

This request returns the information of the specified Service Instance's backup.

Route

GET /v1/instances/:instance_id/backups/:id

:instance_id MUST be the ID of a previously provisioned Service Instance. :id MUST be the ID of the requested backup, within the Service Instance.

cURL

curl --insecure --header "Authorization: ${bearer_token}" "${url}/backups/:id"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance
`size`	`integer`	The size of the backup, in bytes.
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`
`triggered_at`	`datetime`	The date the task was triggered, in ISO 8601 UTC time
`finished_at`	`datetime`	The date on which the status of the task was last changed, in ISO 8601 UTC time
`downloadable`	`boolean`	Indicates if the backup can be downloaded via the a9s Service Dashboard

Example

  {
    "id": 1,
    "size": 2792,
    "status": "done",
    "triggered_at": "2021-04-20T01:30:02.898Z",
    "finished_at": "2021-04-20T01:30:31.883Z",
    "downloadable": false
  }

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Create a Backup

This request triggers the creation of a new Service Instance's backup.

note

In order to be able to decrypt a downloaded backup, the encryption key must be known/set before triggering said backup. You can see how to do this here.

Route

POST /v1/instances/:instance_id/backups

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl -X POST --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/backups"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance
`message`	`string`	The status of the task

Example

{
  "id": 1,
  "message": "job to backup is queued"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Download a Backup

This request downloads the given backup of a given Service Instance.

Route

GET /v1/instances/:instance_id/backups/:id/download

:instance_id MUST be the ID of a previously provisioned Service Instance.
:id MUST be the ID of a previously performed backup.

cURL

curl --insecure --header "Authorization: ${bearer_token}" \
  "${url}/backups/:backup_id/download" > <backup_file_name>.tgz

Response

Status

Status Code	Description
`200` OK	If the backup download is started
`412` Precondition Failed	Either `instance_id` or `id` does not exist or match

Body

For success responses, the body contains the encrypted and compressed backup. The response should be piped into a file. In order to decrypt this file you must know/set the encryption key before triggering the backup. You can see how to do this here

How to decrypt and decompress the backup is described in this guide.

For error responses, the following fields are defined:

Response Field	Type	Description
`message`	`string`	A user-facing message that can be used to tell the user what went wrong
`status`	`int`	The status code of the error

note

There is a request timeout in the Cloud Foundry Gorouter component to handle external requests. By default, the timeout is configured for 15 minutes, therefore when a request reaches this timeout the request is aborted. To know more or request a change of the timeout, contact your Platform Operator.

List All Restores

This request lists all of the Service Instance's triggered restores.

Route

GET /v1/instances/:instance_id/restores

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl --insecure --header "Authorization: ${bearer_token}" \
  "${url}/restores"

Response

Body

For success responses, an array is returned. The objects are composed of the following fields:

Response Field	Type	Description
`id`	`integer`	The internal ID of the restore within the Service Instance
`backup_id`	`integer`	The internal ID of the backup within the Service Instance
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`
`triggered_at`	`datetime`	The date the task was triggered, in ISO 8601 UTC time
`finished_at`	`datetime`	The date on which the status of the task was last changed, in ISO 8601 UTC time

Example

[
  {
    "id": 2,
    "backup_id": 1,
    "status": "done",
    "triggered_at": "2021-04-21T15:34:12.295Z",
    "finished_at": "2021-04-21T15:34:14.322Z"
  },
  {
    "id": 1,
    "backup_id": 1,
    "status": "done",
    "triggered_at": "2021-04-21T15:31:19.910Z",
    "finished_at": "2021-04-21T15:31:31.337Z"
  }
]

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Get a Specific Restore

This request returns the information of the specified Service Instance's restore.

Route

GET /v1/instances/:instance_id/restores/:id

:instance_id MUST be the ID of a previously provisioned Service Instance. :id MUST be the ID of the requested restore, within the Service Instance.

cURL

curl --insecure --header "Authorization: ${bearer_token}" \
  "${url}/restores/:id"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`id`	`integer`	The internal ID of the backup within the Service Instance
`size`	`integer`	The size of the backup, in bytes.
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`
`triggered_at`	`datetime`	The date the task was triggered, in ISO 8601 UTC time
`finished_at`	`datetime`	The date on which the status of the task was last changed, in ISO 8601 UTC time

Example

{
  "id": 2,
  "backup_id": 1,
  "status": "done",
  "triggered_at": "2021-04-21T15:34:12.295Z",
  "finished_at": "2021-04-21T15:34:44.308Z"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Trigger a Restore

This request triggers the restoration process using the specified Service Instance's backup.

Route

POST /v1/instances/:instance_id/backups/:id/restore

:instance_id MUST be the ID of a previously provisioned Service Instance. :id MUST be the ID of an existing backup belonging to the Service Instance.

cURL

curl -X POST --insecure --header "Authorization: ${bearer_token}"  \
  --header "Content-Type: application/json" "${url}/backups/:id/restore"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`id`	`integer`	The internal ID of the restore within the Service Instance

Example

{
  "id": 1
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Rebinding Application after Restoring a Backup

While restoring a backup is usually a straightforward task, it should be noted that after restoring a backup to an a9s Data Service instance, you are required to both rebind your application to your a9s Data Service instance, and to immediately restage it.

Taking Cloud Foundry as an example, this means that after restoring the backup, you should execute the following commands:

$ cf unbind-service <my_app> <my_service_instance>  
$ cf bind-service <my_app> my_service_instance 
$ cf restage <my_app>

Get Backups Configuration

This request gets the information regarding the Service Instance's backups configuration.

Route

GET /v1/instances/:instance_id/backups-config

:instance_id MUST be the ID of a previously provisioned Service Instance.

cURL

curl --insecure --header "Authorization: ${bearer_token}" \
  "${url}/backups-config"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`min_backup_count`	`integer`	The minimum amount of backups per instance. When the amount of backups exceeds this number, the older backups will be deleted. The minimum value is 0
`retention_time`	`integer`	The retention time is measured in days and defines a time range after which backups are deleted. The minimum value is 0
`min_encryption_key_length`	`integer`	The minimum length of the backups' encryption key
`exclude_from_auto_backup`	`boolean`	States whether this instance will be excluded from scheduled backups. Default is false
`backup_type`	`string`	The backup type of a Service Instance. The following backup types exist: `standard`, `continuous_archiving`

Example

{
  "min_backup_count": 5,
  "retention_time": 5,
  "min_encryption_key_length": 8,
  "exclude_from_auto_backup": false,
  "backup_type": "standard"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Update Backups Configuration

This request sets the information regarding the Service Instance's backups' configuration. This is currently limited to setting the backups' encryption key.

note

In order to be able to decrypt a downloaded backup, the encryption key MUST be known/set before triggering said backup.

Route

PATCH /v1/instances/:instance_id/backups-config

:instance_id MUST be the ID of a previously provisioned Service Instance.

Body

The body must be sent in valid JSON format.

Request Field	Type	Required	Description
`encryption_key`	`string`	false	The new backup encryption key. User provided value
`min_backup_count`	`integer`	false	The minimum amount of backups per instance. When the amount of backups exceeds this number, the older backups will be deleted. The minimum value is 0
`retention_time`	`integer`	false	The retention time is measured in days and defines a time range after which backups are deleted. The minimum value is 0
`exclude_from_auto_backup`	`boolean`	false	States whether this instance will be excluded from scheduled backups. Default is false

cURL

curl -X PATCH --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/backups-config" \
  --data '{"encryption_key":"<encryption_key>", "min_backup_count":<min_backup_count>, \
  "retention_time":<retention_time>, "exclude_from_auto_backup":<boolean-value> }'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`message`	`string`	A user-facing success message

Example

{
  "message": "instance updated"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Prepare a Disaster Recovery

This request prepares the required information for an Service Instance's disaster recovery.

Route

POST /v1/instances/:instance_id/disaster-recovery/prepare

Body

The body must be sent in valid JSON format.

Request Field	Type	Required	Description
`encryption_key`	`string`	false	Optional The key which the Backup Manager is using to encrypt backups

cURL

curl -X POST --header "Content-Type: application/json" --header "Authorization: ${bearer_token}" \
  "${url}/disaster-recovery/prepare" --data '{"encryption_key":"<encryption_key>"}'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`backup_guid`	`string`	The GUID which the a9s Backup Manager is using to refer to backups of a given instance

Example

{
  "backup_guid": "3a2e59ee-40cb-472a-91d0-502ab259918c"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Perform a Disaster Recovery

This request performs an Service Instance's disaster recovery in the destination Service Instance.

Route

POST /v1/instances/:instance_id/disaster-recovery/perform

Body

The body must be sent in valid JSON format.

Request Field	Type	Required	Description
`backup_guid`	`string`	true	The GUID which the a9s Backup Manager uses to refer to the originating Service Service Instance's backups
`encryption_key`	`string`	true	The key which the Backup Manager is using to encrypt backups

cURL

curl -X POST --header "Content-Type: application/json" --header "Authorization: ${bearer_token}" \
  "${url}/disaster-recovery/perform" --data '{"encryption_key":"<encryption_key>", "backup_guid":"<backup_guid>"}'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`restore_id`	`integer`	The internal ID of the restore in the destination Service Instance.

Example

{
  "restore_id": 1
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Get Instance Overview

This request gets the Service Instance's overview information.

Route

GET /v1/instances/:instance_id

cURL

curl --insecure --header "Authorization: ${bearer_token}" "${url}"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`available_updates`	`array` of available updates objects	Schema of available updates objects defined below
`created_at`	`datetime`	The date a Service Instance was created, in ISO 8601 UTC time
`id`	`int`	The id of a Service Instance within the Data Service
`name`	`string`	The given name of a Service Instance
`plan_id`	`string`	The id of the plan a Service Instance was created under
`service_id`	`string`	The id of the Data Service from which a Service Instance was created
`state`	`string`	Current state of a Service Instance. The following states exist: `provisioned`, `available`, `deleted`, `deploying`, `failed`
`subtenant_id`	`string`	The id of the subtenant (e.g. space in CF)
`subtenant_name`	`string`	The name of the subtenant (e.g. space in CF)
`tenant_id`	`string`	The id of the tenant (e.g. organization in CF)
`tenant_name`	`string`	The name of the subtenant (e.g. space in CF)
`updated_at`	`datetime`	The date when a Service Instance was last updated, in ISO 8601 UTC time
`urls`	`array` of URLs objects	Schema of URLs objects defined below

Available Updates Object

Response Field	Type	Description
`name`	`string`	The name of the component with available updates
`type`	`string`	The type of update of the component
`version`	`string`	The version of the available update

URLs Object

Response Field	Type	Description
`display_name`	`string`	The display name of the URL
`id`	`string`	The ID of the URL
`link`	`string`	The full URL string

Example

{
  "available_updates": [
    {
      "name": "keyvalue8",
      "type": "release",
      "version": "1.0.0"
    }
  ],
  "created_at": "2024-12-19T18:32:55.970Z",
  "id": 1,
  "name": "my-service",
  "plan_id": "77f163d4-0879-482d-bc93-085143bce70e",
  "service_id": "855887d9-9096-4ddf-a40f-89e6f72da2d1",
  "state": "provisioned",
  "subtenant_id": "fffd9f2a-45c6-4368-8d7a-afab38c0e594",
  "subtenant_name": "manual",
  "tenant_id": "68470a75-fd07-4897-b868-16e81fab46a5",
  "tenant_name": "system",
  "updated_at": "2021-04-22T01:30:06.165Z",
  "urls": [
    {
      "display_name": "KeyValue",
      "id": "KeyValue-link",
      "link": "https://a9s-keyvalue-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d/keyvalue"
    },
    {
      "display_name": "Service Instance Dashboard",
      "id": "Dashboard",
      "link": " https://a9s-keyvalue-dashboard.example.com/service-instances/db8d8ad3-3d72-4f5a-b84a-47aa9df70a7d"
    }
  ]
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Trigger a Recreate

This request triggers the recreate process of a Service Instance.

Route

PATCH /v1/instances/:instance_id/recreate

cURL

curl -X PATCH --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/recreate"

Response

Body

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Trigger a Restart

Triggers the restart process of a Service Instance.

Route

PATCH /v1/instances/:instance_id/restart

cURL

curl -X PATCH --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/restart"

Response

Body

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Trigger an Update

This request triggers the update process of for all available updates of the current a Service Instance.

Route

PATCH /v1/instances/:instance_id/updates

Body

The body must be sent in valid JSON format.

Response Field	Type	Description
`service_id`	`string`	The id of the Service from which a Service Instance was spawned from.

cURL

curl -X PATCH --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/updates" \
  --data '{"service_id":"<service_id>"}'

Response

Body

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Get Metrics

This request displays the metrics of the Service Instance.

Route

GET /v1/instances/:instance_id/metrics?quantity=x

:instance_id MUST be the ID of a previously provisioned Service Instance.
quantity Number of latest elements to be returned. If not set, all elements WILL be returned. If set, quantity MUST be greater than or equal to 1.

cURL

curl --insecure --header "Authorization: ${bearer_token}" \
  "${url}/metrics?quantity=1"

Response

The response is a JSON that contains a collection of metrics DataPoints in Graphite format. For more details, see Graphite Metrics.

Body

For success responses, the body contains the collection of metrics DataPoints which can be piped to a file.

Example

[
  "keyvalue.0.system.cpu.error 0 1594380720",
  "keyvalue.0.system.cpu0.user 894310 1594380720",
  "keyvalue.0.system.cpu0.system 410430 1594380720",
  "keyvalue.0.system.cpu0.idle 72292610 1594380720",
  "keyvalue.0.system.load.load1 3542480 1594380720",
  "keyvalue.0.system.load.load5 3152832 15943807720",
  "keyvalue.0.system.load.load15 2358398 15943807720",
  "keyvalue.0.system.memory.error 0 1594380720",
  "keyvalue.0.system.memory.total 4136923136 1594380720",
  "keyvalue.0.system.memory.used 3278594048 1594380720",
  "keyvalue.0.system.memory.free 151093248 1594380720",
  "keyvalue.0.system.memory.shared 21757952 1594380720",
  "keyvalue.0.system.memory.buffers 137117696 1594380720",
  "keyvalue.0.system.memory.cached 570118144 1594380720",
  "keyvalue.0.system.swap.error 0 1594380720",
  "keyvalue.0.system.swap.total 4136628224 1594380720",
  "keyvalue.0.system.swap.used 0 1594380720",
  "keyvalue.0.system.swap.free 4136628224 1594380720",
  "keyvalue.0.system.disk.error 0 1594380720",
  "keyvalue.0.system.disk.system.error 0 1594380720",
  "keyvalue.0.system.disk.system.total 3103686656 1594380720",
  "keyvalue.0.system.disk.system.used 1558130688 1594380720",
  "keyvalue.0.system.disk.system.free 1369866240 1594380720",
  "keyvalue.0.system.disk.ephemeral.error 0 1594380720",
  "keyvalue.0.system.disk.ephemeral.total 6113067008 1594380720",
  "keyvalue.0.system.disk.ephemeral.used 1042546688 1594380720",
  "keyvalue.0.system.disk.ephemeral.free 4736393216 1594380720",
  "keyvalue.0.system.disk.var_log.error 0 1594380720",
  "keyvalue.0.system.disk.var_log.total 6113067008 1594380720",
  "keyvalue.0.system.disk.var_log.used 1042546688 1594380720",
  "keyvalue.0.system.disk.var_log.free 4736393216 1594380720",
  "keyvalue.0.system.disk.tmp.error 0 1594380720",
  "keyvalue.0.system.disk.tmp.total 6113067008 1594380720",
  "keyvalue.0.system.disk.tmp.used 1042546688 1594380720",
  "keyvalue.0.system.disk.tmp.free 4736393216 1594380720",
  "keyvalue.0.system.disk.var_tmp.error 0 1594380720",
  "keyvalue.0.system.disk.var_tmp.total 6113067008 1594380720",
  "keyvalue.0.system.disk.var_tmp.used 1042546688 1594380720",
  "keyvalue.0.system.disk.var_tmp.free 4736393216 1594380720",
  "keyvalue.0.system.disk.home.error 0 1594380720",
  "keyvalue.0.system.disk.home.total 3103686656 1594380720",
  "keyvalue.0.system.disk.home.used 1558130688 1594380720",
  "keyvalue.0.system.disk.home.free 1369866240 1594380720",
  "keyvalue.0.system.disk.persistent.error 0 1594380720",
  "keyvalue.0.system.disk.persistent.total 5148114944 1594380720",
  "keyvalue.0.system.disk.persistent.used 10547200 1594380720",
  "keyvalue.0.system.disk.persistent.free 4852461568 1594380720"
  "keyvalue.0.parachute.error 0 1594380720",
  "keyvalue.0.parachute.activated 1 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.error 0 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.total 6113067008 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.used 1068199936 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.used_percent 18 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.used_threshold 10 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.free 4710739968 1594380720",
  "keyvalue.0.parachute.disk.ephemeral.activated 1 1594380720",
  "keyvalue.0.parachute.disk.persistent.error 0 1594380720",
  "keyvalue.0.parachute.disk.persistent.total 5148114944 1594380720",
  "keyvalue.0.parachute.disk.persistent.used 10657792 1594380720",
  "keyvalue.0.parachute.disk.persistent.used_percent 0 1594380720",
  "keyvalue.0.parachute.disk.persistent.used_threshold 80 1594380720",
  "keyvalue.0.parachute.disk.persistent.free 4852350976 1594380720",
  "keyvalue.0.parachute.disk.persistent.activated 0 1594380720",
]

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`200` OK	If the request has been processed successfully.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Point-In-Time Recovery - Get Available Time Range

This request fetches the available time range from where a backup can be selected for the restore process of the instance.

caution

This endpoint is only available for a9s PostgreSQL instances with the continuous archiving setting enabled.

Route

GET /v1/instances/:instance_id/pitr

cURL

curl --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/pitr"

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`start_time`	`datetime`	The start (oldest) date of the continuous archiving, from which a backup can be fetched, in ISO 8601 UTC time.
`end_time`	`datetime`	The end (newest) date of the continuous archiving, from which a backup can be fetched, in ISO 8601 UTC time.

Example

{
  "start_time":"2022-02-01T20:53:20.000Z",
  "end_time":"2022-02-02T11:45:37.601Z"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

Point-In-Time Recovery - Restore to a Target Time

This request triggers the restore process of a Service Instance, which uses the backup closest to the target date.

caution

This endpoint is only available for a9s PostgreSQL instances with the continuous archiving setting enabled.

Route

POST /v1/instances/:instance_id/pitr/restore

Body

The body must be sent in valid JSON format.

Response Field	Type	Description
`target_time`	`datetime`	The date (within range) from which the backup should be fetched, in ISO 8601 UTC time.

cURL

curl -X POST --insecure --header "Authorization: ${bearer_token}" \
  --header "Content-Type: application/json" "${url}/pitr/restore" \
  --data '{"target_time":"<point_in_time>"}'

Response

Body

For success responses, the following fields are defined:

Response Field	Type	Description
`status`	`string`	The status of the task. The following statuses exist: `queued`, `running`, `done`, `failed`, `deleted`.

Example

{
  "status":"queued"
}

For error responses, the following fields are defined:

Response Field	Type	Description
`error`	`string`	A single word in camel case that uniquely identifies the error condition.
`description`	`string`	A user-facing error message explaining why the request failed.

Status

Status Code	Description
`202` Accepted	The request has been accepted for processing, but the processing has not been completed. The request might or might not eventually be acted upon, as it might be disallowed when processing actually takes place. There is no facility for re-sending a status code from an asynchronous operation such as this.
`401` Unauthorized	The user does not have valid authentication credentials for the target resource.
`403` Forbidden	The user does not have the required right to do this request.
`404` Not Found	Entity not found.
`500` Internal Server Error	An unexpected error occurred while handling the request.
`502` Bad Gateway	An error occurred during upstream communication.
`504` Gateway Timeout	A timeout occurred during upstream communication.

List All Backups​

Route​

cURL​

Response​

Body​

Status​

Get a Specific Backup​

Route​

cURL​

Response​

Body​

Status​

Create a Backup​

Route​

cURL​

Response​

Body​

Status​

Download a Backup​

Route​

cURL​

Response​

Status​

Body​

List All Restores​

Route​

cURL​

Response​

Body​

Get a Specific Restore​

Route​

cURL​

Response​

Body​

Status​

Trigger a Restore​

Route​

cURL​

Response​

Body​

Status​

Get Backups Configuration​

Route​

cURL​

Response​

Body​

Status​

Update Backups Configuration​

Route​

Body​

cURL​

Response​

Body​

Status​

Prepare a Disaster Recovery​

Route​

Body​

cURL​

Response​

Body​

Status​

Perform a Disaster Recovery​

Route​

Body​

cURL​

Response​

Body​

Status​

Get Instance Overview​

Route​

cURL​

Response​

Body​

Available Updates Object​

URLs Object​

Status​

Trigger a Recreate​

Route​

cURL​

Response​

List All Backups

Route

cURL

Response

Body

Status

Get a Specific Backup

Route

cURL

Response

Body

Status

Create a Backup

Route

cURL

Response

Body

Status

Download a Backup

Route

cURL

Response

Status

Body

List All Restores

Route

cURL

Response

Body

Get a Specific Restore

Route

cURL

Response

Body

Status

Trigger a Restore

Route

cURL

Response

Body

Status

Get Backups Configuration

Route

cURL

Response

Body

Status

Update Backups Configuration

Route

Body

cURL

Response

Body

Status

Prepare a Disaster Recovery

Route

Body

cURL

Response

Body

Status

Perform a Disaster Recovery

Route

Body

cURL

Response

Body

Status

Get Instance Overview

Route

cURL

Response

Body

Available Updates Object

URLs Object

Status

Trigger a Recreate

Route

cURL

Response