Skip to content
You're viewing documentation for v2026.11.14-beta. It may be out of date.Go to latest
TimescaleDB Enterprise
Esc
↑↓navigate↵open⌘Jpreview

Create a database service

POST/api/v1/database-services
Authorization
tse_sessionAPI key · cookierequired
Request body
requiredapplication/json
backup_server_idstring
data_dirstring
database_namestring
dcs_cluster_idstring
extension_versionsobject

The package version of each extension of extensions with versions, by name: a version of check.extensions of GET /packs/available. An omitted extension gets the newest version in the server packages. TimescaleDB takes timescaledb_version

extensionsstring[]
license_filestring
local_repo_pathstring
namestring
pack_releasestring

The release of the server packages to pin, for example v0.11.0-eap.1: a loaded release with the server packages of every PostgreSQL server. Empty pins the newest such release. A restore or a fork takes the pin of the source

pg_versionstring
pg_version_minorstring
pgbackrest_stanzastring
postgres_passwordstring
remote_repo_pathstring
restore_fromRestoreFromRequest
Show properties
modestring
new_backup_serverstring
new_stanza_namestring
source_stanza_idstring
serversDatabaseServiceNodeRequest[]
Show properties
Array of DatabaseServiceNodeRequest
rolestring
server_idstring
sizestring
timescaledb_versionstring
topologystring
vipstring
Responses
201

Created

apply_pendingApplyPending

A running service has a change that waits for a deploy or a restart. Absent when nothing waits.

Show properties
caps_stalebooleanrequired

On a server, the limits on PostgreSQL are not the license settings. A restart applies them.

guard_missingbooleanrequired

The license guard is not loaded on the cluster, and the cluster has a license grant. A deploy, or a restart after a deploy, loads it.

licensing_setupbooleanrequired

The license guard is not loaded on the cluster, and the cluster has no license grant. The steps of the licensing setup show, and their deploy restarts a Standard service after it.

restart_markerbooleanrequired

The last deploy of the Standard service changed settings that apply only when TimescaleDB starts. A restart applies them.

backupConfigOutOfSyncbooleanrequired
backupNeedsAttentionbooleanrequired
backupUnprotectedbooleanrequired
created_atstringrequired
data_dirstringrequired
database_namestringrequired
extension_versionsobjectrequired

The stored version of each extension whose packages the deploy installs, by extension name. TimescaleDB is timescaledb_version too.

extensionsstring[]required
healthServiceHealthResponse

The stored health verdict of a running service. Absent before the first poll and when the service is not running.

Show properties
checked_atstring<date-time>

The time of the last real reading. Absent when there is none. When it is 15 minutes old or older, status is error with a reason that names the checks that did not run.

componentsComponentHealthResponse[]required
Show properties
Array of ComponentHealthResponse
keystringrequired

The stable key of the component: the path segment of its endpoint. Name is text for people and can change.

Allowed:patronietcdpgbouncerhaproxypgbackrestpostgresqlreservevip
messagestring
namestringrequired
statusstringrequired
Allowed:healthywarningerrorunknownnot_applicable
reasonstringrequired
sincestring<date-time>

The time the status last changed. Absent on a live reading.

statusstringrequired
Allowed:healthywarningerrorunknown
idstringrequired
license_enforcedboolean
license_grant_missingboolean

The cluster of the service holds no license grant. Writes stop 72 hours after the first check without one.

livesync_targetboolean
namestringrequired
pack_releasestringrequired

The release of the server packages that the PostgreSQL servers of the service install from, for example v0.11.0-eap.1. Empty when the service has no pin yet: its next deploy pins the newest loaded release that has its versions

pg_versionstring
pg_version_minorstring
postgresql_existsbooleanrequired
redeploy_recommendedbooleanrequired
statusstringrequired
timescaledb_versionstring

Empty when unknown (a service from before TSE-734)

topologystringrequired
Allowed:single_nodestandard_haadvanced_ha
updates_availablebooleanrequired

The Updates tab of the service lists items: the service runs, and its pinned server packages or a newer loaded release have newer versions, or the loaded server components are newer. Nothing changes until an operator runs Check and an admin runs Upgrade

default

Error

codestring

Stable code of the refusal, when the route has codes

detailsstring[]

Additional detail, e.g. per-field validation failures

errorstringrequired

Human-readable error message

Request
curl -X POST 'https://console.example.com/api/v1/database-services' \
  -H 'Cookie: tse_session=YOUR_API_KEY' \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json' \
  -d '{
  "backup_server_id": "string",
  "data_dir": "string",
  "database_name": "string",
  "dcs_cluster_id": "string",
  "extension_versions": {
    "property1": "string",
    "property2": "string"
  },
  "extensions": [
    "string"
  ],
  "license_file": "string",
  "local_repo_path": "string",
  "name": "string",
  "pack_release": "string",
  "pg_version": "string",
  "pg_version_minor": "string",
  "pgbackrest_stanza": "string",
  "postgres_password": "string",
  "remote_repo_path": "string",
  "restore_from": {
    "mode": "string",
    "new_backup_server": "string",
    "new_stanza_name": "string",
    "source_stanza_id": "string"
  },
  "servers": [
    {
      "role": "string",
      "server_id": "string"
    }
  ],
  "size": "string",
  "timescaledb_version": "string",
  "topology": "string",
  "vip": "string"
}'
Response
{
  "apply_pending": {
    "caps_stale": true,
    "guard_missing": true,
    "licensing_setup": true,
    "restart_marker": true
  },
  "backupConfigOutOfSync": true,
  "backupNeedsAttention": true,
  "backupUnprotected": true,
  "created_at": "string",
  "data_dir": "string",
  "database_name": "string",
  "extension_versions": {
    "property1": "string",
    "property2": "string"
  },
  "extensions": [
    "string"
  ],
  "health": {
    "checked_at": "2019-08-24T14:15:22Z",
    "components": [
      {
        "key": "patroni",
        "message": "string",
        "name": "string",
        "status": "healthy"
      }
    ],
    "reason": "string",
    "since": "2019-08-24T14:15:22Z",
    "status": "healthy"
  },
  "id": "string",
  "license_enforced": true,
  "license_grant_missing": true,
  "livesync_target": true,
  "name": "string",
  "pack_release": "string",
  "pg_version": "string",
  "pg_version_minor": "string",
  "postgresql_exists": true,
  "redeploy_recommended": true,
  "status": "string",
  "timescaledb_version": "string",
  "topology": "single_node",
  "updates_available": true
}