Rest APIs for the agent

• 1: VerticaAPIKey
• 2: Backup and restore
• 2.1: GET backups
• 2.2: POST backups/:config_script_base
• 2.3: GET backups/:config_script_base/:archive_id
• 2.4: POST restore/:archive_id
• 3: Databases
• 3.1: GET databases
• 3.2: POST databases
• 3.3: GET databases/:database_name
• 3.4: PUT databases/:database_name
• 3.5: DELETE databases/:database_name
• 3.6: GET databases/:database_name/configuration
• 3.7: PUT databases/:database_name/configuration
• 3.8: GET databases/:database_name/hosts
• 3.9: POST databases/:database_name/hosts
• 3.10: DELETE databases/:database_name/hosts/:host_id
• 3.11: POST databases/:database_name/hosts/:host_id/process
• 3.12: GET databases/:database_name/license
• 3.13: GET databases/:database_name/licenses
• 3.14: DELETE databases/:database_name/hosts/:host_id/process
• 3.15: POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new
• 3.16: GET databases/:database_name/nodes
• 3.17: GET databases/:database_name/nodes/:node_id
• 3.18: POST databases/:database_name/process
• 3.19: GET databases/:database_name/process
• 3.20: DELETE databases/:database_name/process
• 3.21: POST databases/:database_name/rebalance/process
• 3.22: POST databases/:database_name/Workload analyzer/process
• 4: Hosts
• 4.1: GET hosts
• 4.2: GET hosts/:hostid
• 5: Jobs
• 5.1: GET jobs
• 5.2: GET jobs/:id
• 6: Licenses
• 6.1: POST licenses
• 6.2: GET licenses
• 7: Nodes
• 7.1: GET nodes
• 7.2: GET nodes/:nodeid
• 8: Webhooks
• 8.1: GET webhooks
• 8.2: POST webhooks/subscribe
• 8.3: DELETE webhooks/:subscriber_id

1 - VerticaAPIKey

The Management API requires an authentication key, named VerticaAPIKEY, to access some API resources. You can manage API keys by using the apikeymgr command-line tool.

usage: apikeymgr [-h] [--user REQUESTOR] [--app APPLICATION] [--delete]
                 [--create] [--update] [--migrate]
                 [--secure {restricted,normal,admin}] [--list]

API key management tool

optional arguments:
  -h, --help            show this help message and exit
  --user REQUESTOR      The name of the person requesting the key
  --app APPLICATION     The name of the application that will use the key
  --delete              Delete the key for the given R & A
  --create              Create a key for the given R & A
  --update              Update a key for the given R & A
  --migrate             migrate the keyset to the latest format
  --secure {restricted,normal,admin}
                        Set the keys security level
  --list                List all the keys known

Example request

To create a new VerticaAPIKEY for the dbadmin user with admin access, enter the following:

$ apikeymgr --user dbadmin --app vertica --create --secure admin

Response:

Requestor  : dbadmin
Application: vertica
API Key    : ValidAPIKey
Synchronizing cluster...

2 - Backup and restore

You can use these API calls to perform backup and restore tasks for your database.

2.1 - GET backups

Returns a list of all backups created for vbr configuration (*.ini) files that reside in /opt/vertica/config and provides details about each backup.

Resource URL

https://<NODE>:5444/backups

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "data": [
        {
            "backups": [
                {
                    "archive_id": "v_vdb_bk_snapshot_20190305_174428",
                    "version": "v9.2.1-20190305",
                    "href": "/backups/fullbk/v_vdb_bk_snapshot_20190305_174428",
                    "exclude_patterns": "",
                    "backup_type": "full",
                    "include_patterns": "",
                    "epoch": "16",
                    "objects": "",
                    "hosts": "v_vdb_bk_node0001(10.20.91.240), v_vdb_bk_node0002(10.20.91.241), v_vdb_bk_node0003(10.20.91.242), v_vdb_bk_node0004(10.20.91.243), v_vdb_bk_node0005(10.20.91.244)"
                },
                {
                    "archive_id": "v_vdb_bk_snapshot_20190305_174025",
                    "version": "v9.2.1-20190305",
                    "href": "/backups/fullbk/v_vdb_bk_snapshot_20190305_174025",
                    "exclude_patterns": "",
                    "backup_type": "full",
                    "include_patterns": "",
                    "epoch": "16",
                    "objects": "",
                    "hosts": "v_vdb_bk_node0001(10.20.91.240), v_vdb_bk_node0002(10.20.91.241), v_vdb_bk_node0003(10.20.91.242), v_vdb_bk_node0004(10.20.91.243), v_vdb_bk_node0005(10.20.91.244)"
                }
            ],
            "config_file": "/opt/vertica/config/fullbk.ini",
            "config_script_base": "fullbk",
            "num_backups": 2
        }
    ],
    "href": "/backups",
    "mime-type": "application/vertica.databases.json-v2"
}

2.2 - POST backups/:config_script_base

Creates a new backup job for the backup defined in the vbr configuration script :config_script_base. The vbr configuration script must reside in /opt/vertica/configuration. The :config_script_base value does not include the .ini filename extention.

To determine valid :config_script_base values, see GET backups.

Returns a job ID that you can use to determine the status of the job.

Resource URL

https://<NODE>:5444/backups/:config_script_base

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "id": "CreateBackup-VMart-1404750602.03",
    "url": "/jobs/CreateBackup-VMart-1404750602.03"
}

2.3 - GET backups/:config_script_base/:archive_id

Returns details on a specific backup. You must provide the :config_script_base. This value is the name of a vbr config file (without the .ini filename extension) that resides in /opt/vertica/config. The :archive_id is the value of the backup field that the GET backups command returns.

Resource URL

https://<NODE>:5444/backups/:config_script_base/:archive_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "archive_id": "v_vdb_bk_snapshot_20190304_204814",
    "config_file": "/opt/vertica/config/fullbk.ini",
    "objects": "",
    "href": "/backups/fullbk/v_vdb_bk_snapshot_20190304_204814",
    "exclude_patterns": "",
    "epoch": "16",
    "include_patterns": "",
    "backup_type": "full",
    "version": "v9.2.1-20190304",
    "hosts": "v_vdb_bk_node0001(10.20.91.240),
             v_vdb_bk_node0002(10.20.91.241),
             v_vdb_bk_node0003(10.20.91.242),
             v_vdb_bk_node0004(10.20.91.243),
             v_vdb_bk_node0005(10.20.91.244)"
}

2.4 - POST restore/:archive_id

Creates a new restore job to restore the database from the backup archive identified by :archive_id. The :archive_id is the value of a backup field that the GET backups command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/restore/:archive_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "id": "RestoreBackup-VMart-1404760113.71",
    "url": "/jobs/RestoreBackup-VMart-1404760113.71"
}

3 - Databases

You can use these API calls to interact with your database.

3.1 - GET databases

Returns a list of databases, their current status, and database properties.

Resource URL

https://<NODE>:5444/databases

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

An example of the full request using cURL:

curl -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/databases

Response:

{
    "body": [
        {
            "href": "/databases/VMart",
            "mime-type": [
                "application/vertica.database.json-v2"
            ],
            "name": "VMart",
            "port": "5433",
            "status": "UP"
        },
        {
            "href": "/databases/testDB",
            "mime-type": [
                "application/vertica.database.json-v2"
            ],
            "name": "testDB",
            "port": "5433",
            "status": "DOWN"
        }
    ],
    "href": "/databases",
    "links": [
        "/:database_name"
    ],
    "mime-type": "application/vertica.databases.json-v2"
}

3.2 - POST databases

Creates a job to create a new database with the provided parameters.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

Example request

https://:5444/databases?passwd=db_password&name=db_name&
catalog=%2Fpath%2Fto%2Fcatalog&data=%2Fpath%2Fto%2Fdata_directory

Response:

{
    "jobid": "CreateDatabase-testDB-2014-07-07 15:49:53.219445",
    "resource": "/jobs/CreateDatabase-testDB-2014-07-07 15:49:53.219445",
    "userid": "dbadmin"
}

3.3 - GET databases/:database_name

Returns details about a specific database. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": {
        "database_id": "VMart",
        "id": "VMart",
        "nodes": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003",
        "nodes_new": [
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.247",
                "id": "v_vmart_node0001"
            },
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.248",
                "id": "v_vmart_node0002"
            },
            {
                "catalog_base": "/home/dbadmin",
                "data_base": "/home/dbadmin",
                "host": "10.20.100.249",
                "id": "v_vmart_node0003"
            }
        ],
        "path": "/home/dbadmin/VMart",
        "port": "5433",
        "restartpolicy": "ksafe",
        "status": "UP"
    },
    "href": "/databases/VMart",
    "links": [
        "/configuration",
        "/hosts",
        "/license",
        "/nodes",
        "/process",
        "/rebalance/process",
        "/status",
        "/Workload Analyzer/process"
    ],
    "mime-type": "application/vertica.database.json-v2"
}

3.4 - PUT databases/:database_name

Creates a job to run the action specified by the action parameter against the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have normal level security or higher.

Parameters

Example request

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 13:28:49.321744",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 13:28:49.321744"
}

3.5 - DELETE databases/:database_name

Creates a job to delete (drop) an existing database on the cluster. To perform this operation, you must first stop the database. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

None.

Example request

Response:

{
    "id": "DropDatabase-TestDB-2014-07-18 12:50:33.332383",
    "url": "/jobs/DropDatabase-TestDB-2014-07-18 12:50:33.332383"
}

3.6 - GET databases/:database_name/configuration

Returns a list of configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/configuration

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

Response:

This API call returns over 100 configuration parameters.. The following response is a small subset of the total amount returned.

[
    {
        "node_name": "ALL",
        "parameter_name": "ACDAlgorithmForSynopsisVersion1",
        "current_value": "1",
        "restart_value": "1",
        "database_value": "1",
        "default_value": "1",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Algorithm used to interpret synopsis version 1 for approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ACDLinearCountThreshold",
        "current_value": "-1.000000",
        "restart_value": "-1.000000",
        "database_value": "-1.000000",
        "default_value": "-1.000000",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "If positive, will overwrite the default linear counting threshold in approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ACDSynopsisVersion",
        "current_value": "2",
        "restart_value": "2",
        "database_value": "2",
        "default_value": "2",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "SESSION, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Default synopsis version to be generated by approximate count distinct"
    },
    {
        "node_name": "ALL",
        "parameter_name": "AHMBackupManagement",
        "current_value": "0",
        "restart_value": "0",
        "database_value": "0",
        "default_value": "0",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "NODE, DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "Consider backup epochs when setting new AHM"
    },
    {
        "node_name": "ALL",
        "parameter_name": "ARCCommitPercentage",
        "current_value": "3.000000",
        "restart_value": "3.000000",
        "database_value": "3.000000",
        "default_value": "3.000000",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "t",
        "change_requires_restart": "f",
        "description": "ARC will commit only if the change is more than the percentage specified"
    },
    {
        "node_name": "ALL",
        "parameter_name": "AWSCAFile",
        "current_value": "",
        "restart_value": "",
        "database_value": "",
        "default_value": "",
        "current_level": "DEFAULT",
        "restart_level": "DEFAULT",
        "is_mismatch": "f",
        "groups": "",
        "allowed_levels": "DATABASE",
        "superuser_visible_only": "f",
        "change_under_support_guidance": "f",
        "change_requires_restart": "f",
        "description": "Overrides the default CA file"
    },
    ...
]

3.7 - PUT databases/:database_name/configuration

Sets one or more configuration parameters for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns the parameter name, the requested value, and the result of the attempted change (Success or Failed).

Resource URL

https://<NODE>:5444/databases/:database_name/configuration

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

Example request

https://:5444/databases/testDB/configuration?user_id=username&passwd=username_password
&JavaBinaryForUDx=%2Fusr%2Fbin%2Fjava&TransactionIsolationLevel=SERIALIZABLE

Response:

[
    {
        "key": "JavaBinaryForUDx",
        "result": "Success",
        "value": "/usr/bin/java"
    },
    {
        "key": "TransactionIsolationLevel",
        "result": "Success",
        "value": "SERIALIZABLE"
    }
]

3.8 - GET databases/:database_name/hosts

Returns the hostname/IP address, node name, and UP/DOWN status of each host associated with the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        {
            "hostname": "10.20.100.247",
            "nodename": "v_vmart_node0001",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904191"
        },
        {
            "hostname": "10.20.100.248",
            "nodename": "v_vmart_node0002",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904209"
        },
        {
            "hostname": "10.20.100.249",
            "nodename": "v_vmart_node0003",
            "status": "UP",
            "ts": "2014-07-18T13:12:31.904215"
        }
    ],
    "href": "/databases/VMart/hosts",
    "links": [],
    "mime-type": "application/vertica.hosts.json-v2"
}

3.9 - POST databases/:database_name/hosts

Creates a job to add a host to the database identified by :database_name. This host must already be part of the cluster. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

Example request

Response:

{
    "id": "AddHostToDatabase-testDB-2014-07-20 12:24:04.088812",
    "url": "/jobs/AddHostToDatabase-testDB-2014-07-20 12:24:04.088812"
}

3.10 - DELETE databases/:database_name/hosts/:host_id

Creates a job to remove the host identified by :host_id from the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

Example request

Response:

{
    "id": "RemoveHostFromDatabase-testDB-2014-07-20 13:41:15.646235",
    "url": "/jobs/RemoveHostFromDatabase-testDB-2014-07-20 13:41:15.646235"
}

3.11 - POST databases/:database_name/hosts/:host_id/process

Creates a job to start the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "id": "StartDatabase-testDB-2014-07-20 13:14:03.968340",
    "url": "/jobs/StartDatabase-testDB-2014-07-20 13:14:03.968340"
}

3.12 - GET databases/:database_name/license

Returns details about the database license being used by the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/license

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "body": {
        "details": {
            "assigned_to": "Vertica Systems, Inc.",
            "grace_period": 0,
            "is_ce": false,
            "is_unlimited": false,
            "name": "vertica",
            "not_after": "Perpetual",
            "not_before": "2007-08-03"
        },
        "last_audit": {
            "audit_date": "2014-07-18 13:49:22.530105-04",
            "database_size_bytes": "814060522",
            "license_size_bytes": "536870912000",
            "usage_percent": "0.00151630588248372"
        }
    },
    "href": "/databases/VMart/license",
    "links": [],
    "mime-type": "application/vertica.license.json-v2"
}

3.13 - GET databases/:database_name/licenses

Returns details about all license being used by the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/licenses

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "body": [
        {
            "details": {
                "assigned_to": "Vertica Systems, Inc.",
                "audit_date": "2014-07-19 21:35:25.111312",
                "is_ce": "False",
                "name": "vertica",
                "node_restriction": "",
                "not_after": "Perpetual",
                "not_before": "2007-08-03",
                "size": "500GB"
            },
            "last_audit": {
                "audit_date": "2014-07-19 21:35:26.318378-04",
                "database_size_bytes": "819066288",
                "license_size_bytes": "536870912000",
                "usage_percent": "0.00152562984824181"
            }
        },
        {
            "details": {
                "assigned_to": "Vertica Systems, Inc., FlexTable",
                "audit_date": "2014-07-19 21:35:25.111312",
                "is_ce": "False",
                "name": "com.vertica.flextable",
                "node_restriction": "",
                "not_after": "Perpetual",
                "not_before": "2007-08-03",
                "size": "500GB"
            },
            "last_audit": {
                "audit_date": "2014-07-19 21:35:25.111312",
                "database_size_bytes": 0,
                "license_size_bytes": 536870912000,
                "usage_percent": 0
            }
        }
    ],
    "href": "/databases/VMart/licenses",
    "links": [],
    "mime-type": "application/vertica.features.json-v2"
}

3.14 - DELETE databases/:database_name/hosts/:host_id/process

Creates a job to stop the vertica process for the database identified by :database_name on the host identified by :host_id. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field returned by GET databases/:database_name.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 13:02:08.453547",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 13:02:08.453547"
}

3.15 - POST databases/:database_name/hosts/:host_id/replace_with/:host_id_new

Creates a job to replace the host identified by hosts/:host_id with the host identified by replace_with/:host_id. Vertica performs these operations for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns. The :host_id is the value of the host field as returned by GET databases/:database_name. You can find valid replacement hosts using GET hosts. The replacement host cannot already be part of the database. You must stop the vertica process on the host being replaced.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/hosts/:host_id/replace_with/:host_id_new

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

Example request

Response:

{
    "id": "ReplaceNode-testDB-2014-07-20 13:50:28.423509",
    "url": "/jobs/ReplaceNode-testDB-2014-07-20 13:50:28.423509"
}

3.16 - GET databases/:database_name/nodes

Returns a comma-separated list of node IDs for the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Resource URL

https://<NODE>:5444/:database_name/nodes

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

[
    {
        "database_id": "VMart",
        "node_id": "v_vmart_node0001,v_vmart_node0002,v_vmart_node0003",
        "status": "Unknown"
    }
]

3.17 - GET databases/:database_name/nodes/:node_id

Returns details about the node identified by :node_id. The :node_id is one of the node IDs returned by GET databases/:database_name/nodes.

Resource URL

https://<NODE>:5444/:database_name/nodes/:node_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "db": "VMart",
    "host": "10.20.100.247",
    "name": "v_vmart_node0001",
    "state": "UP"
}

3.18 - POST databases/:database_name/process

Creates a job to start the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that can be used to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

An example of the full request using cURL:

curl -d "epoch=epoch_number&include=host1,host2" -X POST -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/:testDB/process

Response:

{
    "id": "StartDatabase-testDB-2014-07-20 12:41:46.061408",
    "url": "/jobs/StartDatabase-testDB-2014-07-20 12:41:46.061408"
}

3.19 - GET databases/:database_name/process

Returns a state of UP or DOWN for the database identified by :database_name. The :database_name is the value of the namefield that the GET databases command returns.

Resource URL

https://<NODE>:5444/databases/:database_name/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "state": "UP"
}

3.20 - DELETE databases/:database_name/process

Creates a job to stop the database identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can useto determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

An example of the full request using cURL:

curl -X DELETE -H "VerticaApiKey: ValidAPIKey" https://<NODE>:5444/:testDB/process?user_id=dbadmin"&"passwd=vertica

Response:

{
    "id": "StopDatabase-testDB-2014-07-20 12:46:04.406637",
    "url": "/jobs/StopDatabase-testDB-2014-07-20 12:46:04.406637"
}

3.21 - POST databases/:database_name/rebalance/process

Creates a job to run a rebalance on the database identified by host identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/rebalance/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "id": "RebalanceData-testDB-2014-07-20 21:42:45.731038",
    "url": "/jobs/RebalanceData-testDB-2014-07-20 21:42:45.731038"
}

3.22 - POST databases/:database_name/Workload analyzer/process

Creates a job to run Workload Analyzer on the database identified by host identified by :database_name. The :database_name is the value of the name field that the GET databases command returns.

Returns a job ID that you can use to determine the status of the job. See GET jobs.

Resource URL

https://<NODE>:5444/databases/:database_name/Workload Analyzer/process

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

Response:

{
    "id": "AnalyzeWorkLoad-testDB-2014-07-20 21:48:27.972989",
    "url": "/jobs/AnalyzeWorkLoad-testDB-2014-07-20 21:48:27.972989"
}

4 - Hosts

You can use these API calls to get information on the hosts in your cluster.

4.1 - GET hosts

Returns a list of the hosts in the cluster and the hardware, software, and network details about each host.

Resource URL

https://<NODE>:5444/hosts

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        {
            "cpu_info": {
                "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
                "number_of_cpus": 2
            },
            "host_id": "10.20.100.247",
            "hostname": "v_vmart_node0001.example.com",
            "max_user_proc": "3833",
            "nics": [
                {
                    "broadcast": "10.20.100.255",
                    "ipaddr": "10.20.100.247",
                    "name": "eth0",
                    "netmask": "255.255.255.0",
                    "speed": "unknown"
                },
                {
                    "broadcast": "255.255.255.255",
                    "ipaddr": "127.0.0.1",
                    "name": "lo",
                    "netmask": "255.0.0.0",
                    "speed": "locallink"
                }
            ],
            "total_memory": 3833,
            "vertica": {
                "arch": "x86_64",
                "brand": "vertica",
                "release": "20140716",
                "version": "24.3.x0"
            }
        },
        {
            "cpu_info": {
                "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
                "number_of_cpus": 2
            },
            "host_id": "10.20.100.248",
            "hostname": "v_vmart_node0002.example.com",
            "max_user_proc": "3833",
            "nics": [
                {
                    "broadcast": "10.20.100.255",
                    "ipaddr": "10.20.100.248",
                    "name": "eth0",
                    "netmask": "255.255.255.0",
                    "speed": "unknown"
                },
                {
                    "broadcast": "255.255.255.255",
                    "ipaddr": "127.0.0.1",
                    "name": "lo",
                    "netmask": "255.0.0.0",
                    "speed": "locallink"
                }
            ],
            "total_memory": 3833,
            "vertica": {
                "arch": "x86_64",
                "brand": "vertica",
                "release": "20140716",
                "version": "24.3.x0"
            }
        },
        {
            "cpu_info": {
                "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
                "number_of_cpus": 2
            },
            "host_id": "10.20.100.249",
            "hostname": "v_vmart_node0003.example.com",
            "max_user_proc": "3833",
            "nics": [
                {
                    "broadcast": "10.20.100.255",
                    "ipaddr": "10.20.100.249",
                    "name": "eth0",
                    "netmask": "255.255.255.0",
                    "speed": "unknown"
                },
                {
                    "broadcast": "255.255.255.255",
                    "ipaddr": "127.0.0.1",
                    "name": "lo",
                    "netmask": "255.0.0.0",
                    "speed": "locallink"
                }
            ],
            "total_memory": 3833,
            "vertica": {
                "arch": "x86_64",
                "brand": "vertica",
                "release": "20140716",
                "version": "24.3.x0"
            }
        }
    ],
    "href": "/hosts",
    "links": [
        "/:hostid"
    ],
    "mime-type": "application/vertica.hosts.json-v2"
}

4.2 - GET hosts/:hostid

Returns hardware, software, and network details about the host identified by :host_id. You can find :host_id for each host using GET hosts.

Resource URL

https://<NODE>:5444/hosts/:hostid

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": {
        "cpu_info": {
            "cpu_type": " Intel(R) Xeon(R) CPU E5-2695 v2 @ 2.40GHz",
            "number_of_cpus": 2
        },
        "hostname": "v_vmart_node0001.example.com",
        "max_user_proc": "3833",
        "nics": [
            {
                "broadcast": "10.20.100.255",
                "ipaddr": "10.20.100.247",
                "name": "eth0",
                "netmask": "255.255.255.0",
                "speed": "unknown"
            },
            {
                "broadcast": "255.255.255.255",
                "ipaddr": "127.0.0.1",
                "name": "lo",
                "netmask": "255.0.0.0",
                "speed": "locallink"
            }
        ],
        "total_memory": 3833,
        "vertica": {
            "arch": "x86_64",
            "brand": "vertica",
            "release": "20140716",
            "version": "24.3.x0"
        }
    },
    "href": "/hosts/10.20.100.247",
    "links": [],
    "mime-type": "application/vertica.host.json-v2"
}

5 - Jobs

You can use these API calls to get information on your database's jobs.

5.1 - GET jobs

Returns a list of jobs being tracked by the agent and job details.

Jobs always start immediately. The is_running field is a Boolean value. If is_running is false, then the job is complete.

The exit_code details the status of the job. The exit_code is different for certain types of jobs:

• For Backup jobs:

  • 0 indicates success.

  • Any other number indicates a failure.

• For all other jobs:

  • -9 indicates success.

  • Any other number indicates a failure.

You can see details about failures in /opt/vertica/log/agentStdMsg.log.

Resource URL

https://<NODE>:5444/jobs

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        {
            "exit_code": 0,
            "id": "CreateBackup-VMart-1405012447.75",
            "is_running": false,
            "status": "unused",
            "ts": "1405012461.18"
        },
        {
            "exit_code": 1,
            "id": "CreateBackup-VMart-1405012454.88",
            "is_running": false,
            "status": "unused",
            "ts": "1405012455.18"
        }
    ],
    "href": "/jobs",
    "links": [
        "/:jobid"
    ],
    "mime-type": "application/vertica.jobs.json-v2"
}

5.2 - GET jobs/:id

Gets the details for a specific job with the provided :id. You can determine the list of job :ids usingGET jobs.

Details for a specific job are the same as the details provided for all jobs byGET jobs.

Resource URL

https://<NODE>:5444/jobs/:id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

6 - Licenses

You can use these API calls to manage licenses for your database.

6.1 - POST licenses

Uploads and applies a license file to this cluster.

You must provide the license file as an HTTP POST form upload, identified by the name license. For example, you can use cURL:

curl -k --request POST -H "VerticaApiKey:ValidAPIKey" \
https://v_vmart_node0001:5444/licenses --form "license=@vlicense.dat"

Resource URL

https://<NODE>:5444/licenses

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have admin level security.

Parameters

None.

Example request

Response:

There is no HTTP body response for successful uploads. A successful upload returns an HTTP 200/OK header.

6.2 - GET licenses

Returns any license files that are used by this cluster when creating databases. License files must reside in /opt/vertica/config/share.

Resource URL

https://<NODE>:5444/licenses

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        {
            "comment": "Vertica license is valid",
            "end": "Perpetual",
            "grace": "0",
            "size": "1TB CE Nodes 3",
            "start": "2011-11-22",
            "status": true,
            "vendor": "Vertica Community Edition"
        }
    ],
    "href": "/license",
    "links": [],
    "mime-type": "application/vertica.license.json-v2"
}

7 - Nodes

You can use these API calls to retrieve information on the nodes in your cluster.

7.1 - GET nodes

Returns a list of nodes associated with this cluster.

Resource URL

https://<NODE>:5444/nodes

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        "node0001",
        "node0002",
        "node0003",
        "v_testdb_node0001",
        "v_testdb_node0002",
        "v_testdb_node0003",
        "v_vmart_node0001",
        "v_vmart_node0002",
        "v_vmart_node0003"
    ],
    "href": "/nodes",
    "links": [
        "/:nodeid"
    ],
    "mime-type": "application/vertica.nodes.json-v2"
}

7.2 - GET nodes/:nodeid

Returns details about the node identified by :node_id. You can find the :node_id for each node using GET nodes.

In the body field, the following information is detailed in comma-separated format:

• Node Name

• Host Address

• Catalog Directory

• Data Directory

Resource URL

https://<NODE>:5444/nodes/:node_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        "v_vmart_node0001",
        "10.20.100.247,/home/dbadmin,/home/dbadmin"
    ],
    "href": "/nodes/v_vmart_node0001",
    "links": [],
    "mime-type": "application/vertica.node.json-v2"
}

8 - Webhooks

You can use these API calls to obtain information on, create, or delete webhooks.

8.1 - GET webhooks

Returns a list of active webhooks for this cluster.

Resource URL

https://<NODE>:5444/webhooks

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

{
    "body": [
        {
            "host": "192.168.232.1",
            "id": "79c1c8a18be02804b3d2f48ea6462909",
            "port": 80,
            "timestamp": "2014-07-20 22:54:09.829642",
            "url": "/gettest.htm"
        },
        {
            "host": "192.168.232.1",
            "id": "9c32cb0f3d2f9a7cb10835f1732fd4a7",
            "port": 80,
            "timestamp": "2014-07-20 22:54:09.829707",
            "url": "/getwebhook.php"
        }
    ],
    "href": "/webhooks",
    "links": [
        "/subscribe",
        "/:subscriber_id"
    ],
    "mime-type": "application/vertica.webhooks.json-v2"
}

8.2 - POST webhooks/subscribe

Creates a subscription for a webhook.

Resource URL

https://<NODE>:5444/webhooks/subscribe

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

Example request

Response:

The response is not JSON encoded. The only text response is the ID of the webhook subscription. Additionally, an HTTP 200/OK header indicates success.

79c1c8a18be02804b3d2f48ea6462909

8.3 - DELETE webhooks/:subscriber_id

Deletes the webhook identified by :subscriber_id. The :subscriber_id is the value of the id field that the GET webhooks command returns.

Resource URL

https://<NODE>:5444/webhooks/:subscriber_id

Authentication

Requires a VerticaAPIKey in the request header.

The API key must have restricted level security or higher.

Parameters

None.

Example request

Response:

There is no HTTP body response for successful deletes. A successful delete returns an HTTP 200/OK header.