Log Insight API documentation version v1

https://127.0.0.1:9543/api/v1

Getting started with the Log Insight REST API

ATTENTION:

This document may not correspond to your vRLI instance version.
To access the vRealize Log Insight API reference, navigate to this page in your browser: http:// Your_Log_Insight_host/rest-api

Check for the latest Product Documentation "vRealize Log Insight Developer Resources" guide in vRLI Documentation

Log Insight REST API provides programmatic access to Log Insight and to the data it collects. You use the API to insert events into the Log Insight data store and to query for those events. Manage the lifecycle of a Log Insight cluster, including initial or ongoing configuration and upgrades.

Use HTTPS on port 9543 with JSON payloads for all API requests.

Ingesting Events

Ingest and index new log events via POST /api/v1/events/ingest/{UUID}. This is a non-authenticated interface designed for use by collection agents. Submit 1-500 events together in a single batch.

For example, we can ingest a single message:

curl -k -X POST https://loginsight.example.com:9543/api/v1/events/ingest/aexample-uuid-4b7a-8b09-fbfac4b46fd9 -d '{"events":[{"text":"Test Event"}]}'
{"status":"ok","message":"events ingested","ingested":1}

Authorization

Most Log Insight APIs require authentication. Your application uses /api/v1/sessions to authenticate with Log Insight and obtain a session ID. The Session ID is a opaque bearer token valid for a limited time, indicated by the ttl value in the response.

For example, we can authenticate using the Local admin account.

curl -k -X POST https://loginsight.example.com:9543/api/v1/sessions \
    -d '{"username":"admin","password":"Secret!","provider":"Local"}'
{
  "userId":"3c1b81cc-418e-44c0-b91a-54e10a87b1d3",
  "sessionId":"1234abcd-opaque-bearer-token-abcdlS7QF2hkqVho==",
  "ttl":1800
}

The Session ID is a opaque bearer token valid for a limited time, indicated by the ttl value in the response.

Your application passes that session ID in the Authorization header of subsequent requests.

curl -k https://loginsight.example.com:9543/api/v1/sessions/current \
    --header "Authorization: Bearer 1234abcd-opaque-bearer-token-abcdlS7QF2hkqVho=="
{
  "userId":"3c1b81cc-418e-44c0-b91a-54e10a87b1d3"
}

Querying

Log events ingested by Log Insight can be searched to return individual events, or can be used to compute aggregations (numeric sequences) from a large collection of events. The two query forms are analogous to the bottom and top halves of the Interactive Analytics user interface.

Retrieve raw log messages via GET /api/v1/events.
Produce an numeric sequence via GET /api/v1/aggregated-events. Common aggregation functions (COUNT, UCOUNT, AVG, MIN, MAX, SUM, STDDEV, VARIANCE, SAMPLE) can be used on both static and dynamic fields.

Constrain requests for log events to those required for your usecase. Queries can be constrained with static fields and/or extracted fields defined by content packs. Pass constraints within the URL, similar to GET /api/v1/events/constraint1/constraint2/

For example, we can query for events where the text field contains Test in the last 6 minutes. Pass the session ID we got earlier in the Authorization header. We get back a list including the test event we ingested earlier, along with a list of metadata fields.

curl -k https://loginsight.example.com:9543/api/v1/events/text/CONTAINS%20Test/timestamp/LAST%20360000 \
    --header "Authorization: Bearer 1234abcd-opaque-bearer-token-abcdlS7QF2hkqVho=="
{
  "complete":true,
  "duration":11,
  "events":[
    {
      "text":"Test Event",
      "timestamp":1505106771135,
      "fields":[
        {"name":"source","content":"10.11.12.13"},
        {"name":"event_type","content":"v4_d0382720"}
      ]
    }
  ]
}

Defaults

Default values are set for simple & fast queries, but can be altered per-request.

Queries are limited to 100 events or bins by default. You can raise that limit up to 20,000 events or 2,000 bins using the limit query parameter.
Queries complete execution within 30 seconds by default. If the query cannot complete within that time, partial results are returned. You can raise the timeout to a higher value using the timeout query parameter.
Queries are limited to events with a timestamp of one minute ago or newer. You can specify a longer time range with a timestamp constraint.

The API lifecycle

The lifecycle of a Log Insight API has several phases, usually starting with introduction in Tech Preview before becoming Supported.

Supported APIs are suitable for consumption by integration, automation or standalone tools. These are stable interfaces that don't change on upgrades.
Tech Preview APIs are publicly released and are suitable for experimentation. Their design or implementation may change without warning and should not be depended on. A tech preview API may become supported, have forwards-incompatible changes or be removed during an upgrade. Feedback is welcome.
Deprecated APIs were formally supported but will soon be removed completely. An API planned for removal will usually be marked deprecated for at least two releases (e.g. supported, deprecated, deprecated, removed) to give developers or users time to adjust.

If a request is made to a Tech Preview or Deprecated API, the lifecycle status will be returned in two headers, VMware-LI-API-Status and Warning. Supported APIs do not carry these headers.

The VMware-LI-API-Status header is machine readable, containing the exact string Tech Preview or Deprecated. This is suitable for verification in test cases or conditional client behavior.

The Warning header is formatted as described in RFC 2616, consisting of warn-code 299, a nil agent, a human-readable description of the corresponding VMware-LI-API-Status and the date the request was made. This is suitable for logging or presenting to a user as-is, but should not be parsed.

For example:

VMware-LI-API-Status: Tech Preview
Warning: 299 - "Tech Preview: This API is a tech-preview. It is subject to change or removal as the product evolves." Thu, 01 Jan 1979 00:00:00 GMT

VMware-LI-API-Status: Deprecated
Warning: 299 - "Deprecated: This API is deprecated, and will be removed in a future release." Thu, 01 Jan 1979 00:00:01 GMT

FAQ

How do I collect a log bundle using the REST API?

The support bundle API lets you make a POST request to create a new support bundle and retrieve it as an attachment in the response. The POST api/v1/appliance/vm-support-bundles lets you create and download an entire support bundle with all available manifests or only required manifests by specifying the manifest ID in the POST request data.

/api/v1/ad Active Directory configuration settings

Describes the current Active Directory configuration settings.

get
post

get /api/v1/ad

Gets the Active Directory configuration settings.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the Active Directory configuration settings.

Body: application/json

{
  "enableAD": true,
  "domain": "example.com",
  "domainServers": ["host1.example.com", "host2.example.com", "host3.example.com"],
  "username": "exampleuser",
  "password": "",
  "connType": "CUSTOM",
  "port": 636,
  "sslOnly": true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "enableAD": {
      "type": "boolean"
    },
    "domain": {
      "type": "string"
    },
    "domainServers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "connType": {
      "type": "string",
      "enum": [
        "STANDARD",
        "GLOBAL_CAT",
        "CUSTOM"
      ]
    },
    "port": {
      "type": "integer"
    },
    "sslOnly": {
      "type": "boolean"
    }
  },
  "required" : [
    "enableAD"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Authenticated requests must include an Authorization header with a session ID that was retrieved from /api/v1/sessions. The session ID has a limited lifespan. Access is allowed only to resources that the user is authorized to use.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/ad

Updates the Active Directory configuration settings.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "enableAD": true,
  "domain": "example.com",
  "domainServers": ["host1.example.com", "host2.example.com", "host3.example.com"],
  "username": "exampleuser",
  "password": "password",
  "connType": "CUSTOM",
  "port": 636,
  "sslOnly": true,
  "acceptCert" : true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "enableAD": {
      "type": "boolean"
    },
    "domain": {
      "type": "string"
    },
    "domainServers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "connType": {
      "type": "string",
      "enum": [
        "STANDARD",
        "GLOBAL_CAT",
        "CUSTOM"
      ]
    },
    "port": {
      "type": "integer"
    },
    "sslOnly": {
      "type": "boolean"
    },
    "acceptCert": {
      "type": "boolean"
    }
  },
  "required" : [
    "enableAD"
  ]
}

Response

HTTP status code 200

Successfully updated the Active Directory configuration settings.

Body: application/json

{
}

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/ad/test

post

post /api/v1/ad/test

Tests if the Active Directory domain controller can be accessed using the credentials in the configuration settings.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "enableAD": true,
  "domain": "example.com",
  "domainServers": ["host1.example.com", "host2.example.com", "host3.example.com"],
  "username": "exampleuser",
  "password": "password",
  "connType": "CUSTOM",
  "port": 636,
  "sslOnly": true,
  "acceptCert" : true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "enableAD": {
      "type": "boolean"
    },
    "domain": {
      "type": "string"
    },
    "domainServers": {
      "type": "array",
      "items": {
        "type": "string"
      }
    },
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "connType": {
      "type": "string",
      "enum": [
        "STANDARD",
        "GLOBAL_CAT",
        "CUSTOM"
      ]
    },
    "port": {
      "type": "integer"
    },
    "sslOnly": {
      "type": "boolean"
    },
    "acceptCert": {
      "type": "boolean"
    }
  },
  "required" : [
    "enableAD"
  ]
}

Response

HTTP status code 200

Successfully verified the connection to Active Directory.

HTTP status code 400

Failed to verify a connection to Active Directory

Body: application/json

{
  "errorMessage": "AD authentication failed.",
  "errorCode": "TEST_ERROR",
  "errorDetails": {
    "errorCode": "com.vmware.loginsight.api.errors.wrong_credentials"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/agent/groups/{cpNameSpace}

/api/v1/agent/packages/files

/api/v1/agent/packages/info

/api/v1/agent/packages/types

/api/v1/agent/status

/api/v1/aggregated-events

/api/v1/aggregated-events/{+path}

get /api/v1/aggregated-events/{+path}

Queries Log Insight for groups of events.

This is a supported API.

Request

URI Parameters

+path: required (string)
Specifies constraints on the events to retrieve. See the specifying constraints section of /events for details.

Query Parameters

limit: (integer - default: 100 - minimum: 1 - maximum: 2147483647)
The maximum number of events to retrieve.
timeout: (integer - default: 30000 - maximum: 2147483647)
The time to wait for a response. If the complete result is not available within that time, partial result is returned and the complete flag is set to true.
view: (one of DEFAULT, SIMPLE - default: DEFAULT)
The format of query results in the reponse.
content-pack-fields: (string)
The namespace of a content pack to take fields from. If provided, fields defined in the given content-pack are returned in the response, in addition to static fields. Specify this parameter more than once to extract fields from several content packs. If this parameter is not specified, then only static fields are returned in the response payload
bin-width: (integer - default: 5000 - minimum: 1 - maximum: 2147483647)
The time-span of time range bins, in milliseconds.
aggregation-function: (one of COUNT, SAMPLE, UCOUNT, MIN, MAX, SUM, STDDEV, VARIANCE - default: COUNT)
The aggregation function to use. One of the following values:
- COUNT: The count of the events in each bin is returned
- SAMPLE: An arbitrary event from each bin is returned
- UCOUNT: The count of unique values in the bin
- MIN: The minimum value in the bin
- MAX: The maximum value in the bin
- SUM: The sum of the values in the bin
- STDDEV: The standard deviation of the values in the bin
- VARIANCE: The variance of the values in the bin
aggregation-field: (string)
The field to aggregate. This parameter is required for all aggregation functions, except COUNT and SAMPLE. It is not supported for COUNT and SAMPLE.
group-by-field: (string)
Specify additional GROUP BY fields. Use subsequent key=value pairs to specify custom bins for numeric fields: use bin-width=12345 to specify fixed-width bins; use bins=10,100,500 to specify a specific set of bin boundaries; if neither is specified then each individual value of the field is assigned to its own bucket.
order-by-function: (one of COUNT, UCOUNT, MIN, MAX, SUM, STDDEV, VARIANCE)
The aggregation function to use for ordering the bins. Those are the same functions as in the aggregation-function query parameter, with the exception of SAMPLE which is not supported.
order-by-field: (string)
The field to sort by.
order-by-direction: (one of ASC, DESC - default: DESC)
The sort direction.

Response

HTTP status code 200

Body: application/json

{
  "complete": true,
  "duration": 90,
  "results": [
    {
      "minTimestamp": 0,
      "maxTimestamp": 9223372036828799999,
      "event_type": "v4_4a6fdf4b",
      "COUNT(event)": 50,
      "SAMPLE(event)": {
        "text": "[2017-06-13 15:27:22.606] ...",
        "timestamp": 1497353242606,
        "timestampString": "2017-06-13 15:27:22.606 GMT+04:00",
        "appname": "Vpxa",
        "event_type": "v4_df1bc800",
        "hostname": "li-qe-esx5.vmware.com",
        "source": "127.0.0.1"
      }
    },
    {
      "minTimestamp": 0,
      "maxTimestamp": 9223372036828799999,
      "event_type": "v4_dc0c9904",
      "COUNT(event)": 100,
      "SAMPLE(event)": {
        "text": "[2017-06-13 15:27:52.491-0700] ...",
        "timestamp": 1497353272491,
        "timestampString": "2017-06-13 15:27:52.491 GMT+04:00",
        "event_type": "v4_dc0c9904",
        "source": "127.0.0.1"
      }
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "properties": {
    "bins": {
      "description": "Lists bins of events matching the query. Present when view=DEFAULT",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "minTimestamp": {
            "description": "The lowest timestamp in the bin, in milliseconds since 00:00:00 UTC on 1 January 1970",
            "type": "integer"
          },
          "minTimestampString": {
            "description": "The lowest timestamp in the bin, in ISO8601 format with time zone offset",
            "type": "string"
          },
          "maxTimestamp": {
            "description": "The highest timestamp in the bin, in milliseconds since 00:00:00 UTC on 1 January 1970",
            "type": "integer"
          },
          "maxTimestampString": {
            "description": "The highest timestamp in the bin, in ISO8601 format with time zone offset",
            "type": "string"
          },
          "keys": {
            "description": "The values of the GROUP BY fields for this bin. Present only when GROUP BY fields are requested with 'group-by-field'.",
            "type": "array"
          },
          "value": {
            "description": "The value of the aggregation function on the events in the bin. Present when one aggregation function is requested; see also 'values'.",
            "type": "number"
          },
          "values": {
            "description": "The values of the aggregation functions on the events in the bin. Present when more than one aggregation function is requested; see also 'value'.",
            "type": "array"
          }
        }
      }
    },
    "results": {
      "description": "List of rows in simple query results table. Present when view=SIMPLE",
      "type": "array",
      "items": {
        "type": "object",
        "additionalProperties": true,
        "entries": {
          "minTimestamp": {
            "description": "The lowest timestamp in the bin, in milliseconds since 00:00:00 UTC on 1 January 1970",
            "type": "integer"
          },
          "minTimestampString": {
            "description": "The lowest timestamp in the bin, in ISO8601 format with time zone offset",
            "type": "string"
          },
          "maxTimestamp": {
            "description": "The highest timestamp in the bin, in milliseconds since 00:00:00 UTC on 1 January 1970",
            "type": "integer"
          },
          "maxTimestampString": {
            "description": "The highest timestamp in the bin, in ISO8601 format with time zone offset",
            "type": "string"
          },
          "group-by-field-1": {
            "description": "group by field <name,value> pair",
            "type": "string"
          },
          "aggregation-function-1": {
            "description": "aggregation function <name,value> pair",
            "type": "string or object (aggregation-function=SAMPLE)"
          }
        }
      }
    },
    "complete": {
      "description": "Indicates whether all matching bins were returned (true), or if only some of them where, because the timeout expired or other problems (false).  See also 'warnings'.",
      "type": "boolean"
    },
    "duration": {
      "description": "The time required to compute the results, in milliseconds.",
      "type": "number"
    },
    "warnings": {
      "description": "A list of problems that were encountered while processing the query. Present if 'complete' is false.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "An identifier for the problem.",
            "type": "number"
          },
          "details": {
            "description": "A description of the problem.",
            "type": "string"
          },
          "progress": {
            "description": "The fraction of events processed when the timeout expired. Present for id 128 which indicates that the request timeout expired.",
            "type": "number"
          }
        }
      }
    }
  },
  "dependencies": {
    "warnings": {"properties": {
      "complete": {"type": "boolean", "enum": [false]}
    }}
  },
  "type": "object",
  "required": ["complete"]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/alerts

get
post

get /api/v1/alerts

Get all the alerts created by the current user

This is a supported API.

Response

HTTP status code 200

A list of all the current user's alerts

Body: application/json

[
  {
    "id":"32ffeeb9-427e-475d-a983-a92a77c485c8",
    "enabled":true,
    "emailEnabled":true,
    "vcopsEnabled":false,
    "alertType":"RATE_BASED_WITH_GROUPS",
    "name":"Hello Alert 3",
    "hitCount":5,
    "searchPeriod":300000,
    "searchInterval":60000,
    "emails":"email@address.com",
    "info":"This is an example of a rate based with groups alert",
    "vcopsResourceName":"",
    "vcopsCriticality":"none",
    "lastRanAt": 1497017941283,
    "lastRanAtString": "2017-06-09 18:19:01.283 GMT+04:00",
    "nextRunAt": 1497018241283,
    "nextRunAtString": "2017-06-09 18:24:01.283 GMT+04:00",
    "runCount":79,
    "lastRunTime":4,
    "totalRunTime":55186,
    "lastHitTimestamp": 1497017922145,
    "lastHitTimestampString": "2017-06-09 18:18:42.145 GMT+04:00",
    "ownerUuid":"1f024658-8b93-4f45-ae59-4657f96a5450",
    "webhookEnabled":false,
    "autoClearAlertAfterTimeout":false,
    "chartQuery": "{\"query\":\"\",\"startTimeMillis\":1506417301511,\"endTimeMillis\":1506423141233,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[{\"internalName\":\"ibadax3fpbpwm2lfnrsf643bl5stezk7onugc4tfmq000000\",\"operator\":\"CONTAINS\",\"value\":\"lang\"},{\"internalName\":\"ibadgns7mm4domrsgq4dkllgmvstcljrgfsteljygnrdoljsgbrtszbqgq3win3bg5sxqx3gnfwgkzc7onqv6zjsmvpw433oonugc4tfmrpwe6k7mfsg22lo\",\"operator\":\"CONTAINS\",\"value\":\"run\"}],\"supplementalConstraints\":[],\"group"
  },
  {
    "id":"94110e39-efd8-48ae-a767-2bf96afefc40",
    "enabled":true,
    "emailEnabled":true,
    "vcopsEnabled":false,
    "alertType":"NEW_EVENT_TYPE",
    "name":"Hello Alert 4",
    "hitCount":0,
    "searchPeriod":300000,
    "searchInterval":300000,
    "emails":"email@address.com",
    "info":"This is an example of a new event type alert",
    "vcopsResourceName":"",
    "vcopsCriticality":"immediate",
    "lastRanAt": 1497017941391,
    "lastRanAtString": "2017-06-09 18:19:01.391 GMT+04:00",
    "nextRunAt": 1497018241391,
    "nextRunAtString": "2017-06-09 18:24:01.391 GMT+04:00",
    "runCount":17,
    "lastRunTime":1,
    "totalRunTime":31,
    "lastHitTimestamp": 1497017922145,
    "lastHitTimestampString": "2017-06-09 18:18:42.145 GMT+04:00",
    "ownerUuid":"1f024658-8b93-4f45-ae59-4657f96a5450",
    "webhookEnabled":false,
    "autoClearAlertAfterTimeout":false,
    "chartQuery": "{\"query\":\"\",\"startTimeMillis\":1506417301511,\"endTimeMillis\":1506423141233,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[{\"internalName\":\"ibadax3fpbpwm2lfnrsf643bl5stezk7onugc4tfmq000000\",\"operator\":\"CONTAINS\",\"value\":\"lang\"},{\"internalName\":\"ibadgns7mm4domrsgq4dkllgmvstcljrgfsteljygnrdoljsgbrtszbqgq3win3bg5sxqx3gnfwgkzc7onqv6zjsmvpw433oonugc4tfmrpwe6k7mfsg22lo\",\"operator\":\"CONTAINS\",\"value\":\"run\"}],\"supplementalConstraints\":[],\"group"
  },
  {
    "id":"df3cb390-1a0b-48ea-baa3-1116858127bc",
    "enabled":true,
    "emailEnabled":true,
    "vcopsEnabled":false,
    "alertType":"RATE_BASED",
    "name":"Hello Alert 2",
    "hitCount":0,
    "searchPeriod":300000,
    "searchInterval":300000,
    "emails":"email@address.com",
    "info":"This is an example of an on any match alert",
    "vcopsResourceName":"",
    "vcopsCriticality":"none",
    "lastRanAtString": "2017-06-09 18:19:01.439 GMT+04:00",
    "nextRunAt": 1497018241439,
    "nextRunAtString": "2017-06-09 18:24:01.439 GMT+04:00",
    "runCount":17,
    "lastRunTime":1,
    "totalRunTime":36,
    "lastHitTimestamp": 1497017922145,
    "lastHitTimestampString": "2017-06-09 18:18:42.145 GMT+04:00",
    "ownerUuid":"1f024658-8b93-4f45-ae59-4657f96a5450",
    "webhookEnabled":false,
    "autoClearAlertAfterTimeout":false,
    "chartQuery": "{\"query\":\"\",\"startTimeMillis\":1506417301511,\"endTimeMillis\":1506423141233,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[{\"internalName\":\"ibadax3fpbpwm2lfnrsf643bl5stezk7onugc4tfmq000000\",\"operator\":\"CONTAINS\",\"value\":\"lang\"},{\"internalName\":\"ibadgns7mm4domrsgq4dkllgmvstcljrgfsteljygnrdoljsgbrtszbqgq3win3bg5sxqx3gnfwgkzc7onqv6zjsmvpw433oonugc4tfmrpwe6k7mfsg22lo\",\"operator\":\"CONTAINS\",\"value\":\"run\"}],\"supplementalConstraints\":[],\"group"
  },
  {
    "id":"fc7bfcac-200c-4840-b349-b885338f03d1",
    "enabled":true,
    "emailEnabled":true,
    "vcopsEnabled":true,
    "alertType":"RATE_BASED",
    "name":"Hello Alert",
    "hitCount":2,
    "searchPeriod":300000,
    "searchInterval":60000,
    "emails":"email1@address.com, email2@address.com",
    "info":"This is an example of a rate based alert",
    "vcopsResourceName":"local-li-wdc-li1-04",
    "vcopsCriticality":"immediate",
    "lastRanAt": 1497018241300,
    "lastRanAtString": "2017-06-09 18:24:01.300 GMT+04:00",
    "nextRunAt": 1497018541300,
    "nextRunAtString": "2017-06-09 18:29:01.300 GMT+04:00",
    "runCount":86,
    "lastRunTime":1,
    "totalRunTime":1039,
    "lastHitTimestamp": 1497018235310,
    "lastHitTimestampString": "2017-06-09 18:23:55.310 GMT+04:00",
    "ownerUuid":"1f024658-8b93-4f45-ae59-4657f96a5450",
    "webhookEnabled":true,
    "webhookURLs":"http://example.com/webhook1 http://example.com/webhook2",
    "autoClearAlertAfterTimeout":false,
    "chartQuery": "{\"query\":\"\",\"startTimeMillis\":1506417301511,\"endTimeMillis\":1506423141233,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[{\"internalName\":\"ibadax3fpbpwm2lfnrsf643bl5stezk7onugc4tfmq000000\",\"operator\":\"CONTAINS\",\"value\":\"lang\"},{\"internalName\":\"ibadgns7mm4domrsgq4dkllgmvstcljrgfsteljygnrdoljsgbrtszbqgq3win3bg5sxqx3gnfwgkzc7onqv6zjsmvpw433oonugc4tfmrpwe6k7mfsg22lo\",\"operator\":\"CONTAINS\",\"value\":\"run\"}],\"supplementalConstraints\":[],\"group"
  }
]

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",
   "type":"array",
   "items":{
      "type":"object",
      "properties":{
         "id":{
            "type":"string",
            "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
         },
         "enabled":{
            "type":"boolean"
         },
         "alertType":{
            "enum":[
               "RATE_BASED",
               "RATE_BASED_WITH_GROUPS",
               "NEW_EVENT_TYPE"
            ]
         },
         "name":{
            "type":"string"
         },
         "hitCount":{
            "type":"integer",
            "minimum":0,
            "maximum": 100000
         },
         "searchPeriod":{
            "type":"integer",
            "minimum":60000
         },
         "searchInterval":{
            "type":"integer",
            "minimum":60000
         },
         "info":{
            "type":"string"
         },
         "emailEnabled":{
            "type":"boolean"
         },
         "emails":{
            "type":"string",
            "description":"A comma-separated list of email addresses"
         },
         "vcopsEnabled":{
            "type":"boolean"
         },
         "vcopsResourceName":{
            "type":"string"
         },
         "vcopsCriticality":{
            "enum":[
               "none",
               "information",
               "warning",
               "immediate",
               "critical"
            ]
         },
         "webhookEnabled":{
            "type":"boolean"
         },
         "webhookURLs":{
            "type":"string",
            "description":"A space-separated list of URLs"
         },
         "lastRanAt":{
            "type":"integer"
         },
         "lastRanAtString":{
            "type":"string"
         },
         "nextRunAt":{
            "type":"integer"
         },
         "nextRanAtString":{
            "type":"string"
         },
         "runCount":{
            "type":"integer"
         },
         "lastRunTime":{
            "type":"integer"
         },
         "totalRunTime":{
            "type":"integer"
         },
         "lastHitTimestamp":{
            "type":"integer"
         },
         "lastHitTimestampString":{
            "type":"string"
         },
         "ownerUuid":{
            "type":"string",
            "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
         },
         "autoClearAlertAfterTimeout":{
            "type":"boolean"
         },
         "chartQuery":{
            "type":"string",
            "description":"A string of JSON format"
         }
      }
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/alerts

Create a new alert by given parameters. The 'name' parameter is mandatory. There are some optional parameters as well, but some of them could be required in specific combination with other parameters. For example:

When the field 'emailEnabled' is set to 'true' then at least one email address should be specified in the 'emails' field.
When the field 'webhookEnabled' is set to 'true' then at least one URL should be specified in the 'webhookURLs' field.
When the field 'vcopsEnabled' is set to 'true' then 'vcopsResourceKindKey' field should be specified.

This is a supported API.

Request

Body: application/json

{
  "name":"My Alert",
  "info":"This is an example of a rate based alert",
  "recommendation":"Some text for recommendation",
  "emailEnabled":true,
  "emails":"email1@example.com, email2@example.com",
  "webhookEnabled":true,
  "webhookURLs":"http://username:password@example.com/webhook1 http://example.com/webhook2",
  "vcopsEnabled":true,
  "vcopsCriticality":"none",
  "vcopsResourceKindKey":"resourceName=test-vsan-template&adapterKindKey=VMWARE&resourceKindKey=VirtualMachine&identifiers=VMEntityName::test-vsan-template$$VMEntityObjectID::vm-107$$VMEntityVCID::94a1a7ea-ff03-4c18-827a-413998b7308c",
  "autoClearAlertAfterTimeout":false,
  "alertType":"RATE_BASED",
  "hitCount":4,
  "searchPeriod":300000,
  "hitOperator": "GREATER_THAN",
  "chartQuery":"{\"query\":\"alert\",\"startTimeMillis\":1500451917374,\"endTimeMillis\":1500532872702,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[],\"supplementalConstraints\":[],\"groupByFields\":[],\"extractedFields\":[]}"
}

Schema:

{
  "$schema": "http: //json-schema.org/draft-04/schema",
  "type":  "object",
  "properties": {
    "alertType": {
      "enum": [
        "RATE_BASED",
        "RATE_BASED_WITH_GROUPS",
        "NEW_EVENT_TYPE"
      ]
    },
    "name": {
      "type":  "string"
    },
    "chartQuery": {
      "type": "string",
      "description": "A query in json or piql format"
    },
    "messageQuery": {
      "type": "string",
      "description": "A query in json or piql format"
    },
    "hitCount": {
      "type": "integer",
      "minimum": 0,
      "maximum": 100000,
      "default": 0
    },
    "hitOperator": {
      "enum": [
        "GREATER_THAN",
        "LESS_THAN"
      ],
      "default": "GREATER_THAN"
    },
    "searchPeriod": {
      "type": "integer",
      "minimum": 60000,
      "default": 300000
    },
    "info": {
      "type": "string"
    },
    "recommendation": {
      "type": "string"
    },
    "emailEnabled": {
      "type": "boolean",
      "default": false
    },
    "emails": {
      "type": "string",
      "description": "A comma-separated list of email addresses"
    },
    "vcopsEnabled": {
      "type": "boolean",
      "default": false
    },
    "vcopsResourceKindKey": {
      "type": "string",
      "description": "A vROps resource string containing resourceName, adapterKindKey, resourceKindKey, identifiers and etc."
    },
    "vcopsCriticality": {
      "enum": [
        "none",
        "information",
        "warning",
        "immediate",
        "critical"
      ],
      "default": "none"
    },
    "autoClearAlertAfterTimeout": {
      "type": "boolean",
      "default": false
    },
    "webhookEnabled": {
      "type": "boolean",
      "default": false
    },
    "webhookURLs": {
      "type": "string",
      "description": "A space-separated list of URLs"
    }
  },
  "required":  [
    "name"
  ]
}

Response

HTTP status code 201

Created a new alert with the provided data

Body: application/json

{
  "id":"fc7bfcac-200c-4840-b349-b885338f03d1",
  "enabled":true,
  "emailEnabled":true,
  "vcopsEnabled":true,
  "alertType":"RATE_BASED",
  "name":"Hello Alert",
  "hitCount":2,
  "searchPeriod":300000,
  "searchInterval":60000,
  "emails":"email1@address.com, email2@address.com",
  "info":"This is an example of a rate based alert",
  "vcopsResourceName":"local-li-wdc-li1-04",
  "vcopsCriticality":"immediate",
  "lastRanAt": 1497017941283,
  "lastRanAtString": "2017-06-09 18:19:01.283 GMT+04:00",
  "nextRunAt": 1497018241283,
  "nextRunAtString": "2017-06-09 18:24:01.283 GMT+04:00",
  "runCount":7,
  "lastRunTime":800,
  "totalRunTime":946,
  "lastHitTimestamp": 1497017922145,
  "lastHitTimestampString": "2017-06-09 18:18:42.145 GMT+04:00",
  "ownerUuid":"1f024658-8b93-4f45-ae59-4657f96a5450",
  "webhookEnabled":true,
  "webhookURLs":"http://example.com/webhook1 http://example.com/webhook2",
  "autoClearAlertAfterTimeout":false,
  "chartQuery": "{\"query\":\"\",\"startTimeMillis\":1506417301511,\"endTimeMillis\":1506423141233,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[{\"internalName\":\"ibadax3fpbpwm2lfnrsf643bl5stezk7onugc4tfmq000000\",\"operator\":\"CONTAINS\",\"value\":\"lang\"},{\"internalName\":\"ibadgns7mm4domrsgq4dkllgmvstcljrgfsteljygnrdoljsgbrtszbqgq3win3bg5sxqx3gnfwgkzc7onqv6zjsmvpw433oonugc4tfmrpwe6k7mfsg22lo\",\"operator\":\"CONTAINS\",\"value\":\"run\"}],\"supplementalConstraints\":[],\"group"
}

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",
   "type":"object",
   "properties":{
      "id":{
         "type":"string",
         "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      },
      "enabled":{
         "type":"boolean"
      },
      "alertType":{
         "enum":[
            "RATE_BASED",
            "RATE_BASED_WITH_GROUPS",
            "NEW_EVENT_TYPE"
         ]
      },
      "name":{
         "type":"string"
      },
      "hitCount":{
         "type":"integer",
         "minimum":0,
         "maximum": 100000
      },
      "searchPeriod":{
         "type":"integer",
         "minimum":60000
      },
      "searchInterval":{
         "type":"integer",
         "minimum":60000
      },
      "info":{
         "type":"string"
      },
      "emailEnabled":{
         "type":"boolean"
      },
      "emails":{
         "type":"string",
         "description":"A comma-separated list of email addresses"
      },
      "vcopsEnabled":{
         "type":"boolean"
      },
      "vcopsResourceName":{
         "type":"string"
      },
      "vcopsCriticality":{
         "enum":[
            "none",
            "information",
            "warning",
            "immediate",
            "critical"
         ]
      },
      "webhookEnabled":{
         "type":"boolean"
      },
      "webhookURLs":{
         "type":"string",
         "description":"A space-separated list of URLs"
      },
      "lastRanAt":{
         "type":"integer"
      },
      "lastRanAtString":{
         "type":"string"
      },
      "nextRunAt":{
         "type":"integer"
      },
      "nextRanAtString":{
         "type":"string"
      },
      "runCount":{
         "type":"integer"
      },
      "lastRunTime":{
         "type":"integer"
      },
      "totalRunTime":{
         "type":"integer"
      },
      "lastHitTimestamp":{
         "type":"integer"
      },
      "lastHitTimestampString":{
         "type":"string"
      },
      "ownerUuid":{
         "type":"string",
         "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      },
      "autoClearAlertAfterTimeout":{
         "type":"boolean"
      },
      "chartQuery":{
         "type":"string",
         "description":"A string of JSON format"
      }
   }
}

HTTP status code 400

Error trying to create an alert with incorrect parameters

Body: application/json

{
  "errorMessage": "The 'name' field is required"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-03/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/alerts/{alertId}

get
delete

get /api/v1/alerts/{alertId}

Get alert by UUID

This is a supported API.

Request

URI Parameters

alertId: required (string)
The UUID of the alert

Response

HTTP status code 200

Successfully retrieved the alert information

Body: application/json

{
  "id":"fc7bfcac-200c-4840-b349-b885338f03d1",
  "enabled":true,
  "emailEnabled":true,
  "vcopsEnabled":true,
  "alertType":"RATE_BASED",
  "name":"Hello Alert",
  "hitCount":2,
  "searchPeriod":300000,
  "searchInterval":60000,
  "emails":"email1@address.com, email2@address.com",
  "info":"This is an example of a rate based alert",
  "vcopsResourceName":"local-li-wdc-li1-04",
  "vcopsCriticality":"immediate",
  "lastRanAt": 1497017941283,
  "lastRanAtString": "2017-06-09 18:19:01.283 GMT+04:00",
  "nextRunAt": 1497018241283,
  "nextRunAtString": "2017-06-09 18:24:01.283 GMT+04:00",
  "runCount":7,
  "lastRunTime":800,
  "totalRunTime":946,
  "lastHitTimestamp": 1497017922145,
  "lastHitTimestampString": "2017-06-09 18:18:42.145 GMT+04:00",
  "ownerUuid":"1f024658-8b93-4f45-ae59-4657f96a5450",
  "webhookEnabled":true,
  "webhookURLs":"http://example.com/webhook1 http://example.com/webhook2",
  "autoClearAlertAfterTimeout":false,
  "chartQuery": "{\"query\":\"\",\"startTimeMillis\":1506417301511,\"endTimeMillis\":1506423141233,\"piqlFunctionGroups\":[{\"functions\":[{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false}],\"field\":null}],\"dateFilterPreset\":\"LAST_5_MINUTES\",\"shouldGroupByTime\":true,\"eventSortOrder\":\"DESC\",\"summarySortOrder\":\"DESC\",\"compareQueryOrderBy\":\"TREND\",\"compareQuerySortOrder\":\"DESC\",\"compareQueryOptions\":null,\"messageViewType\":\"EVENTS\",\"constraintToggle\":\"ALL\",\"piqlFunction\":{\"label\":\"Count\",\"value\":\"COUNT\",\"requiresField\":false,\"numericOnly\":false},\"piqlFunctionField\":null,\"fieldConstraints\":[{\"internalName\":\"ibadax3fpbpwm2lfnrsf643bl5stezk7onugc4tfmq000000\",\"operator\":\"CONTAINS\",\"value\":\"lang\"},{\"internalName\":\"ibadgns7mm4domrsgq4dkllgmvstcljrgfsteljygnrdoljsgbrtszbqgq3win3bg5sxqx3gnfwgkzc7onqv6zjsmvpw433oonugc4tfmrpwe6k7mfsg22lo\",\"operator\":\"CONTAINS\",\"value\":\"run\"}],\"supplementalConstraints\":[],\"group"
}

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",
   "type":"object",
   "properties":{
      "id":{
         "type":"string",
         "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      },
      "enabled":{
         "type":"boolean"
      },
      "alertType":{
         "enum":[
            "RATE_BASED",
            "RATE_BASED_WITH_GROUPS",
            "NEW_EVENT_TYPE"
         ]
      },
      "name":{
         "type":"string"
      },
      "hitCount":{
         "type":"integer",
         "minimum":0,
         "maximum": 100000
      },
      "searchPeriod":{
         "type":"integer",
         "minimum":60000
      },
      "searchInterval":{
         "type":"integer",
         "minimum":60000
      },
      "info":{
         "type":"string"
      },
      "emailEnabled":{
         "type":"boolean"
      },
      "emails":{
         "type":"string",
         "description":"A comma-separated list of email addresses"
      },
      "vcopsEnabled":{
         "type":"boolean"
      },
      "vcopsResourceName":{
         "type":"string"
      },
      "vcopsCriticality":{
         "enum":[
            "none",
            "information",
            "warning",
            "immediate",
            "critical"
         ]
      },
      "webhookEnabled":{
         "type":"boolean"
      },
      "webhookURLs":{
         "type":"string",
         "description":"A space-separated list of URLs"
      },
      "lastRanAt":{
         "type":"integer"
      },
      "lastRanAtString":{
         "type":"string"
      },
      "nextRunAt":{
         "type":"integer"
      },
      "nextRanAtString":{
         "type":"string"
      },
      "runCount":{
         "type":"integer"
      },
      "lastRunTime":{
         "type":"integer"
      },
      "totalRunTime":{
         "type":"integer"
      },
      "lastHitTimestamp":{
         "type":"integer"
      },
      "lastHitTimestampString":{
         "type":"string"
      },
      "ownerUuid":{
         "type":"string",
         "pattern":"^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
      },
      "autoClearAlertAfterTimeout":{
         "type":"boolean"
      },
      "chartQuery":{
         "type":"string",
         "description":"A string of JSON format"
      }
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

delete /api/v1/alerts/{alertId}

Delete alert by UUID

This is a supported API.

Request

URI Parameters

alertId: required (string)
The UUID of the alert

Response

HTTP status code 200

The alert is successfully deleted

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/alerts/{alertId}/history

get /api/v1/alerts/{alertId}/history

Get alert history records

This is a supported API.

Request

URI Parameters

alertId: required (string)
The UUID of the alert

Query Parameters

limit: (integer - default: 20 - minimum: 1 - maximum: 50)
The maximum number of records to retrieve.
fromTimestamp: (integer - default: 9223372036854776000 - maximum: 9223372036854776000)
The timestamp of the last record retrieved, this is the way to paginate when retrieving the records, no value if the first page is being retrieved

Response

HTTP status code 200

Successfully retrieved history records for specified alert

Body: application/json

[
  {
    "alertId": "2f8d5c71-177d-4625-b1f5-441908f870fa",
    "resultUrl": "https://192.168.8.101:9443/explorer?existingChartQuery=%7B%22query%22%3A%22%22%2C%22startTimeMillis%22%3A1467313663823%2C%22endTimeMillis%22%3A1467313724401%2C%22piqlFunctionGroups%22%3A%5B%7B%22functions%22%3A%5B%7B%22label%22%3A%22Count%22%2C%22value%22%3A%22COUNT%22%2C%22requiresField%22%3Afalse%2C%22numericOnly%22%3Afalse%7D%5D%2C%22field%22%3Anull%7D%5D%2C%22dateFilterPreset%22%3A%22CUSTOM%22%2C%22shouldGroupByTime%22%3Atrue%2C%22eventSortOrder%22%3A%22DESC%22%2C%22summarySortOrder%22%3A%22DESC%22%2C%22compareQueryOrderBy%22%3A%22TREND%22%2C%22compareQuerySortOrder%22%3A%22DESC%22%2C%22compareQueryOptions%22%3Anull%2C%22messageViewType%22%3A%22EVENTS%22%2C%22constraintToggle%22%3A%22ALL%22%2C%22piqlFunction%22%3A%7B%22label%22%3A%22Count%22%2C%22value%22%3A%22COUNT%22%2C%22requiresField%22%3Afalse%2C%22numericOnly%22%3Afalse%7D%2C%22piqlFunctionField%22%3Anull%2C%22fieldConstraints%22%3A%5B%5D%2C%22supplementalConstraints%22%3A%5B%5D%2C%22groupByFields%22%3A%5B%5D%2C%22extractedFields%22%3A%5B%5D%7D",
    "messages": [{
      "text": "hello world 3",
      "timestamp": 1496994835768,
      "timestampString": "2017-06-09 11:53:55.768 GMT+04:00",
      "fields": [{
        "name": "Field2",
        "content": "Content2_3"
      }, {
        "name": "__li_agent_id",
        "content": "ok"
      }, {
        "name": "__li_source_path",
        "content": "0:0:0:0:0:0:0:1"
      }, {
        "name": "Field1",
        "content": "Content1_3"
      }]
    }, {
      "text": "hello world 3",
      "timestamp": 1496994835134,
      "timestampString": "2017-06-09 11:53:55.134 GMT+04:00",
      "fields": [{
        "name": "Field2",
        "content": "Content2_3"
      }, {
        "name": "__li_agent_id",
        "content": "ok"
      }, {
        "name": "__li_source_path",
        "content": "0:0:0:0:0:0:0:1"
      }, {
        "name": "Field1",
        "content": "Content1_3"
      }]
    }],
    "acknowledged": false,
    "triggerTimestamp": 1496994860447,
    "triggerTimestampString": "2017-06-09 11:54:20.447 GMT+04:00"
  }, {
    "alertId": "2f8d5c71-177d-4625-b1f5-441908f870fa",
    "resultUrl": "https://192.168.8.101:9443/explorer?existingChartQuery=%7B%22query%22%3A%22%22%2C%22startTimeMillis%22%3A1467313603317%2C%22endTimeMillis%22%3A1467313664391%2C%22piqlFunctionGroups%22%3A%5B%7B%22functions%22%3A%5B%7B%22label%22%3A%22Count%22%2C%22value%22%3A%22COUNT%22%2C%22requiresField%22%3Afalse%2C%22numericOnly%22%3Afalse%7D%5D%2C%22field%22%3Anull%7D%5D%2C%22dateFilterPreset%22%3A%22CUSTOM%22%2C%22shouldGroupByTime%22%3Atrue%2C%22eventSortOrder%22%3A%22DESC%22%2C%22summarySortOrder%22%3A%22DESC%22%2C%22compareQueryOrderBy%22%3A%22TREND%22%2C%22compareQuerySortOrder%22%3A%22DESC%22%2C%22compareQueryOptions%22%3Anull%2C%22messageViewType%22%3A%22EVENTS%22%2C%22constraintToggle%22%3A%22ALL%22%2C%22piqlFunction%22%3A%7B%22label%22%3A%22Count%22%2C%22value%22%3A%22COUNT%22%2C%22requiresField%22%3Afalse%2C%22numericOnly%22%3Afalse%7D%2C%22piqlFunctionField%22%3Anull%2C%22fieldConstraints%22%3A%5B%5D%2C%22supplementalConstraints%22%3A%5B%5D%2C%22groupByFields%22%3A%5B%5D%2C%22extractedFields%22%3A%5B%5D%7D",
    "messages": [{
      "text": "hello world 3",
      "timestamp": 1496994480389,
      "timestampString": "2017-06-09 11:48:00.389 GMT+04:00",
      "fields": [{
        "name": "Field2",
        "content": "Content2_3"
      }, {
        "name": "__li_agent_id",
        "content": "ok"
      }, {
        "name": "__li_source_path",
        "content": "0:0:0:0:0:0:0:1"
      }, {
        "name": "Field1",
        "content": "Content1_3"
      }]
    }, {
      "text": "hello world 3",
      "timestamp": 1496994476883,
      "timestampString": "2017-06-09 11:47:56.883 GMT+04:00",
      "fields": [{
        "name": "Field2",
        "content": "Content2_3"
      }, {
        "name": "__li_agent_id",
        "content": "ok"
      }, {
        "name": "__li_source_path",
        "content": "0:0:0:0:0:0:0:1"
      }, {
        "name": "Field1",
        "content": "Content1_3"
      }]
    }],
    "acknowledged": false,
    "triggerTimestamp": 1496994560395,
    "triggerTimestampString": "2017-06-09 11:49:20.395 GMT+04:00"
  }
]

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",
   "type":"array",
   "items":{
      "type":"object",
      "properties":{
         "alertId":{
            "type":"string"
         },
         "resultUrl":{
            "type":"string"
         },
         "messages":{
            "type":"array",
            "items":{
               "type":"object",
               "properties":{
                  "text":{
                     "type":"string"
                  },
                  "timestamp":{
                     "type":"integer"
                  },
                  "timestampString":{
                     "type":"string"
                  },
                  "fields":{
                     "type":"array",
                     "items":{
                        "type":"object",
                        "properties":{
                           "name":{
                              "type":"string"
                           },
                           "content":{
                              "type":"string"
                           }
                        },
                        "required":[
                           "name",
                           "content"
                        ]
                     }
                  }
               },
               "required":[
                  "text",
                  "timestamp",
                  "timestampString",
                  "fields"
               ]
            }
         },
         "acknowledged":{
            "type":"boolean"
         },
         "triggerTimestamp":{
            "type":"integer"
         },
         "triggerTimestampString":{
            "type":"string"
         }
      },
      "required":[
         "alertId",
         "triggerTimestamp",
         "triggerTimestampString",
         "resultUrl",
         "messages",
         "acknowledged"
      ]
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/appliance

How to create a log bundle

Get the manifest ID for the log bundle: The GET api/vi/appliance/vm-support-bundles/manifests gets a list of all supported manifest IDs which also contains the ID to download the log bundle.

HTTP GET request:

GET /api/v1/appliance/vm-support-bundles/manifests
Authorization: Bearer {session_id}

HTTP Response: The response is a XML dataset containing the manifests information. Please find an example response below.

<xml>
  <manifestList>
    <manifest name="Agent" id="Agent:Agent" group="Agent" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Configuration" id="Core:Configuration" group="Core" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Configuration" id="Linux:Configuration" group="Linux" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Coredumps" id="Linux:Coredumps" group="Linux" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="DiskUsage" id="Core:DiskUsage" group="Core" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="HistoricLogs" id="Core:HistoricLogs" group="Core" defaultSelected="false" vmOnly="false"></manifest>
    <manifest name="LVM" id="Linux:LVM" group="Linux" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="LoadBalancer" id="Core:LoadBalancer" group="Core" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Logs" id="Core:Logs" group="Core" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Logs" id="Linux:Logs" group="Linux" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Proc" id="Linux:Proc" group="Linux" defaultSelected="true" vmOnly="false"></manifest>
  </manifestList>
</xml>

The manifest ID for getting the logs is Core:Logs which you will use in the POST request to download the log bundle.

Download the log bundle as an attachement: The POST api/vi/appliance/vm-support-bundles lets you create and download the log bundle as an attachement.
The optional "target" input parameter is specified with "ALL" to get log bundles from all nodes the cluster or "SINGLE" to get the log bundle from the local node. The default download target is "SINGLE".
The optional "manifests" is a string array of manifest IDs which are supported for creating and downloading the support bundle.
The API sends data as an attachment with content type set to application/octet-stream which is a binary file. Hence you will need to save the attachment as a file in a compressed format ( .tgz) and then can be accessed.
HTTP POST request:
```
POST /api/v1/appliance/vm-support-bundles
Authorization: Bearer {session_id}

Content-type: application/json
{
  "target": "SINGLE",
  "manifests": {
    "Core:Logs"
  }
}
```
HTTP Response:
HTTP/1.0 200 OK
```
Content-Type: application/octet-stream
Content-disposition: attachment; filename={filename}.tgz
```
Example HTTP curl POST request:
```
curl -#vkX POST --data '{"manifests": {"Core:Logs"}, "target": "ALL"}' https://{host-IP}:9543/api/v1/appliance/vm-support-bundles --header 'Authorization: Bearer {session-id}' -o  ~/downloadbundle.tgz
```

/api/v1/appliance/vm-support-bundles

post

post /api/v1/appliance/vm-support-bundles

Creates a new support bundle and returns it in a compressed format. Calling this API without specifying a manifests value retrieves the entire support bundle. Or, you can provide an array of manifest IDs you are interested in. manifests is a list of string manifest IDs. You can get the list of supported manifests with the GET /api/v1/vm-support-bundles/manifests API.

This is a supported API.

Request

Body: application/json

{
  "target": "SINGLE",
  "manifests": [
    "Core:Logs",
    "Linux:Coredumps"
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "target": {
      "enum": [ "ALL", "SINGLE" ],
      "default": "SINGLE"
    },
    "manifests": {
      "type": "array"
    }
  }
}

Response

HTTP status code 200

Successfully created a support bundle and sent the support bundle as an attachment. The response body contains the support bundle as binary data, which can be saved as a compressed file in .tgz format.

Body: application/octet-stream

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/appliance/vm-support-bundles/manifests

get /api/v1/appliance/vm-support-bundles/manifests

Gets a list of manifests of available support bundle content. The manifest list is returned in XML format.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the list of manifests.

Body: text/xml

<xml>
  <manifestList>
    <manifest name="Agent" id="Agent:Agent" group="Agent" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Configuration" id="Core:Configuration" group="Core" defaultSelected="true" vmOnly="false"></manifest>
    <manifest name="Logs" id="Core:Logs" group="Core" defaultSelected="true" vmOnly="false"></manifest>
  </manifestList>
</xml>

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/archiving/config

get
post

get /api/v1/archiving/config

TODO: add a description

This API is deprecated, and will be removed in a future release.

Response

HTTP status code 200

TODO: add a description

Headers

VMware-LI-API-Status: (string)
Indicates the life-cycle status of the API.
Example:
```
VMware-LI-API-Status: Deprecated
```
Warning: (string)
Additional information about the life-cycle status of the API.
Example:
```
Warning: 299 - "Deprecated: This API is deprecated" "Tue, 29 Mar 2016 21:54:10 GMT
```

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/archiving/config

TODO: add a description

This API is deprecated, and will be removed in a future release.

Request

Body: application/json

{
}

Schema:

{
  "$schema": "http://json-schema.org/draft-03/schema"
}

Response

HTTP status code 200

TODO: add a description

Headers

VMware-LI-API-Status: (string)
Indicates the life-cycle status of the API.
Example:
```
VMware-LI-API-Status: Deprecated
```
Warning: (string)
Additional information about the life-cycle status of the API.
Example:
```
Warning: 299 - "Deprecated: This API is deprecated" "Tue, 29 Mar 2016 21:54:10 GMT
```

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/auth-providers

get /api/v1/auth-providers

Returns a list of supported authentication providers. You can use these providers with the sessions API.

This is a supported API.

Response

HTTP status code 200

Body: application/json

{
  "providers": [
    "Local",
    "ActiveDirectory"
  ]
}

HTTP status code 503

Log Insight did not have its initial configuration set up yet. See /deployment/new.

Body: application/json

{
  "errorMessage": "LI server should be bootstrapped to process this API call"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

/api/v1/authgroups/{provider}/{domain}

/api/v1/cassandra/sstables

/api/v1/cassandra/sstables/{table}/nodes

/api/v1/ceip

Review and alter participation in the VMware Customer Experience Improvement Program. This provides us with information that helps us improve our products and services, fix problems and advise you on how best to deploy and use our products. For more information, see http://www.vmware.com/solutions/trustvmware/ceip.html

get /api/v1/ceip

Retrieve current Customer Experience Improvement Program participation status.

This is a supported API.

Response

HTTP status code 200

Customer Experience Improvement Program configuration was retrieved successfully.

Body: application/json

{
  "feedback" : true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "feedback": {
      "type" : "boolean"
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/ceip

Enable or disable participation in the Customer Experience Improvement Program.

This is a supported API.

Request

Body: application/json

{
  "feedback" : true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "feedback": {
      "type" : "boolean"
    }
  }
}

Response

HTTP status code 200

Customer Experience Improvement Program participation change was saved successfully.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/certificate

post
get

post /api/v1/certificate

Upload a custom certificate. Provide a PEM certificate in the request body.

This is a supported API.

Response

HTTP status code 200

Certificate successfully uploaded

Body: text/plain

Certificate successfully uploaded

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

get /api/v1/certificate

Retrieve certificate details.

This is a supported API.

Response

HTTP status code 200

Certificate information successfully retrieved

Body: application/json

[
  {
    "owner": {
        "country": "US",
        "stateProvince": "California",
        "locality": "Palo Alto",
        "organization": "VMware",
        "organizationUnit": "CMBU",
        "commonName": "vc-ops-slice-32"
    },
    "issuer": {
        "country": "US",
        "stateProvince": "California",
        "locality": "Palo Alto",
        "organization": "VMware",
        "organizationUnit": "CMBU",
        "commonName": "vc-ops-intermediate-32"
    },
    "serialNum": "20",
    "validityPeriod": {
        "from": "Thu May 07 16:25:24 UTC 2015",
        "until": "Wed May 06 16:25:24 UTC 2020"
    }
  }
]

Schema:

[
   "$schema":"http://json-schema.org/draft-04/schema",

   "type":"object",
   {
      "owner":{
         "type":"object",
         "properties":{
            "country":{
               "type":"string"
            },
            "stateProvince":{
               "type":"string"
            },
            "locality":{
               "type":"string"
            },
            "organization":{
               "type":"string"
            },
            "organizationUnit":{
               "type":"string"
            },
            "commonName":{
               "type":"string"
            }
         }
      }
      "issuer":{
         "type":"object",
         "properties":{
            "country":{
               "type":"string"
            },
            "stateProvince":{
               "type":"string"
            },
            "locality":{
               "type":"string"
            },
            "organization":{
               "type":"string"
            },
            "organizationUnit":{
               "type":"string"
            },
            "commonName":{
               "type":"string"
            }
         }
      }
      "serialNum":{
         "type":"string"
      }
      "validityPeriod":{
         "type":"object",
         "properties":{
            "from":{
               "type":"string"
            },
            "until":{
               "type":"string"
            }
        }
      }
   }
]

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/certificates

get /api/v1/certificates

Get the list of all trusted certificates

This is a supported API.

Response

HTTP status code 200

A list of all trusted certificates

Body: application/json

[
  {
    "thumbprint": "3324b8996f2b9f2366e412effdcdbf8987ef8d6b",
    "aliases": [
      "vROpsCertificate_some_vROps_Host_1",
      "vROpsCertificate_some_vROps_Host_2"
    ],
    "certificateInfo": {
      "owner": {
        "country": "US",
        "stateProvince": "California",
        "locality": "Palo Alto",
        "organization": "VMware",
        "organizationUnit": "CMBU",
        "commonName": "vc-ops-slice-32"
      },
      "issuer": {
        "country": "US",
        "stateProvince": "California",
        "locality": "Palo Alto",
        "organization": "VMware",
        "organizationUnit": "CMBU",
        "commonName": "vc-ops-intermediate-32"
      },
      "serialNum": "20",
      "validityPeriod": {
        "from": "Thu May 07 16:25:24 UTC 2015",
        "until": "Wed May 06 16:25:24 UTC 2020"
      }
    }
  },
  {
    "thumbprint": "4424b8996f2b9f2366e412effdcdbf8987ef8d6a",
    "aliases": [
      "vSphereCertificate_some_vc_host"
    ],
    "certificateInfo": {
      "owner": {
        "country": "US",
        "stateProvince": "California",
        "locality": "Palo Alto",
        "organization": "VMware",
        "organizationUnit": "CMBU",
        "commonName": "some_vc_host"
      },
      "issuer": {
        "country": "US",
        "stateProvince": "California",
        "locality": "Palo Alto",
        "organization": "VMware",
        "organizationUnit": "CMBU",
        "commonName": "CA"
      },
      "serialNum": "30",
      "validityPeriod": {
        "from": "Thu May 09 15:15:14 UTC 2018",
        "until": "Wed May 08 16:25:24 UTC 2021"
      }
    }
  }
]

Schema:

{
   "$schema": "http://json-schema.org/draft-04/schema",
   "type": "array",
   "items": {
      "type": "object",
      "properties": {
         "thumbprint": {
            "type": "string"
         },
         "aliases": {
            "type": "array",
            "items": {
               "type": "string"
            }
         },
         "certificateInfo": {
            "type": "object",
            "properties": {
               "owner": {
                  "type": "object",
                  "properties": {
                     "country": {
                        "type": "string"
                     },
                     "stateProvince": {
                        "type": "string"
                     },
                     "locality": {
                        "type": "string"
                     },
                     "organization": {
                        "type": "string"
                     },
                     "organizationUnit": {
                        "type": "string"
                     },
                     "commonName": {
                        "type": "string"
                     }
                  }
               },
               "issuer": {
                  "type": "object",
                  "properties": {
                     "country": {
                        "type": "string"
                     },
                     "stateProvince": {
                        "type": "string"
                     },
                     "locality": {
                        "type": "string"
                     },
                     "organization": {
                        "type": "string"
                     },
                     "organizationUnit": {
                        "type": "string"
                     },
                     "commonName": {
                        "type": "string"
                     }
                  }
               },
               "serialNum": {
                  "type": "string"
               },
               "validityPeriod": {
                  "type": "object",
                  "properties": {
                     "from": {
                        "type": "string"
                     },
                     "until": {
                        "type": "string"
                     }
                  }
               }
            }
         }
      }
  }

}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/certificates/{thumbprint}

get
delete

get /api/v1/certificates/{thumbprint}

Get the trusted certificate by thumbprint hashed in SHA-1 format

This is a supported API.

Request

URI Parameters

thumbprint: required (string)
The SHA-1 hashed thumbprint of trusted certificate

Response

HTTP status code 200

Successfully retrieved the trusted certificate information

Body: application/json

{
  "thumbprint": "3324b8996f2b9f2366e412effdcdbf8987ef8d6b",
  "aliases": [
    "vROpsCertificate_vc-ops-intermediate_1",
    "vROpsCertificate_vc-ops-intermediate_2"
  ],
  "certificateInfo": {
    "owner": {
      "country": "US",
      "stateProvince": "California",
      "locality": "Palo Alto",
      "organization": "VMware",
      "organizationUnit": "CMBU",
      "commonName": "vc-ops-slice-32"
    },
    "issuer": {
      "country": "US",
      "stateProvince": "California",
      "locality": "Palo Alto",
      "organization": "VMware",
      "organizationUnit": "CMBU",
      "commonName": "vc-ops-intermediate-32"
    },
    "serialNum": "20",
    "validityPeriod": {
      "from": "Thu May 07 16:25:24 UTC 2015",
      "until": "Wed May 06 16:25:24 UTC 2020"
    }
  }
}

Schema:

{
   "$schema": "http://json-schema.org/draft-04/schema",
   "type": "object",
   "properties": {
      "thumbprint": {
         "type": "string"
      },
      "aliases": {
         "type": "array",
         "items": {
            "type": "string"
         }
      },
      "certificateInfo": {
         "type": "object",
         "properties": {
            "owner": {
               "type": "object",
               "properties": {
                  "country": {
                     "type": "string"
                  },
                  "stateProvince": {
                     "type": "string"
                  },
                  "locality": {
                     "type": "string"
                  },
                  "organization": {
                     "type": "string"
                  },
                  "organizationUnit": {
                     "type": "string"
                  },
                  "commonName": {
                     "type": "string"
                  }
               }
            },
            "issuer": {
               "type": "object",
               "properties": {
                  "country": {
                     "type": "string"
                  },
                  "stateProvince": {
                     "type": "string"
                  },
                  "locality": {
                     "type": "string"
                  },
                  "organization": {
                     "type": "string"
                  },
                  "organizationUnit": {
                     "type": "string"
                  },
                  "commonName": {
                     "type": "string"
                  }
               }
            },
            "serialNum": {
               "type": "string"
            },
            "validityPeriod": {
               "type": "object",
               "properties": {
                  "from": {
                     "type": "string"
                  },
                  "until": {
                     "type": "string"
                  }
               }
            }
         }
      }
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Not found.

Body: text/plain

Not Found

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

delete /api/v1/certificates/{thumbprint}

Delete trusted certificate by thumbprint hashed in SHA-1 format

This is a supported API.

Request

URI Parameters

thumbprint: required (string)
The SHA-1 hashed thumbprint of trusted certificate

Response

HTTP status code 200

The trusted certificate is successfully deleted

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Not found.

Body: text/plain

Not Found

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

/api/v1/cluster

Configure Log Insight cluster. For more information see https://docs.vmware.com/en/vRealize-Log-Insight/index.html

/api/v1/cluster/vips

get
post

get /api/v1/cluster/vips

Retrieve the list of virtual IP addresses. Includes the IP and FQDN for each, along with current status.

This is a supported API.

Response

HTTP status code 200

The list of virtual IP addresses was retrieved successfully.

Body: application/json

{
  "vips": [
    {
      "uuid": "10.11.12.13",
      "ipAddress": "10.11.12.13",
      "fqdn": "test1.example.com",
      "tags": {
        "k1": "v1",
        "k2": "v2"
       },
      "status": "AVAILABLE"
    },
    {
      "uuid": "10.11.12.14",
      "ipAddress": "10.11.12.14",
      "fqdn": "",
      "tags": {
        "k3": "v3"
       },
      "status": "UNAVAILABLE"
    },
    {
      "uuid": "10.11.12.15",
      "ipAddress": "10.11.12.15",
      "fqdn": "test3.example.com",
      "tags": "key3=val3",
      "tags": {
         "k4": "v4",
         "k5": "v5"
       },
      "status": "UNKNOWN"
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "vips": {
      "description": "A list of all virtual IP addresses in the Log Insight cluster",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "uuid": {
            "type": "string"
          },
          "ipAddress": {
            "type": "string"
          },
          "fqdn": {
            "type": "string"
          },
          "tags": {
            "type": "object",
            "additionalProperties": {
              "type":"string"
            }
          },
          "status": {
            "enum": [
              "AVAILABLE",
              "UNAVAILABLE",
              "UNKNOWN"
            ]
          }
        }
      }
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/cluster/vips

Create new virtual IP addresses.

This is a supported API.

Request

Body: application/json

{
  "ipAddress": "10.11.12.13",
  "fqdn": "test1.example.com",
  "tags": {
    "k1": "v1",
    "k2": "v2"
   }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "ipAddress": {
      "type": "string"
    },
    "fqdn": {
      "type": "string"
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type":"string"
      }
    }
  },
  "required": [
    "ipAddress"
  ]
}

Response

HTTP status code 200

New virtual IP address was created successfully.

Body: application/json

{
  "uuid": "10.11.12.13"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string"
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 403

A virtual IP address with specified IP Address or FQDN already exists.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/cluster/vips/{uuid}

get /api/v1/cluster/vips/{uuid}

Retrieve the details of a virtual IP address. Includes the IP and FQDN for each, along with current status.

This is a supported API.

Request

URI Parameters

uuid: required (string)
This is a unique ID for Log Insight virtual IP address. It can be retrieved by 'GET /cluster/vips' call.

Response

HTTP status code 200

The virtual IP address details were retrieved successfully.

Body: application/json

{
  "uuid": "10.11.12.13",
  "ipAddress": "10.11.12.13",
  "fqdn": "test1.example.com",
  "tags": {
    "k1": "v1",
    "k2": "v2"
   },
  "status": "AVAILABLE"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "uuid": {
      "type": "string"
    },
    "ipAddress": {
      "type": "string"
    },
    "fqdn": {
      "type": "string"
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type":"string"
      }
    },
    "status": {
      "enum": [
        "AVAILABLE",
        "UNAVAILABLE",
        "UNKNOWN"
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

A virtual IP address with specified UUID was not found.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/cluster/vips/{uuid}

Update existing virtual IP address.

This is a supported API.

Request

URI Parameters

uuid: required (string)
This is a unique ID for Log Insight virtual IP address. It can be retrieved by 'GET /cluster/vips' call.

Body: application/json

{
  "fqdn": "test1.example.com",
  "tags": {
    "k1": "v1",
    "k2": "v2"
   }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "fqdn": {
      "type": "string"
    },
    "tags": {
      "type": "object",
      "additionalProperties": {
        "type":"string"
      }
    }
  }
}

Response

HTTP status code 200

The virtual IP address was updated successfully.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

A virtual IP address with the specified UUID was not found.

HTTP status code 409

VIP is currently used in a vSphere or vRealize Operations Integration.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

delete /api/v1/cluster/vips/{uuid}

Delete specified virtual IP address.

This is a supported API.

Request

URI Parameters

uuid: required (string)
This is a unique ID for Log Insight virtual IP address. It can be retrieved by 'GET /cluster/vips' call.

Response

HTTP status code 200

The specified Virtual IP address was deleted successfully.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

A virtual IP address with the specified UUID was not found.

HTTP status code 409

VIP is currently used in a vSphere or vRealize Operations Integration.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/config

/api/v1/config/data

get
post

get /api/v1/config/data

Export LogInsight configuration into a file, which can be used for configuring a fresh Log Insight setup.

Exported configuration includes the following information about the LogInsight cluster:

General configuration (CEIP, System notification recipients, etc.)
NTP configuration
Event forwarder configuration
SMTP configuration
Archiving settings
Agents groups configuration

Exported configuration does NOT include the following information:

Cluster configuration (e.g. the number of nodes, VIP configuration, etc.) Exporting VIP configuration might result in multiple clusters having the same VIP, which would cause isues with ingestion, event forwarding, etc.
Hosts information
Patterns and fields extracted during machine learning
Agents configuration
Local users. Local users aren't migrated for security reasons so that passwords are exposed in the exported configuration file.
Active Directory and vIDM configurations aren't migrated for security reasons, as exporting these configurations would expose the passwords.
Content packs and user content, such as dashboards, alerts, etc.
SSL configuration
vSphere integration configuration isn't migrated for security reasons, as exporting this configuration would expose the passwords.
vROps integration configuration isn't migrated for security reasons, as exporting this configuration would expose the passwords.

This is a supported API.

Response

HTTP status code 200

Returns a file containing the exported configuration.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/config/data

Import an exported Log Insight configuration.

The following configuration can be imported based on the provided parameters:

General configuration (CEIP, System notification recipients, etc.)
NTP configuration
Event forwarder configuration
SMTP configuration
Archiving settings
Agents groups configuration

Imported configuration does NOT include the following information:

Cluster configuration (e.g. the number of nodes, VIP configuration, etc.) Exporting VIP configuration might result in multiple clusters having the same VIP, which would cause isues with ingestion, event forwarding, etc.
Hosts information
Patterns and fields extracted during machine learning
Agents configuration
Local users. Local users aren't migrated for security reasons so that passwords are exposed in the exported configuration file.
Active Directory and vIDM configurations aren't migrated for security reasons, as exporting these configurations would expose the passwords.
Content packs and user content, such as dashboards, alerts, etc. Content migration can be addressed with separate APIs designed to export and import content packs and user content.
SSL configuration
vSphere integration configuration isn't migrated for security reasons, as exporting this configuration would expose the passwords.
vROps integration configuration isn't migrated for security reasons, as exporting this configuration would expose the passwords.

Configuration import process consists of two steps:

The exported configuration file should be uploaded as binary data with the "Content-Type: applications/octet-stream" header.
Once the file is uploaded, the configurations can be applied by setting the "Content-Type: applications/json" header and providing the items to exclude in the JSON body.

This is a supported API.

Request

Body: application/json

{
  "includeNtpConfig": "false",
  "includeAgentsGroups": "false"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "includeGeneralConfig": {
      "type": "boolean"
    },
    "includeNtpConfig": {
      "type": "boolean"
    },
    "includeEventForwarderConfig": {
      "type": "boolean"
    },
    "includeSmtpConfig": {
      "type": "boolean"
    },
    "includeArchivingConfig": {
      "type": "boolean"
    },
    "includeAgentsGroups": {
      "type": "boolean"
    }
  }
}

Response

HTTP status code 200

Imports the configuration file and applies the selected configuration.

Body: application/json

{
    "GeneralConfiguration": "Successfully configured.",
    "Time": "Successfully configured.",
    "EventForwarder": "Successfully configured.",
    "SMTP": "Successfully configured.",
    "Archiving": "Successfully configured.",
    "includeAgentsGroups": "Successfully configured."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "GeneralConfiguration": {
    "type": "string"
  },
  "Time": {
    "type": "string"
  },
  "EventForwarder": {
    "type": "string"
  },
  "SMTP": {
    "type": "string"
  },
  "Archiving": {
    "type": "string"
  },
  "SSL": {
    "type": "string"
  },
  "includeAgentsGroups": {
    "type": "string"
  }
}

HTTP status code 202

Applying the imported configuration has partially succeeded.

Body: application/json

{
    "GeneralConfiguration": "Successfully configured.",
    "Time": "Successfully configured.",
    "EventForwarder": "Successfully configured.",
    "SMTP": "Successfully configured.",
    "Archiving": "Successfully configured.",
    "includeAgentsGroups": "Successfully configured."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "GeneralConfiguration": {
    "type": "string"
  },
  "Time": {
    "type": "string"
  },
  "EventForwarder": {
    "type": "string"
  },
  "SMTP": {
    "type": "string"
  },
  "Archiving": {
    "type": "string"
  },
  "SSL": {
    "type": "string"
  },
  "includeAgentsGroups": {
    "type": "string"
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/deployment

About the Deployment API

The Deployment API lets you create a new cluster or join an existing cluster on newly installed Log Insight cluster. This is a one time setup process.

New Deployment: To create a new deployment, issue /api/v1/deployment/new. The server where this api is issued, becomes either the first server or the master server of a new cluster where you can add other server nodes or a single standalone server.

HTTP POST Request for new deployment:

   POST /api/v1/deployment/new
   Content-type: application/json

   {
     "user": {
       "userName": "admin",
       "password": "Password123!",
       "email": "admin@example.com"
     }
   }

HTTP Response:

   HTTP/1.0 200 OK

How to create a cluster

Create a new cluster: Issue a new deployment api request as mentioned above

Add other server nodes to a cluster: Issue /api/v1/deployment/join in newly installed Log Insight servers to add them to created cluster above.

HTTP POST request:

POST /api/v1/deployment/join
Content-type: application/json

{
  "masterFQDN": "li.example.com"
}

HTTP Response:

HTTP/1.0 200 OK
Content-Type: application/json; charset=utf-8
{
  "masterAddress": "10.0.0.123",
  "workerAddress": "10.0.0.124",
  "workerPort": 16520,
  "workerToken": "85867eeb-3461-4dff-9294-e60f69467ab1",
  "masterUiPort": 9099
}

Master approve of the join request: Once the join request is issued by a worker node to a master node of the cluster, then the master needs to approve the join. This is done by issue of /api/v1/deployment/approve api.

HTTP POST request:

POST /api/v1/deployment/approve
Authorization: Bearer {session_id}
Content-type: application/json

{
  "workerAddress": "10.0.0.124",
  "workerPort": 16520,
  "workerToken": "85867eeb-3461-4dff-9294-e60f69467ab1",
  "approved": true
}

HTTP Response:

 HTTP/1.0 200 OK
 Content-Type: application/json; charset=utf-8

 {
   "masterHostname": "10.0.0.123",
   "clusterNode": {
     "token": "869a1b6d-a3e8-493f-b280-adb60f106006",
     "hostname": "10.0.0.124",
     "status": "Connected",
     "fullVersion": "2.6.3-0"
   }
 }

/api/v1/deployment/approve

post

post /api/v1/deployment/approve

Approves a request to join a server to a Log Insight cluster.

The API can only be used to bootstrap a new node. during the bootstrap phase. Once a Log Insight cluster has been created or joined, the bootstrap interfaces are no longer available.

This is a supported API.

Request

Body: application/json

{
  "workerAddress": "10.0.0.124",
  "workerPort": 16520,
  "workerToken": "fcfeab92-3346-460f-bd9e-20799437a475",
  "approved": true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "workerAddress": {
      "type": "string"
    },
    "workerPort": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "exclusiveMaximum": false,
      "exclusiveMinimum": false
    },
    "workerToken": {
      "type": "string"
    },
    "approved": {
      "type": "boolean"
    }
  },
  "required": [
    "workerAddress",
    "workerPort",
    "workerToken",
    "approved"
  ]
}

Response

HTTP status code 200

The request to join the cluster was successfully approved or denied.

Body: application/json

{
  "masterHostname": "10.0.0.123",
  "clusterNode": {
    "token": "2bd24a67-ac4c-4ca5-a54a-7a8e215c4e8d",
    "hostname": "10.0.0.124",
    "status": "Connected",
    "fullVersion": "4.0.0-1234567"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "masterHostname": {
      "type": "string"
    },
    "clusterNode": {
      "id": "#clusterNode",
      "properties": {
        "token": {
          "type": "string"
        },
        "hostname": {
          "type": "string"
        },
        "status": {
          "enum": [
            "Connected",
            "Disconnected",
            "Maintenance"
          ]
        },
        "fullVersion": {
          "type": "string"
        }
      },
      "required": [
        "token",
        "hostname",
        "status",
        "fullVersion"
      ]
    }
  },
  "required": [
    "masterHostname",
    "clusterNode"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 403

This interface is not available after the Log Insight server has been configured.

Body: application/json

{
  "errorMessage": "This call isn't allowed after the LI server is bootstrapped"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/deployment/join

post

post /api/v1/deployment/join

Joins a newly installed Log Insight server to an existing cluster. When setting up a cluster with multiple servers, call the POST /api/v1/deployment/new API on the first server. Then call this API on the other servers to get them to join the cluster.

The API can only be used to bootstrap a new node. during the bootstrap phase. Once a Log Insight cluster has been created or joined, the bootstrap interfaces are no longer available.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "masterFQDN": "li-01.example.com"
}

Schema:

{
  "title": "Join existing deployment",
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "masterFQDN": {
      "type": "string"
    },
    "masterPort": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "exclusiveMaximum": false,
      "exclusiveMinimum": false
    }
  },
  "required": [
    "masterFQDN"
  ]
}

Response

HTTP status code 200

Successfully submitted a request to join the cluster.

Body: application/json

{
  "masterAddress": "10.0.0.123",
  "masterUiPort": 80,
  "workerAddress": "10.0.0.124",
  "workerPort": 16520,
  "workerToken": "0ae94cb9-550a-4c01-85b9-3b7095e92321"
}

Schema:

{
  "title": "Joined existing deployment",
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "masterAddress": {
      "type": "string"
    },
    "workerAddress": {
      "type": "string"
    },
    "workerPort": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "exclusiveMaximum": false,
      "exclusiveMinimum": false
    },
    "workerToken": {
      "type": "string"
    },
    "masterUiPort": {
      "type": "integer",
      "minimum": 1,
      "maximum": 65535,
      "exclusiveMaximum": false,
      "exclusiveMinimum": false
    }
  },
  "required": [
    "masterAddress",
    "workerAddress",
    "workerPort",
    "workerToken",
    "masterUiPort"
  ]
}

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 403

This interface is not available after the Log Insight server has been configured.

Body: application/json

{
  "errorMessage": "This call isn't allowed after the LI server is bootstrapped"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

/api/v1/deployment/new

post

post /api/v1/deployment/new

Configures a newly installed Log Insight server as the first member of a new cluster. When setting up a single stand-alone server, call this API to initialize the server. When setting up a cluster with multiple servers, call this API on the first server to create a cluster. Then call POST /api/v1/deployment/join on the other servers to get them to join the cluster.

The API can only be used to bootstrap a new node. during the bootstrap phase. Once a Log Insight cluster has been created or joined, the bootstrap interfaces are no longer available.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "user": {
    "username": "admin",
    "password": "secret",
    "email": "admin@example.com"
  }
}

Schema:

{
  "title": "Administrator Account",
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "user": {
      "id": "#adminuser",
      "properties": {
        "userName": {
          "type": "string"
        },
        "password": {
          "type": "string"
        },
        "email": {
          "type": "string"
        }
      },
      "required": [
        "username",
        "password"
      ]
    }
  },
  "required": [
    "user"
  ]
}

Response

HTTP status code 200

Successfully configured the server.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 403

This interface is not available after the Log Insight server has been configured.

Body: application/json

{
  "errorMessage": "This call isn't allowed after the LI server is bootstrapped"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

/api/v1/deployment/waitUntilStarted

post

post /api/v1/deployment/waitUntilStarted

Waits until the server starts. This can take several minutes to complete.

This is a supported API.

Response

HTTP status code 200

The server started successfully.

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

/api/v1/events

GET /api/v1/events
User-Agent: YourAppName/1.0
Authorization: Bearer 80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL

The response looks like this:

HTTP/1.1 200 OK

{
  "complete": true,
  "duration": 12,
  "events": [
    {
      "text": "[2016-03-31 14:07:25.942-0700] [vpxa] ...",
      "timestamp": 1459458445942,
      "fields": [
        {
          "name": "source",
          "content": "10.0.0.123"
        },
        {
          "name": "event_type",
          "content": "v4_4eca2033"
        },
        {
          "name": "appname",
          "startPosition": 32,
          "length": 4
        }
      ]
    },
    {
      "text": "[2016-03-31 14:07:25.698-0700] [hostd] ...",
      "timestamp": 1459458445698,
      "fields": [
        {
          "name": "source",
          "content": "10.0.0.234"
        },
        {
          "name": "event_type",
          "content": "v4_a7ce5b6a"
        },
        {
          "name": "appname",
          "startPosition": 32,
          "length": 5
        }
      ]
    }
  ]
}

If you want a simple response:

GET /api/v1/events?view=SIMPLE
User-Agent: YourAppName/1.0
Authorization: Bearer 80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL

The response looks like this:

HTTP/1.1 200 OK

{
  "complete": true,
  "duration": 12,
  "results": [
    {
      "text": "[2016-03-31 14:07:25.942-0700] [vpxa] ...",
      "timestamp": 1459458445942,
      "source": "10.0.0.123",
      "event_type": "v4_4eca2033",
      "appname": "vpxa"
    },
    {
      "text": "[2016-03-31 14:07:25.698-0700] [hostd] ...",
      "timestamp": 1459458445698,
      "source": "10.0.0.234",
      "event_type": "v4_a7ce5b6a",
      "appname": "hostd"
    }
  ]
}

complete indicates whether all matching events were returned (true), or only some of them due to timeout expiration or other errors (false).
duration is the time required to compute the results, in milliseconds.
events lists events that match the query. See the GET /api/v1/events API for details.
results lists events that match in query in a simple flatmap format. See the GET /api/v1/events API for details.
if the query response was incomplete, then warnings is an array that explains the problems. Each problem has a string description and a numeric code. For example, description TRUNCATED_GROUPS (code 9) is returned when a GROUP BY query response is approximated because there are too many groups. Another example is description TIMEOUT (code 128) which indicates that they query duration exceeded the request timeout. When the query times out, the warning also contains a progress value which indicates the fraction of data that was processed when the timeout occurred.

Query parameters for events queries

order-by-direction (ASC or DESC).
Specify the order in which events are returned: either ascending by time (oldest first), or descending by time (newest first)
limit: (integer - default: 100)
The maximum number of events to retrieve.
timeout: (integer - default: 30000)
The time to wait for a response. If the complete result is not available within that time, partial result is returned and the complete flag is set to false.
view: (DEFAULT or SIMPLE).
Specify the query results format in the response. DEFAULT returns a list of events in the ingestion ready format; SIMPLE returns a list of events in user-friendly flat map format.
content-pack-fields: (string)
The namespace of a content pack to take fields from. For example, specifying content-pack-fields=com.vmware.vsphere will include fields from the vSphere content pack. If provided, fields defined in the given content-pack are returned in the response, in addition to static fields. Specify this parameter more than once to extract fields from several content packs. If this parameter is not specified, then only static fields are returned in the response payload.

Example:

GET /api/v1/events?limit=1000&timeout=15000

Querying for groups of events

To query for groups of events, issue the GET /api/v1/aggregated-events API.

GET /api/v1/aggregated-events
User-Agent: YourAppName/1.0
Authorization: Bearer 80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL

The response looks like:

HTTP/1.1 200 OK

{
  "complete": true,
  "duration": 9,
  "bins": [
    {
      "minTimestamp": 1459458460000,
      "maxTimestamp": 1459458464999,
      "value": 2
    },
    {
      "minTimestamp": 1459458455000,
      "maxTimestamp": 1459458459999,
      "value": 14
    }
  ]
}

To query for groups of events with multiple aggregation function and additional group-bys:

GET /api/v1/aggregated-events?aggregation-function=COUNT&aggregation-function=UCOUNT&aggregation-field=appname&group-by-field=event_type&group-by-field=hostname
User-Agent: YourAppName/1.0
Authorization: Bearer 80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL

The response looks like:

HTTP/1.1 200 OK

{
  "complete": true,
  "duration": 9,
  "bins": [
    {
      "minTimestamp": 1459458460000,
      "maxTimestamp": 1459458464999,
      "keys": ["v4_4a6fdf4b", "strata-esx4.eng.vmware.com"],
      "values": [2, 1]
    },
    {
      "minTimestamp": 1459458455000,
      "maxTimestamp": 1459458459999,
      "keys": ["v4_4a6fdf4b", "strata-esx5.eng.vmware.com"],
      "values": [12, 1]
    }
  ]
}

add view=SIMPLE for a user-friendly table like response:

HTTP/1.1 200 OK

{
  "complete": true,
  "duration": 9,
  "results": [
    {
      "minTimestamp": 1459458460000,
      "maxTimestamp": 1459458464999,
      "event_type": "v4_4a6fdf4b",
      "hostname": "strata-esx4.eng.vmware.com",
      "COUNT(event)": 2,
      "UCOUNT(event.appname)": 1
    },
    {
      "minTimestamp": 1459458455000,
      "maxTimestamp": 1459458459999,
      "event_type": "v4_4a6fdf4b",
      "hostname": "strata-esx5.eng.vmware.com",
      "COUNT(event)": 12,
      "UCOUNT(event.appname)": 1
    }
  ]
}

Another example is to query for both count and a sample event for each event type in a simple format, which is the same query as the event type tab in the UI:

GET /api/v1/aggregated-events?bin-width=all&view=simple&aggregation-function=COUNT&aggregation-function=SAMPLE&group-by-field=event_type
User-Agent: YourAppName/1.0
Authorization: Bearer 80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL

The response looks like:

HTTP/1.1 200 OK

{
  "complete": true,
  "duration": 90,
  "results": [
    {
      "minTimestamp": 0,
      "maxTimestamp": 9223372036828799999,
      "event_type": "v4_4a6fdf4b",
      "COUNT(event)": 50,
      "SAMPLE(event)": {
            "text": "[2013-10-05T11:54:02.265Z] ...",
            "timestamp": 1472006615653,
            "appname": "Vpxa",
            "event_type": "v4_df1bc800",
            "hostname": "li-qe-esx5.vmware.com",
            "source": "127.0.0.1"
      }
    },
    {
      "minTimestamp": 0,
      "maxTimestamp": 9223372036828799999,
      "event_type": "v4_dc0c9904",
      "COUNT(event)": 100,
      "SAMPLE(event)": {
            "text": "[2014-05-06 14:35:39.723-0700] ...",
            "timestamp": 1472006611297,
            "event_type": "v4_dc0c9904",
            "source": "127.0.0.1"
      }
    }
  ]
}

complete indicates whether all matching events were returned (true), or if only some of them where, because the timeout expired (false)
duration is the time required to compute the results, in milliseconds.
bins lists bins, or groups, of events. See the GET /api/v1/aggregated-events API for details.
results lists results that match in query in a simple flatmap format. See the GET /api/v1/aggregated-events API for details.

Query parameters for event group queries

Queries for groups of events can use the same query parameters as event queries, including limit, timeout, view and content-pack-fields. The can also use the following parameters:

bin-width (integer - default: 5000)
The time-span of time range bins, in milliseconds. A special "all" or "Infinity" bin-width will effectively group by over the entire time range.

Aggregation clause parameters:

Specify aggregation functions. With none of those options, the default behavior is aggregation of number events in each group.

aggregation-function [primary key] (string - default: COUNT):
The aggregation function to use. One of the following values:
- COUNT: The count of the events in each bin is returned
- SAMPLE: An arbitrary event from each bin is returned
- UCOUNT: The count of unique values in the bin
- MIN: The minimum value in the bin
- MAX: The maximum value in the bin
- SUM: The sum of the values in the bin
- STDDEV: The standard deviation of the values in the bin
- VARIANCE: The variance of the values in the bin
aggregation-field (string): the field to aggregate. This parameter is required for all aggregation functions, except COUNT and SAMPLE. It is not supported for COUNT and SAMPLE.

Group by clause parameters:

Specify additional GROUP BY fields. Use subsequent bin-width or bins query parameters to specify bin boundaries. If neither is specified then each individual value of the field is assigned to its own bucket.

group-by-field [primary key] (string): additional GROUP BY fields.
bins (string): custom bin boundaries for the current group by clause. For example, use bins=10,100,500 to specify a specific set of bin boundaries.
bin-width (integer): the width of the bins for the current group by clause. For example, use bin-width=10000 to specify fixed-width bins.

Order by clause parameters:

Specify sorting orders. With none of these options, the default behavior is a descending sort by each bin's time range. But if any options are specified, then this default is overridden by the given options. To restore the default behavior, use order-by-field=timestamp.

order-by-function [primary key] (string): sort on any aggregation function except SAMPLE or NONE.
order-by-field (string): sort on a field with or without aggregation function or on event itself with COUNT function.
order-by-direction (ASC or DESC): specify the sorting direction of the current order by clause.
Notes: The clause primary key order-by-function is always required, if no aggreagation is needed, order-by-function=NONE order-by-field is required for all functions, with the exception of COUNT. For example:
- order-by-function=NONE&order-by-field=hostname sorts on alphabetical order of hostname field
- order-by-function=COUNT&order-by-function=UCOUNT&order-by-field=hostname&order-by-direction=ASC sorts by a composite keys: first by the number of events (largest first) and then by the number of distinct hostnames (smallest first).
For large datasets with more groups than the limit query parameter, order-by options can change the returned data, as the groups that are returned depend on the sorting key.

Specifying constraints

Constraints Example 1

You can specify what events to return by adding constraints to the API's path. For example, to list events containing the word 'ERROR':

GET /api/v1/events/text/CONTAINS%20ERROR

Let's break this apart:

The GET /api/v1/events/ part is the events query API.
The text/ portion indicates that only events with a specific text value should be retrieved.
The CONTAINS%20ERROR tells the query API that only text values containing the word 'ERROR' should be considered:
- CONTAINS is an operator that works on string fields such as text.
- %20 is a URL-encoded space character.
- ERROR is the word that the CONTAINS operator is applied to.

Constraints Example 2

Here's another example. This one lists events with a timestamp later than January 1 2016 UTC:

GET /api/v1/events/timestamp/%3E1451606400000

The breakdown is:

The GET /api/v1/events/ part is the events query API.
The timestamp/ portion indicates that only events with specific timestamp values should be retrieved.
The %3E1451606400000 part has two components"
- %3E is the URL encoding of the > character.
- 1451606400000 is the January 1 2016 date represented as milliseconds since midnight January 1 1970 UTC.

Constraints Example 3

You can compose several constraints together. For example, to list all events containing the word 'ERROR' and with any timestamp, try:

GET /api/v1/events/timestamp/%3E0/text/CONTAINS%20ERROR

Constraints Reference

The general format of an events query follows the form of /api/v1/events/constraint/constraint/.../constraint.

Each constraint has the form field/operator value or field/operator, URL-encoded as appropriate.

field is one of:
- The text or timestamp special fields.
- Any static field.
- A field defined in a content pack. In that case, refer to it with these syntax content-pack-namespace:field-name. For example: com.vmware.vsphere:vmw_user.
operator is one of:
- The numeric operators apply to fields that contain numbers:
  - = is the equals operator. The URL encoding is %3D. EQ is an alternate form of this operator.
```
GET /api/v1/events/timestamp/%3D1451606400
```
  - != is the not-equals operator. The URL encoding is %21%3D. NE is an alternate form of this operator.
```
GET /api/v1/events/timestamp/%21%3D1451606400
```
  - < is the less-than operator. The URL encoding is %3C. LT is an alternate form of this operator.
```
GET /api/v1/events/timestamp/%3C1451606400
```
  - <= is the less-than-or-equals operator. The URL encoding is %3C%3D. LE is an alternate form of this operator.
```
GET /api/v1/events/timestamp/%3C%3D1451606400
```
  - > is the larger-than operator. The URL encoding is %3E. GT is an alternate form of this operator.
```
GET /api/v1/events/timestamp/%3E1451606400
```
  - >= is the larger-than-or-equals operator. The URL encoding is %3E%3D. GE is an alternate form of this operator.
```
GET /api/v1/events/timestamp/%3E%3D1451606400
```
- The string operators are case-insensitive filters that apply to text fields:
  - CONTAINS checks if a text field contains a value. Note that if the value contains whitespace, it is treated as a phrase: the tokens must occur in the specified order without any intervening tokens (although punctuation is permitted). For example, the following request retrieves events like "[ERROR] File not found", but not "Error: Invalid file" or "Critical file error".
```
GET /api/v1/events/text/CONTAINS%20error%20file
```
  - NOT_CONTAINS checks if a text field does not contain a value.
```
GET /api/v1/events/text/NOT_CONTAINS%20error%20file
```
  - HAS checks if a field contains every white-space delimited token in the value. The tokens may occur in any order, with any intervening tokens. For example, the following request retrieves events like "[ERROR] File not found" as well as "Error: Invalid file" and "Critical file error".
```
GET /api/v1/events/text/HAS%20error%20file
```
  - NOT_HAS checks if a text field does not contain all of the tokens in the value.
```
GET /api/v1/events/text/NOT_HAS%20error%20file
```
  - =~ checks if a text field matches a regular expression. The URL encoding is %3D%7E. MATCHES_REGEX is an alternate form of this operator.
```
GET /api/v1/events/text/%3D%7EERROR
```
  - !=~ checks if a text field does not match a regular expression. The URL encoding is %21%3D%7E. NOT_MATCHES_REGEX is an alternate form of this operator.
```
GET /api/v1/events/text/%21%3D%7EERROR
```
- The LAST operator selects a time range in milliseconds relative to the current time. It only applies to the timestamp field. For example, the following query selects events from the last minute.
```
GET /api/v1/events/timestamp/LAST%2060000
```
- The EXISTS operator limits the results to events that contain a specific field.

URL encoding

All queries have to be URL-encoded. It's easy to think about a query of the form GET /api/v1/events/timestamp/>0. However, for the query to work, the '>' character has to be URL encoded, e.g. GET /api/v1/events/timestamp/%3E0.

Regular expressions in constraints

By default, the MATCHES_REGEX and NOT_MATCHES_REGEX operators are disabled. Constraints based on regular expression are computationally expensive and don't benefit from indexes. Queries using regex constraints should also leverage a non-regex constraint to short-circuit evaluation. To enable these operators for all users, set the internal configuration option config.api-server.regex-query-enabled to true using the steps in https://kb.vmware.com/kb/2123058:

<config>
 <api-server>
  <regex-query-enabled value="true"/>
 </api-server>
</config>

Combining constraints

AND between conditions

When multiple constraints are included, only events that match all the constraints are retrieved. For example, the following retrieves events that both contain the text 'ERROR' and have a size field with a size larger than 10 (make sure to URL-encode first):

GET /api/v1/events/text/CONTAINS ERROR/size/>10

OR between conditions

When multiple instances of the same operator and the same field are included, events that match any of the constraints are retrieved. For example, the following retrieves events that contain either 'WARNING' or 'ERROR'.

GET /api/v1/events/text/CONTAINS WARNING/text/CONTAINS ERROR

Note: Multiple constraints of the same field but different operators will still be combined with "AND". For example, the following retrieves events that have timestamp >= 147500388000 AND timestamp <= 147500590000

GET /api/v1/events/timestamp/>=147500388000/timestamp/<=147500590000

Negation

A negated version of each operator is available. For example, < and >= or CONTAINS and NOT_CONTAINS.

/api/v1/events/flush

/api/v1/events/ingest

/api/v1/events/ingest/{agentId}

post

post /api/v1/events/ingest/{agentId}

Ingest and index new log messages contained in the body.

Can contain a maximum of 4MB of JSON in a single submission with 16KB in a single text field. Batch-submission of multiple adjacent events is more efficient than a seperate POST for each.

Each event can contain a list of key-value fields. Values are expressed as strings or as character ranges in the event text.

The timestamp of an event is optional, and expressed as milliseconds-since-epoch UTC. If the submission is authenticated, the timestamp field is trusted. Unauthenticated event submissions have their time clamped to within 10 minutes of the server's current time.

#% config.api-server.max-tolerated-client-time-drift=600000

This is a supported API.

Request

URI Parameters

agentId: required (string)
A unique identifier for the event source. Specify a BIOS UUID, a stored UUID4 or other stable identifier. If no suitible identifier exists, can be safely set to 0.
Example:
```
aexample-uuid-4b7a-8b09-fbfac4b46fd9
```

Body: application/json

{
  "events": [{
    "fields": [
      {"name": "StaticField", "content": "Security"},
      {"name": "PositionalField", "startPosition": 6, "length": 7}
    ],
    "text": "A new process has been created.",
    "timestamp": 1396622879241
  }]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "AnonymousField": {
      "type": "object",
      "title": "Field content provided directly",
      "properties": {
        "name": {
          "type": "string"
        },
        "content": {
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "PositionalField": {
      "type": "object",
      "title": "Field content from range in event text",
      "properties": {
        "name": {
          "type": "string"
        },
        "startPosition": {
          "type": "integer"
        },
        "length": {
          "type": "integer"
        }
      },
      "additionalProperties": false
    },
    "ContentlessField": {
      "type": "object",
      "title": "Field content from range in event text",
      "properties": {
        "name": {
          "type": "string"
        }
      },
      "additionalProperties": false
    }
  },
  "id": "IngestLogEvents",
  "type": "object",
  "properties": {
    "events": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "fields": {
            "type": "array",
            "items": {
              "oneOf": [
                {
                  "$ref": "#/definitions/AnonymousField"
                },
                {
                  "$ref": "#/definitions/PositionalField"
                },
                {
                  "$ref": "#/definitions/ContentlessField"
                }
              ]
            }
          },
          "text": {
            "type": "string"
          },
          "timestamp": {
            "type": "integer"
          }
        }
      }
    }
  },
  "required": [
    "events"
  ]
}

Response

HTTP status code 200

Successfully ingested new log events.

Body: application/json

{
  "ingested": 1,
  "message": "events ingested",
  "status": "ok"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "ingested": {
      "type": "integer"
    },
    "message": {
      "type": "string"
    },
    "status": {
      "type": "string"
    }
  },
  "required": [
    "ingested",
    "message",
    "status"
  ]
}

HTTP status code 400

The body contained a zero-length list of events.

Body: application/json

{
  "errorMessage": "Missing events"
}

HTTP status code 401

The request was refused because it included invalid authentication credentials. The Authorization header was present, but it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions, or make an unauthenticated request without the Authorization header.

Body: text/plain

Login Timeout

HTTP status code 503

The server is overloaded and unable to handle this ingestion request. The Retry-After header contains a suggested retry time in seconds.

Security

This API can be used with or without authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/events/{+path}

get /api/v1/events/{+path}

Queries Log Insight for events.

This is a supported API.

Request

URI Parameters

+path: required (string)
Specifies constraints on the events to retrieve. See the specifying constraints section of /events for details.

Query Parameters

limit: (integer - default: 100)
The maximum number of events to retrieve.
timeout: (integer - default: 30000)
The time to wait for a response. If the complete result is not available within that time, partial result is returned and the complete flag is set to true.
view: (one of DEFAULT, SIMPLE - default: DEFAULT)
The format of query results in the reponse.
content-pack-fields: (string)
If provided, fields defined in the given content-pack are returned in the response, in addition to static fields. Specify this parameter more than once to extract fields from several content packs. If this parameter is not specified, then only static fields are returned in the response payload
order-by-direction: (one of ASC, DESC - default: DESC)
The event timestamp sort direction.

Response

HTTP status code 200

Body: application/json

{
  "complete": true,
  "duration": 12,
  "events": [
    {
      "text": "[2017-06-09 12:21:02.076-0700] [vpxa] ...",
      "timestamp": 1496996462076,
      "timestampString": "2017-06-09 12:21:02.076 GMT+04:00",
      "fields": [
        {
          "name": "source",
          "content": "10.0.0.123"
        },
        {
          "name": "event_type",
          "content": "v4_4eca2033"
        },
        {
          "name": "appname",
          "startPosition": 32,
          "length": 4
        }
      ]
    },
    {
      "text": "[2017-06-09 12:20:56.176-0700] [hostd] ...",
      "timestamp": 1496996456176,
      "timestampString": "2017-06-09 12:20:56.176 GMT+04:00",
      "fields": [
        {
          "name": "source",
          "content": "10.0.0.234"
        },
        {
          "name": "event_type",
          "content": "v4_a7ce5b6a"
        },
        {
          "name": "appname",
          "startPosition": 32,
          "length": 5
        }
      ]
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "properties": {
    "events": {
      "description": "Lists events that match the query. Present when view=DEFAULT",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "description": "The full text of the event.",
            "type": "string"
          },
          "timestamp": {
            "description": "The time the event was reported, in milliseconds since 00:00:00 UTC on 1 January 1970",
            "type": "integer"
          },
          "timestampString": {
            "description": "The time the event was reported, in ISO8601 format with time zone offset",
            "type": "string"
          },
          "fields": {
            "description": "The fields of the event.",
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "name": {
                  "description": "The field name.",
                  "type": "string"
                },
                "content": {
                  "description": "The content of the field. Present if the field is not a substring of the event text; see also 'startPosition' and 'length'.",
                  "type": "string"
                },
                "startPosition": {
                  "description": "The startPosition in the event text of the field. Present if the field is a substring of the event text; see also 'content' and 'length'.",
                  "type": "integer"
                },
                "length": {
                  "description": "The length in the event text of the field. Present if the field is a substring of the event text; see also 'content' and 'startPosition'.",
                  "type": "integer"
                }
              }
            }
          }
        }
      }
    },
    "results": {
      "description": "List of events in a simple flat map format. Present when view=SIMPLE",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "text": {
            "description": "The full text of the event.",
            "type": "string"
          },
          "timestamp": {
            "description": "The time the event was reported, in milliseconds since 00:00:00 UTC on 1 January 1970",
            "type": "integer"
          },
          "timestampString": {
            "description": "The time the event was reported, in ISO8601 format with time zone offset",
            "type": "string"
          }
        },
        "additionalProperties": true
      }
    },
    "complete": {
      "description": "Indicates whether all matching events were returned (true), or if only some of them where, because the timeout expired (false).  See also 'warnings'.",
      "type": "boolean"
    },
    "duration": {
      "description": "The time required to compute the results, in milliseconds.",
      "type": "number"
    },
    "warnings": {
      "description": "A list of problems that were encountered while processing the query. Present if 'complete' is false.",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "description": "An identifier for the problem.",
            "type": "number"
          },
          "details": {
            "description": "A description of the problem.",
            "type": "string"
          },
          "progress": {
            "description": "The fraction of events processed when the timeout expired. Present for id 128 which indicates that the request timeout expired.",
            "type": "number"
          }
        }
      }
    }
  },
  "dependencies": {
    "warnings": {
      "properties": {
        "complete": {
          "type": "boolean",
          "enum": [
            false
          ]
        }
      }
    }
  },
  "type": "object",
  "required": [
    "complete"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/ilb/status

get /api/v1/ilb/status

TODO: add a description

This API is deprecated, and will be removed in a future release.

Response

HTTP status code 200

TODO: add a description

Headers

VMware-LI-API-Status: (string)
Indicates the life-cycle status of the API.
Example:
```
VMware-LI-API-Status: Deprecated
```
Warning: (string)
Additional information about the life-cycle status of the API.
Example:
```
Warning: 299 - "Deprecated: This API is deprecated" "Tue, 29 Mar 2016 21:54:10 GMT
```

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/internal/agent

/api/v1/internal/cluster

/api/v1/internal/force-error

/api/v1/internal/force-error-auth

/api/v1/inventory/item

/api/v1/inventory/item/{clientId}

/api/v1/inventory/items

/api/v1/inventory/lookup

/api/v1/licenses

Represents the license state, including a list of licenses and the average osi consumption for the last three months. The existing licenses can be enumerated, or a new license can be added to the current list.

get
post

get /api/v1/licenses

Retrieve the license state, including a list of licenses.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the License information

Body: application/json

{
  "licenseState": "ACTIVE",
  "maxOsis": 0,
  "maxCpus": 0,
  "hasCpu": false,
  "hasOsi": true,
  "averageOsiUsage": 0,
  "hasTap": false,
  "licenses": {
    "95bfa29a-e60d-49e7-b00e-8c40d83f2036": {
      "id": "95bfa29a-e60d-49e7-b00e-8c40d83f2036",
      "status": "Active",
      "error": "",
      "configuration": "1 Operating System Instance (OSI)",
      "licenseKey": "4J2TK-XXXXX-XXXXX-XXXXX-XXXXX",
      "infinite": true,
      "count": 0,
      "typeEnum": "OSI",
      "expiration": -14400000,
      "createdDate": 1498731608705
    }
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "type": "object",
    "properties": {
      "license": {
        "properties": {
          "licensekey": {
            "name": "licence_key",
            "id": "#licensekey",
            "type": "object",
            "properties": {
              "id": {
                "type": "string"
              },
              "status": {
                "type": "string"
              },
              "error": {
                "type": "string"
              },
              "configuration": {
                "type": "string"
              },
              "licenseKey": {
                "type": "string"
              },
              "infinite": {
                "type": "boolean"
              },
              "count": {
                "type": "integer"
              },
              "typeEnum": {
                "type": "string"
              },
              "expirationDate": {
                "type": "number"
              },
              "createdDate": {
                "type": "number"
              }
            }
          },
          "licensekeys": {
            "name": "license_keys",
            "id": "#licensekeys",
            "type": "object",
            "additionalProperties": true,
            "patternProperties": {
              "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$": {
                "$ref": "#/definitions/licensekey"
              }
            }
          }
        },
        "id": "#existinglicenses",
        "type": "object",
        "properties": {
          "licenseState": {
            "type": "string",
            "enum": [
              "ACTIVE",
              "LIMITED",
              "EXPIRED",
              "UNINITIALIZED",
              "ERROR",
              "DELETED"
            ]
          },
          "maxOsis": {
            "type": "integer"
          },
          "maxCpus": {
            "type": "integer"
          },
          "hasCpu": {
            "type": "boolean"
          },
          "hasOsi": {
            "type": "boolean"
          },
          "hasTap": {
            "type": "boolean"
          },
          "averageOsiUsage": {
            "type": "integer"
          },
          "licenses": {
            "oneOf": [
              {
                "$ref": "#/definitions/licensekeys"
              }
            ]
          }
        },
        "required": [
          "licenseState",
          "maxOsis",
          "maxCpus",
          "hasCpu",
          "hasOsi",
          "hasTap",
          "licenses"
        ],
        "additionalProperties": false
      }
    }
  },
  "required": [
    "license"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/licenses

Add a new license to the collection. A UUID will be generated to represent the license, and can be used for deletion. The license summary cannot be set, and is derived from the license key. In addition, a single license key cannot be updated in-place. Instead, the old license keys should be deleted after the new license is added.

This is a supported API.

Request

Body: application/json

{
  "key":"M502V-XXXXX-XXXXX-XXXXX-XXXXX"
}

Schema:

{
  "title": "License Key Added",
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "key": {
      "type": "string",
      "pattern": "^[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}$"
    }
  },
  "required": [
    "key"
  ]
}

Response

HTTP status code 201

Created a new license with the provided license key.

Body: application/json

{
  "license": {
    "id": "abcdef12-3456-7890-ba36-123456789012",
    "status": "Active",
    "error": "",
    "configuration": "1 Operating System Instance (OSI)",
    "licenseKey": "M502V-XXXXX-XXXXX-XXXXX-XXXXX",
    "infinite": true,
    "count": 0,
    "typeEnum": "OSI",
    "expirationDate": -14400000,
    "createdDate": 1498731659310
  }
}

Schema:

{
  "title": "License Key Added",
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "license": {
      "properties": {
        "id": {
          "title": "UUID",
          "type": "string",
          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
        },
        "status": {
          "type": "string"
        },
        "error": {
          "type": "string"
        },
        "configuration": {
          "type": "string"
        },
        "licenseKey": {
          "type": "string",
          "pattern": "^[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}-[0-9A-Z]{5}$"
        },
        "infinite": {
          "type": "boolean"
        },
        "count": {
          "type": "integer"
        },
        "typeEnum": {
          "type": "string"
        },
        "expirationDate": {
          "type": "number"
        },
        "createdDate": {
          "type": "number"
        }
      },
      "required": [
        "id",
        "status",
        "count",
        "licenseKey"
      ]
    }
  },
  "required": [
    "license"
  ]
}

HTTP status code 400

Error when trying to upload an invalid license key

Body: application/json

{
  "errorMessage": "Invalid serial number"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-03/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 409

Error when trying to upload the license key which already exists

Body: application/json

{
  "errorMessage": "License already exists."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-03/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  }
}

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/licenses/{licenseId}

Remove a single license key, specified by its UUID.

delete

delete /api/v1/licenses/{licenseId}

Remove a single license key, specified by its UUID.

This is a supported API.

Request

URI Parameters

licenseId: required (string)
License ID of the license to delete.
Example:
```
de305d54-75b4-431b-adb2-eb6b9e546014
```

Response

HTTP status code 200

Successfully deleted a license.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/messages/flush

/api/v1/messages/flush/{agentId}

put /api/v1/messages/flush/{agentId}

TODO: add a description

This API is deprecated, and will be removed in a future release.

Request

URI Parameters

agentId: required (string)
TODO: add a description

Body: application/json

{
}

Schema:

{
  "$schema": "http://json-schema.org/draft-03/schema"
}

Response

HTTP status code 200

TODO: add a description

Headers

VMware-LI-API-Status: (string)
Indicates the life-cycle status of the API.
Example:
```
VMware-LI-API-Status: Deprecated
```
Warning: (string)
Additional information about the life-cycle status of the API.
Example:
```
Warning: 299 - "Deprecated: This API is deprecated" "Tue, 29 Mar 2016 21:54:10 GMT
```

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/messages/ingest

/api/v1/messages/ingest/{agentId}

post

post /api/v1/messages/ingest/{agentId}

TODO: add a description

This API is deprecated, and will be removed in a future release.

Request

URI Parameters

agentId: required (string)
TODO: add a description

Body: application/json

{
}

Schema:

{
  "$schema": "http://json-schema.org/draft-03/schema"
}

Response

HTTP status code 200

TODO: add a description

Headers

VMware-LI-API-Status: (string)
Indicates the life-cycle status of the API.
Example:
```
VMware-LI-API-Status: Deprecated
```
Warning: (string)
Additional information about the life-cycle status of the API.
Example:
```
Warning: 299 - "Deprecated: This API is deprecated" "Tue, 29 Mar 2016 21:54:10 GMT
```

Body: application/json

{
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/notification

/api/v1/notification/channels

get /api/v1/notification/channels

Gets a list of all the notification channels that are used for alerting. At this time, the list includes SMTP server configuration used for sending alert emails.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the SMTP server configuration used for sending email alerts.

Body: application/json

{
  "channels": [
    {
      "type": "email",
      "config": {
        "server": "smtp.example.com",
        "port": 25,
        "sslAuth": false,
        "tls": false,
        "defaultSender": "email@example.com",
        "login": "user@example.com",
        "password": ""
      }
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "smtpserverconfig": {
      "type": "object",
      "required": [
        "server",
        "port",
        "sslAuth",
        "tls",
        "defaultSender",
        "login",
        "password"
      ],
      "properties": {
        "server": {
          "type": "string"
        },
        "port": {
          "type": "integer"
        },
        "sslAuth": {
          "type": "boolean"
        },
        "tls": {
          "type": "boolean"
        },
        "defaultSender": {
          "type": "string"
        },
        "login": {
          "type": "string"
        },
        "password": {
          "type": "string"
        }
      }
    },
    "notificationserverconfig": {
      "type": "object",
      "required": [
        "type",
        "config"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "email"
          ]
        },
        "config": {
          "oneOf": [
            {
              "$ref": "#/definitions/smtpserverconfig"
            }
          ]
        }
      }
    }
  },
  "id": "NotificationChannels",
  "type": "object",
  "properties": {
    "channels": {
      "type": "array",
      "items": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "#/definitions/notificationserverconfig"
          }
        ]
      }
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/notification/channels

Updates the configurations for the notification channels that are used for alerting. At this time, the list includes SMTP server configuration used for sending alert emails.

This is a supported API.

Request

Body: application/json

{
  "channels": [
    {
      "type": "email",
      "config": {
        "server": "smtp.example.com",
        "port": 25,
        "sslAuth": false,
        "tls": false,
        "defaultSender": "email@example.com",
        "login": "user@example.com",
        "password": "",
        "acceptCert": false
      }
    }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "smtpserverconfig": {
      "type": "object",
      "required": [
        "server",
        "port",
        "sslAuth",
        "tls",
        "defaultSender",
        "login",
        "password"
      ],
      "properties": {
        "server": {
          "type": "string"
        },
        "port": {
          "type": "integer"
        },
        "sslAuth": {
          "type": "boolean"
        },
        "tls": {
          "type": "boolean"
        },
        "defaultSender": {
          "type": "string"
        },
        "login": {
          "type": "string"
        },
        "password": {
          "type": "string"
        },
        "acceptCert": {
          "type": "boolean"
        }
      }
    },
    "notificationserverconfig": {
      "type": "object",
      "required": [
        "type",
        "config"
      ],
      "properties": {
        "type": {
          "type": "string",
          "enum": [
            "email"
          ]
        },
        "config": {
          "oneOf": [
            {
              "$ref": "#/definitions/smtpserverconfig"
            }
          ]
        }
      }
    }
  },
  "id": "NotificationChannels",
  "type": "object",
  "properties": {
    "channels": {
      "type": "array",
      "items": {
        "type": "object",
        "oneOf": [
          {
            "$ref": "#/definitions/notificationserverconfig"
          }
        ]
      }
    }
  }
}

Response

HTTP status code 200

Successfully updated the SMTP configurations used for sending alert emails.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/notification/email

Provides access to the list of email addresses to which system notifications will be delivered.

get /api/v1/notification/email

Retrieve the list of email addresses to which system notifications will be delivered.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the list of email addresses to which system notifications will be delivered.

Body: application/json

{
  "emails": ["email1@address.com", "email2@address.com"]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "emails": {
    "type": "array",
      "items": {
        "type": "string"
      }
     }
  },
  "required": [
    "emails"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/notification/email

Update the list of email addresses to which system notifications will be delivered.

This is a supported API.

Request

Body: application/json

{
  "emails": ["email1@address.com", "email2@address.com"]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "emails": {
    "type": "array",
      "items": {
        "type": "string"
      }
     }
  },
  "required": [
    "emails"
  ]
}

Response

HTTP status code 200

Successfully updated the list of emails to which system notifications will be delivered.

HTTP status code 400

Failed to apply configuration changes, either because of a parse error or invalid configuration options.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/notification/webhook

Provides access to the list of webhook URLs configured for receiving system notifications.

get /api/v1/notification/webhook

Get the list of webhook URLs configured for receiving system notifications.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the list of webhook URLs configured for receiving system notifications.

Body: application/json

{
  "URLs": ["http://example.com/webhook1", "http://example.com/webhook2"]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "URLs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "URLs"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/notification/webhook

Update the list of webhook URLs configured for receiving system notifications.

This is a supported API.

Request

Body: application/json

{
  "URLs": ["http://example.com/webhook1", "http://example.com/webhook2"]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "URLs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  },
  "required": [
    "URLs"
  ]
}

Response

HTTP status code 200

Successfully updated the list of webhook URLs configured for receiving system notifications.

HTTP status code 400

Failed to apply configuration changes, either because of a parse error or invalid configuration options.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/notification/config

/api/v1/notification/config/retention-threshold

get /api/v1/notification/config/retention-threshold

Retrieve current retention notification threshold configuration. If the amount of data the system can hold at the current ingestion rate is less than the given amount, send a system notification. E.g., if you are receiving 10 GB/day of data and you have 200 GB of space, then you have 20 days of capacity. If you set your threshold to 1 month, you will receive a notification that you are below this capacity.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved retention notification threshold configuration.

Body: application/json

{
  "sendNotification" : true,
  "dataInterval" : 2,
  "intervalUnit" : "MONTHS"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "sendNotification": {
      "type" : "boolean"
    },
    "dataInterval": {
      "type" : "integer"
    },
    "intervalUnit": {
      "enum": [
        "MINUTES",
        "HOURS",
        "DAYS",
        "WEEKS",
        "MONTHS"
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/notification/config/retention-threshold

Update retention notification threshold configuration.

This is a supported API.

Request

Body: application/json

{
  "sendNotification" : true,
  "dataInterval" : 2,
  "intervalUnit" : "MONTHS"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "sendNotification": {
      "type" : "boolean"
    },
    "dataInterval": {
      "type" : "integer"
    },
    "intervalUnit": {
      "enum": [
        "MINUTES",
        "HOURS",
        "DAYS",
        "WEEKS",
        "MONTHS"
      ]
    }
  }
}

Response

HTTP status code 200

Successfully updated retention notification threshold configuration.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/queries/all

/api/v1/queries/token

/api/v1/sessions

How to authenticate to Log Insight

Use the POST /api/v1/sessions API to sign into Log Insight. For example:

POST /api/v1/sessions HTTP/1.1
Accept: application/json
Content-Type: application/json
User-Agent: YourAppName/1.0

{
    "username": "username",
    "password": "password",
    "provider": "Local"
}

For authentication using VMware Identity Manager, use "provider": "vIDM", for Active Directory, use "provider": "ActiveDirectory".

When signing into Log Insight with VMware Identity Manager user, provide username in the following format:

username@domain

The API response contains a session ID that you can use with subsequent API requests:

HTTP/1.1 200 OK
Content-Type: application/json

{
  "userId": "cc251b9f-b4d0-437d-86de-8ac560d45e55",
  "sessionId": "80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL",
  "ttl": 1800
}

How to send authorized requests

To send an authorized API request, add the Authorization header to the request. Set the value of the header to the word Bearer, followed by a single space character, and then followed by the session ID returned from the POST /api/v1/sessions request.

GET /api/v1/time
User-Agent: YourAppName/1.0
Authorization: Bearer 80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL

post

post /api/v1/sessions

Signs into Log Insight with the given credentials, creates and returns a new session.

This is a supported API.

Request

Body: application/json

{
  "username": "johndoe",
  "password": "password",
  "provider": "Local"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "title": "Login",
  "properties": {
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    },
    "provider": {
      "type": "string",
      "pattern": "^(Local|ActiveDirectory|vIDM)$"
    }
  },
  "required": [
    "username",
    "password",
    "provider"
  ],
  "type": "object"
}

Response

HTTP status code 200

Successfully signed into Log Insight.

Body: application/json

{
  "userId": "cc251b9f-b4d0-437d-86de-8ac560d45e55",
  "sessionId": "80Lmue52xwIgDiQMu7as9jLdLFFs+Hn3HI2WP0fx6kH0ApL",
  "ttl": 1800
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "userId": {
      "description": "UUID",
      "type": "string",
      "id": "#userId",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "sessionId": {
      "description": "An opaque session ID for use in the Authorization header.",
      "type": "string",
      "minLength": 1,
      "id": "#sessionId"
    },
    "ttl": {
      "description": "Time to live: Number of seconds this session is valid for.",
      "type": "integer",
      "minimum": 0,
      "id": "#ttl"
    }
  },
  "required": [
    "userId",
    "sessionId",
    "ttl"
  ]
}

HTTP status code 401

Could not sign in with the given credentials.

Body: application/json

{
  "errorMessage": "Invalid username or password.",
  "errorCode": "FIELD_ERROR"
}

HTTP status code 503

Log Insight did not have its initial configuration set up yet. See /deployment/new.

Body: application/json

{
  "errorMessage": "LI server should be bootstrapped to process this API call"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

/api/v1/sessions/current

Retrieve user ID and TTL (time to live) for the current session.

get /api/v1/sessions/current

Retrieve user ID and TTL (time to live) for the current session.

This is a supported API.

Response

HTTP status code 200

User ID and TTL (time to live) for the current session.

Body: application/json

{
  "userId": "cc251b9f-b4d0-437d-86de-8ac560d45e55",
  "ttl": 1800
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "type": "object",
  "properties": {
    "userId": {
      "description": "UUID",
      "type": "string",
      "id": "#userId",
      "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
    },
    "ttl": {
      "description": "Time to live: Number of seconds this session is valid for.",
      "type": "integer",
      "minimum": 0,
      "id": "#ttl"
    }
  },
  "required": [
    "userId",
    "ttl"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/stats/groups

/api/v1/stats/groups/{statGroup}

/api/v1/stats/groups/{statGroup}/types

/api/v1/stats/groups/{statGroup}/types/{statType}

/api/v1/stats/groups/{statGroup}/types/{statType}/names

/api/v1/time

Time is critical to the core functionality of VMware vRealize Log Insight. You must synchronize the time on the Log Insight virtual appliance with an NTP server or with the ESX/ESXi host on which you deployed the virtual appliance.

get /api/v1/time

Retrieve the current time from the server's perspective, expressed as milliseconds-since-epoch UTC.

Constraints used for an events query include operators. The time range for the LAST operator is relative to the current time. See the constraints reference section of /events for details.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the server's current time.

Body: application/json

{
  "currentTime": 1496995473577,
  "currentTimeString": "2017-06-09 12:04:33.577 GMT+04:00"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "currentTime": {
      "type": "integer"
    },
    "currentTimeString": {
      "type": "string"
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/time/config

Time source synchronization settings.

By default, vRealize Log Insight synchronizes time with a pre-defined list of public NTP servers. If public NTP servers are not accessible due to a firewall, you can use the internal NTP server of your company. If no NTP servers are available, you can sync time with the ESX/ESXi host where you have deployed the vRealize Log Insight virtual appliance.

get /api/v1/time/config

Retrieve the current list of time sources for this cluster.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved the current time source.

Body: application/json

{
  "ntpConfig": {
    "timeReference": "NTP_SERVER",
    "ntpServers": [
      "0.vmware.pool.ntp.org",
      "1.vmware.pool.ntp.org",
      "2.vmware.pool.ntp.org",
      "3.vmware.pool.ntp.org"
    ]
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "timesource": {
      "type": "object",
      "required": [
        "timeReference"
      ],
      "properties": {
        "timeReference": {
          "type": "string",
          "enum": [
            "NTP_SERVER",
            "ESX_HOST"
          ]
        },
        "ntpServers": {
          "id": "#ntpServers",
          "description": "List of remote NTP server FQDN/IPs",
          "type": "array",
          "items": {
            "type": "string"
          }
        }
      }
    }
  },
  "id": "TimeSyncronization",
  "type": "object",
  "properties": {
    "ntpConfig": {
      "oneOf": [
        {
          "$ref": "#/definitions/timesource"
        }
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/time/config

Set new time sources for this cluster.

This is a supported API.

Request

Body: application/json

{
  "timeReference": "NTP_SERVER",
  "ntpServers": [
    "0.vmware.pool.ntp.org",
    "1.vmware.pool.ntp.org",
    "2.vmware.pool.ntp.org",
    "3.vmware.pool.ntp.org"
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "timeReference": {
      "enum": [
        "NTP_SERVER",
        "ESX_HOST"
      ]
    },
    "ntpServers": {
      "type": "array",
        "servernames": {
           "type": "string"
        }
    }
  }
}

Response

HTTP status code 200

Successfully applied new time source settings.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/time/test

post

post /api/v1/time/test

Test connectivity to new NTP servers. May take up to 20 seconds per server listed.

This is a supported API.

Request

Body: application/json

{
  "ntpServers": [
    "0.vmware.pool.ntp.org",
    "1.vmware.pool.ntp.org",
    "2.vmware.pool.ntp.org",
    "3.vmware.pool.ntp.org"
  ]
}

Schema:

{
  "description": "Test NTP servers",
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "ntpServers": {
      "description": "List of remote NTP server FQDN/IPs",
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Response

HTTP status code 200

Successfully tested connectivity to NTP servers.

Body: application/json

{
  "testedNTPServers": [
    { "server": "0.vmware.pool.ntp.org", "state": "pass" },
    { "server": "1.vmware.pool.ntp.org", "state": "pass" },
    { "server": "2.vmware.pool.ntp.org", "state": "pass" },
    { "server": "3.vmware.pool.ntp.org", "state": "fail" }
  ]
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "testedNTPServers": {
      "description": "List of remote NTP server FQDN/IPs",
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "server": {
            "type": "string"
          },
          "state": {
            "type": "string",
            "enum": [
              "fail",
              "pass"
            ]
          }
        }
      }
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/ui

Represents the list of configurations for UI.

/api/v1/ui/browser-session

By default, vRealize Log Insight Web sessions expire in 30 minutes. You can increase or decrease the timeout duration, or disable it entirely.

get /api/v1/ui/browser-session

Retrieve current browser session timeout, expressed in minutes.

This is a supported API.

Response

HTTP status code 200

Browser session timeout configuration was retrieved successfully.

Body: application/json

{
  "timeout" : 20
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "timeout": {
      "type" : "integer",
      "minimum": -1
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/ui/browser-session

Set a new browser session timeout, expressed in minutes. Specify -1 for no timeout.

This is a supported API.

Request

Body: application/json

{
  "timeout" : 20
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "timeout": {
      "type" : "integer",
      "minimum": -1
    }
  }
}

Response

HTTP status code 200

Browser session timeout was saved successfully.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/ui/language

The VMware vRealize Log Insight user interface is localized to several languages. However, you can administratively force use of the English (EN_US) translation for all users.

get /api/v1/ui/language

Retrieve current language configuration.

This is a supported API.

Response

HTTP status code 200

Language configuration was retrieved successfully.

Body: application/json

{
  "alwaysUseEnglish" : true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "alwaysUseEnglish": {
      "type" : "boolean"
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/ui/language

Set a new language configuration.

This is a supported API.

Request

Body: application/json

{
  "alwaysUseEnglish" : true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "alwaysUseEnglish": {
      "type" : "boolean"
    }
  }
}

Response

HTTP status code 200

Language configuration was saved successfully.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/upgrades

Represents the list of active upgrade operations.

post
get

post /api/v1/upgrades

Starts the process of upgrading Log Insight to a new version. This request uploads a PAK file containing the new version, and sets the upgrade status to "Pending". PAK file URL should be provided in JSON body. It's also possible to upload PAK file directly as a binary data by setting 'Content-Type' header to 'application/octet-stream' and sending PAK file as a body. It returns the new End User License Agreement (EULA) and upgrade version. To continue with the upgrade, send a PUT /upgrades/{version}/eula with eulaAccepted set to true.

Troubleshooting Tips

Refer to "/storage/var/loginsight/upgrade.log" for additional information on upgrade failure.

This is a supported API.

Request

Body: application/json

{
  "pakUrl": "http://vmware.com/downloads/VMware-vRealize-Log-Insight-4.0.0.pak"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "pakUrl": {
      "type": "string"
    }
  },
  "required": [ "pakUrl" ]
}

Body: application/octet-stream

PAK file containing new version of the Log Insight

Response

HTTP status code 200

The upgrade was started successfully.

Body: application/json

{
  "eula": "VMware Agreement text",
  "version": "4.0.0-1234567"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "eula": {
      "type": "string"
    },
    "version": {
      "type": "string"
    }
  }
}

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

get /api/v1/upgrades

Gets the upgraded version of the Log Insight cluster.

This is a supported API.

Response

HTTP status code 200

The upgraded version was retrieved successfully.

Body: application/json

{
  "version": "4.0.0-1234567",
  "fullVersion": "4.0.0-1234567",
  "stable": true,
  "nodes": {
    "5817df88-7383-43cb-bf2b-aa87de412213": {
      "version": "4.0.0-1234567",
      "fullVersion": "4.0.0-1234567"
    },
    "74108d1e-7ec2-4524-b5ca-864957654d2e": {
      "version": "4.0.0-1234567",
      "fullVersion": "4.0.0-1234567"
    },
    "61f3dfb1-dcf2-4e6d-9335-6271716d8055": {
      "version": "4.0.0-1234567",
      "fullVersion": "4.0.0-1234567"
    },
    "c73f9683-0319-4fee-a3a8-a841c62e6b61": {
      "version": "4.0.0-1234567",
      "fullVersion": "4.0.0-1234567"
    }
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "UpgradeNodeList": {
      "type": "object",
      "name": "UpgradeNodeList",
      "id": "#UpgradeNodeList",
      "patternProperties": {
        "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$": {
          "$ref": "#/definitions/NodeUpgradeStatus"
        }
      }
    },
    "NodeUpgradeStatus": {
      "type": "object",
      "name": "NodeUpgradeStatus",
      "id": "#NodeUpgradeStatus",
      "properties": {
        "version": {
          "type": "string"
        },
        "fullVersion": {
          "type": "string"
        }
      }
    }
  },
  "type": "object",
  "properties": {
    "version": {
      "type": "string"
    },
    "fullVersion": {
      "type": "string"
    },
    "stable": {
      "type": "boolean"
    },
    "nodes": {
      "oneOf": [
        {
          "$ref": "#/definitions/UpgradeNodeList"
        }
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/upgrades/local

Represents the upgrade state on the Log Insight node that received the API call.

get /api/v1/upgrades/local

Gets the upgraded version on the Log Insight node that received the API call.

This is a supported API.

Response

HTTP status code 200

The upgraded version was retrieved successfully.

Body: application/json

{
  "version": "4.0.0-1234567",
  "fullVersion": "4.0.0-1234567"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
     "version": {
       "type": "string"
     },
     "fullVersion": {
       "type": "string"
     }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/upgrades/{version}

get /api/v1/upgrades/{version}

Gets the cluster-wide status of the upgrade.

This is a supported API.

Request

URI Parameters

version: required (string)
The Log Insight version of the upgrade
Example:
```
4.0.0-1234567
```

Response

HTTP status code 200

Successfully retrieved the upgrade status of the cluster.

Body: application/json

{
  "status": {
    "version": "4.0.0-1234567",
    "pakFileName": "VMware-vRealize-Log-Insight-4.0.0-1234567.pak",
    "nodeStatuses": [{
      "status": "Upgrading",
      "timestamp": 1496145083890,
      "timestampString": "2017-05-30 15:51:23.890 GMT+04:00",
      "token": "27bcbafc-b99d-4609-9fab-4f3ad937fe5e"
      }],
    "pakFileUrl": "http://vmware.com/downloads/VMware-vRealize-Log-Insight-4.0.0.pak",
    "eulaAccepted": false,
    "masterToken": "27bcbafc-b99d-4609-9fab-4f3ad937fe5e",
    "clusterStatus": "Upgrading",
    "started": "1496145083067",
    "finished": "0",
    "startedString": "2017-05-30 15:51:23.067 GMT+04:00",
    "finishedString": ""
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "UpgradeStatusSingleNode":{
        "id": "UpgradeStatusSingleNode",
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "Started",
              "PendingSnapshot",
              "CreatingSnapshot",
              "Pending",
              "TransferringPak",
              "Upgrading",
              "Restarting",
              "Verifying",
              "Complete",
              "Cancelled",
              "Failed",
              "NewDeployment"
            ]
          },
          "timestamp": {
            "type": "number",
            "id": "#timestamp"
          },
          "timestampString": {
            "type": "string"
          },
          "token": {
            "type": "string",
            "id": "#token"
          }
        },
        "required": [
          "status",
          "timestamp",
          "timestampString",
          "token"
        ]
      },
    "upgradestatus": {
      "id": "#upgradestatus",
      "type": "object",
      "properties": {
        "version": {
          "type": "string"
        },
        "pakFileName": {
          "type": "string"
        },
        "nodeStatuses": {
          "type": "array",
          "uniqueItems": true,
          "items": { "oneOf": [
            {"$ref":"#/definitions/UpgradeStatusSingleNode"}
          ]}
        },
        "pakFileUrl": {
          "type": "string"
        },
        "eulaAccepted": {
          "type": "boolean"
        },
        "masterToken": {
          "type": "string"
        },
        "clusterStatus": {
          "enum": [
            "Started",
            "PendingSnapshot",
            "CreatingSnapshot",
            "Pending",
            "TransferringPak",
            "Upgrading",
            "Restarting",
            "Verifying",
            "Complete",
            "Cancelled",
            "Failed",
            "NewDeployment"
          ]
        },
        "started": {
          "type": "string"
        },
        "finished": {
          "type": "string"
        },
        "startedString": {
          "type": "string"
        },
        "finishedString": {
          "type": "string"
        }
      }
    }
  },
  "title": "Upgrade to Version Status",
  "type": "object",
  "properties": {
    "status": {
      "oneOf": [
        {
          "$ref": "#/definitions/upgradestatus"
        }
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/upgrades/{version}/eula

put /api/v1/upgrades/{version}/eula

Accepts or declines the End User License Agreement (EULA) of a product upgrade. Continues the upgrade process if accepted is true, or cancels it otherwise. This request is expected when the upgrade status is "Pending".

This is a supported API.

Request

URI Parameters

version: required (string)
The Log Insight version of the upgrade
Example:
```
4.0.0-1234567
```

Body: application/json

{
  "accepted": true
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "accepted": {
      "type": "boolean",
      "default": false
    }
  },
  "required": [ "accepted" ]
}

Response

HTTP status code 200

Successfully accepted or declined the EULA. Returns the upgrade status of the cluster.

Body: application/json

{
  "status": {
    "started": "1471285414207",
    "finished": "0",
    "version": "4.0.0-1234567",
    "pakFileName": "VMware-vRealize-Log-Insight-4.0.0-1234567.pak",
    "nodeStatuses": [{
      "status": "Upgrading",
      "token": "27bcbafc-b99d-4609-9fab-4f3ad937fe5e",
      "timestamp": 1498657510765,
      "timestampString": "2017-06-28 17:45:10.765 GMT+04:00"
      }],
    "pakFileUrl": "http://vmware.com/downloads/VMware-vRealize-Log-Insight-4.0.0.pak",
    "eulaAccepted": true,
    "masterToken": "27bcbafc-b99d-4609-9fab-4f3ad937fe5e",
    "clusterStatus": "Upgrading"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "definitions": {
    "UpgradeStatusSingleNode":{
        "id": "UpgradeStatusSingleNode",
        "type": "object",
        "properties": {
          "status": {
            "type": "string",
            "enum": [
              "Started",
              "PendingSnapshot",
              "CreatingSnapshot",
              "Pending",
              "TransferringPak",
              "Upgrading",
              "Restarting",
              "Verifying",
              "Complete",
              "Cancelled",
              "Failed",
              "NewDeployment"
            ]
          },
          "timestamp": {
            "type": "number",
            "id": "#timestamp"
          },
          "timestampString": {
            "type": "string"
          },
          "token": {
            "type": "string",
            "id": "#token"
          }
        },
        "required": [
          "status",
          "timestamp",
          "timestampString",
          "token"
        ]
      },
    "upgradestatus": {
      "id": "#upgradestatus",
      "type": "object",
      "properties": {
        "version": {
          "type": "string"
        },
        "pakFileName": {
          "type": "string"
        },
        "nodeStatuses": {
          "type": "array",
          "uniqueItems": true,
          "items": { "oneOf": [
            {"$ref":"#/definitions/UpgradeStatusSingleNode"}
          ]}
        },
        "pakFileUrl": {
          "type": "string"
        },
        "eulaAccepted": {
          "type": "boolean"
        },
        "masterToken": {
          "type": "string"
        },
        "clusterStatus": {
          "enum": [
            "Started",
            "PendingSnapshot",
            "CreatingSnapshot",
            "Pending",
            "TransferringPak",
            "Upgrading",
            "Restarting",
            "Verifying",
            "Complete",
            "Cancelled",
            "Failed",
            "NewDeployment"
          ]
        },
        "started": {
          "type": "string"
        },
        "finished": {
          "type": "string"
        },
        "startedString": {
          "type": "string"
        },
        "finishedString": {
          "type": "string"
        }
      }
    }
  },
  "title": "Upgrade to Version Status",
  "type": "object",
  "properties": {
    "status": {
      "oneOf": [
        {
          "$ref": "#/definitions/upgradestatus"
        }
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/upgrades/{version}/nodes

/api/v1/upgrades/{version}/rollback/services/{service}

/api/v1/users/self

Represents the user logged-in to the API.

/api/v1/version

get /api/v1/version

Retrieve Log Insight version information, in the form Major.Minor.Patch-Build.

This is a supported API.

Response

HTTP status code 200

Body: application/json

{
  "releaseName": "GA",
  "version": "1.2.3-4567890"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "releaseName": {
      "type": "string"
    },
    "version": {
      "type": "string"
    }
  },
  "required": [
    "releaseName",
    "version"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vidm

get
post

get /api/v1/vidm

Gets the current vIDM configuration.

This is a supported API.

Response

HTTP status code 200

Gets the current vIDM configuration.

Body: application/json

{
  "enabled": true,
  "hostname": "vidm.example.com",
  "port": 443,
  "tenant": "vIDMTenant",
  "redirectURL": "loginsight.example.com"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "enabled": {
      "type": "boolean"
    },
    "hostname": {
      "type": "string"
    },
    "port": {
      "type": "integer"
    },
    "tenant": {
      "type": "string"
    },
    "redirectURL": {
      "type": "string"
    }
  },
  "required" : [
    "enabled"
  ]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "Failed to process request."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/vidm

Configures vIDM integration.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "acceptCert" : true,
  "enabled": true,
  "hostname": "vidm.example.com",
  "port": 443,
  "tenant": "vIDMTenant",
  "redirectURL": "loginsight.example.com",
  "username": "vIDMAdmin",
  "password": "vIDMPassword"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "acceptCert": {
      "type": "boolean"
    },
    "enabled": {
      "type": "boolean"
    },
    "hostname": {
      "type": "string"
    },
    "port": {
      "type": "integer"
    },
    "tenant": {
      "type": "string"
    },
    "redirectURL": {
      "type": "string"
    },
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required": [
    "enabled",
    "hostname",
    "redirectURL",
    "username",
    "password"
  ]
}

Response

HTTP status code 200

HTTP response code 200 indicates that connection was made successfully.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, did not match the required JSON format, or provided vIDM credentials are wrong.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 403

Indicates one of 2 possible cases; vIDM provided untrusted CA certificate and SSL connection was unsuccessful, or the requested action is not permitted for requesting user.

Body: application/json

{
  "errorMessage": "Requested action is forbidden for the requesting user.",
  "errorCode": "VIDM_ERROR",
  "errorDetails": {
    "errorCode":"com.vmware.loginsight.api.providers.vidm.forbidden_for_user"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 404

Indicates that LI was not able to connect to specified vIDM instance.

Body: application/json

{
  "errorMessage": "Recieved unexpected response from the specified vIDM instance.",
  "errorCode": "VIDM_ERROR",
  "errorDetails": {
    "errorCode":"com.vmware.loginsight.api.providers.vidm.unexpected_response"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "Failed to process request."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

HTTP status code 504

This response specifies that LI was unable to get timely and valid response from vIDM.

Body: application/json

{
  "errorMessage": "Recieved unexpected response from the specified vIDM instance.",
  "errorCode": "VIDM_ERROR",
  "errorDetails": {
    "errorCode":"com.vmware.loginsight.api.providers.vidm.unexpected_response"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vidm/test

post

post /api/v1/vidm/test

Tests a connection with the specified vIDM instance with specified credentials.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "acceptCert" : true,
  "enabled": true,
  "hostname": "vidm.example.com",
  "port": 443,
  "tenant": "vIDMTenant",
  "redirectURL": "loginsight.example.com",
  "username": "vIDMAdmin",
  "password": "vIDMPassword"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "acceptCert": {
      "type": "boolean"
    },
    "hostname": {
      "type": "string"
    },
    "port": {
      "type": "integer"
    },
    "tenant": {
      "type": "string"
    },
    "username": {
      "type": "string"
    },
    "password": {
      "type": "string"
    }
  },
  "required" : [
    "hostname",
    "username",
    "password"
   ]
}

Response

HTTP status code 200

HTTP response code 200 indicates that connection was made successfully.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, did not match the required JSON format, or provided vIDM credentials are wrong.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 403

Indicates one of 2 possible cases; vIDM provided untrusted CA certificate and SSL connection was unsuccessful, or the requested action is not permitted for requesting user.

Body: application/json

{
  "errorMessage": "Requested action is forbidden for the requesting user.",
  "errorCode": "VIDM_ERROR",
  "errorDetails": {
    "errorCode":"com.vmware.loginsight.api.providers.vidm.forbidden_for_user"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 404

Indicates that LI was not able to connect to specified vIDM instance.

Body: application/json

{
  "errorMessage": "Recieved unexpected response from the specified vIDM instance.",
  "errorCode": "VIDM_ERROR",
  "errorDetails": {
    "errorCode":"com.vmware.loginsight.api.providers.vidm.unexpected_response"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "Failed to process request."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

HTTP status code 504

This response specifies that LI was unable to get timely and valid response from vIDM.

Body: application/json

{
  "errorMessage": "Recieved unexpected response from the specified vIDM instance.",
  "errorCode": "VIDM_ERROR",
  "errorDetails": {
    "errorCode":"com.vmware.loginsight.api.providers.vidm.unexpected_response"
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vidm/status

get /api/v1/vidm/status

Gets the current state of connection with vIDM.

This is a supported API.

Response

HTTP status code 200

HTTP response code 200 indicates that connection was made successfully.

Body: application/json

{
  "state":"CONNECTED"
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "state": {
      "enum": [
        "CONNECTED",
        "DISCONNECTED",
        "UNCONFIGURED"
      ]
    }
  },
  "required": ["state"]
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "Failed to process request."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vsphere

Providing APIs to work with configurations for connecting with vCenter Servers. Integration with vSphere provides many advantages including the ability to collect vCenter Server events, tasks and alarms as well as configure ESXi hosts to forward logs to Log Insight. It is recommended to have up to 15 vCenter Server instances configured per Log Insight connected node.

get
post

get /api/v1/vsphere

Get all vCenter Server integration configurations.

This is a supported API.

Response

HTTP status code 200

Successfully retrieved vCenter Server integration configurations.

Body: application/json

{
  "vCenterServers" :
    [
      {
        "hostname":"vSphere-hostname1",
        "username":"vSphere-username1",
        "syslogProtocol":"tcp",
        "esxiHostsConfigured":true,
        "configureNewEsxiHostsAutomatically":true,
        "passwordSet":true,
        "vsphereEventsEnabled":true,
        "target":"exampleVIP.ip.or.fqdn"
      },{
        "hostname":"vSphere-hostname2",
        "username":"vSphere-username2",
        "syslogProtocol":"udp",
        "esxiHostsConfigured":false,
        "configureNewEsxiHostsAutomatically":false,
        "passwordSet":true,
        "vsphereEventsEnabled":true,
        "target":"exampleVIP1.ip.or.fqdn"
      }
    ]
}

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",

   "type":"object",
   "properties":{
      "vSenterServers":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "hostname":{
                  "type":"string"
               },
               "username":{
                  "type":"string"
               },
               "passwordSet":{
                  "type":"boolean"
               },
               "target":{
                  "type":"string"
               },
               "syslogProtocol":{
                  "enum":[
                     "udp",
                     "tcp",
                     "ssl"
                  ],
                  "description":"Syslog protocol used for ESXi hosts auto-configuration."
               },
               "esxiHostsConfigured":{
                  "type":"boolean",
                  "description":"Indicates whether ESXi hosts are configured or not."
               },
               "configureNewEsxiHostsAutomatically":{
                  "type":"boolean",
                  "description":"Indicates whether ESXi hosts auto-configuration is turned on or not. Auto-configuration will periodically try to configure ESXi hosts that are not configured yet."
               },
               "vsphereEventsEnabled":{
                  "type":"boolean",
                  "description":"Indicates whether to collect vCenter Server events, tasks, and alarms or not."
               }
            }
         }
      }
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

post /api/v1/vsphere

Add new integration configuration to vCenter Server.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "acceptCert" : true,
  "hostname":"example-vc.eng.vmware.com",
  "username":"exampleVCUsername",
  "password":"exampleVCPassword",
  "syslogProtocol":"tcp",
  "vsphereEventsEnabled":true,
  "configureEsxiHostsAutomatically":false,
  "target":"exampleVIP.ip.or.fqdn",
  "userTags":"tag1=value1,tag2=value2"
}

Schema:

{
  "$schema": "http: //json-schema.org/draft-04/schema",
  "type":  "object",
  "properties": {
    "acceptCert": {
      "type": "boolean",
      "description":"Automatically accept not trusted vCenter Server certificates. Default value is false"
    },
    "hostname":{
      "type":"string",
      "description":"The vCenter Server hostname"
    },
    "username":{
      "type":"string",
      "description":"The vCenter Server username"
    },
    "password":{
      "type":"string",
      "description":"The vCenter Server password"
    },
    "syslogProtocol":{
      "enum":[
        "udp",
        "tcp",
        "ssl"
      ],
      "description":"Syslog protocol used for ESXi hosts configuration. Default Protocol is UDP."
    },
    "vsphereEventsEnabled":{
      "type":"boolean",
      "description":"Collect vCenter Server events, tasks, and alarms. Default value is false"
    },
    "configureEsxiHostsAutomatically":{
      "type":"boolean",
      "description":"Configure ESXi hosts and turn on auto-configuration. Default value is false. Auto-configuration will periodically try to configure ESXi hosts that are not configured yet."
    },
    "target":{
      "type":"string",
      "description":"Target for vCenter Server and ESXi hosts logs. This can be Log Insight master node or one of the virtual IP addresses."
    },
    "userTags":{
      "type":"string",
      "description":"User tags used for vCenter Server integration"
    }
  },
  "required":  [
    "hostname",
    "username",
    "password",
    "target"
  ]
}

Response

HTTP status code 200

Successfully added new vCenter Server integration configuration.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 409

Configuration with specified vCenter Server hostname already exists.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vsphere/{vcHostname}

Represents a vCenter Server integration configuration.

get /api/v1/vsphere/{vcHostname}

Retrieve the integration configuration settings for vCenter Server with the specified hostname.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname

Body: application/json

{
  "vCenterServer" :
    {
      "hostname":"vSphere-hostname",
      "username":"vSphere-username",
      "passwordSet":true,
      "syslogProtocol":"tcp",
      "esxiHostsConfigured":true,
      "configureNewEsxiHostsAutomatically":true,
      "vsphereEventsEnabled":true,
      "target":"exampleVIP.ip.or.fqdn"
  }
}

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",

   "type":"object",
   "properties":{
      "vCenterServer":{
         "type":"object",
         "properties":{
            "hostname":{
               "type":"string"
            },
            "username":{
               "type":"string"
            },
            "passwordSet":{
               "type":"boolean"
            },
            "syslogProtocol":{
               "enum":[
                  "udp",
                  "tcp",
                  "ssl"
               ],
               "description":"Syslog protocol used for ESXi hosts auto-configuration."
            },
            "esxiHostsConfigured":{
               "type":"boolean",
               "description":"Indicates whether ESXi hosts are configured or not."
            },
            "configureNewEsxiHostsAutomatically":{
               "type":"boolean",
               "description":"Indicates whether ESXi hosts auto-configuration is turned on or not. Auto-configuration will periodically try to configure ESXi hosts that are not configured yet."
            },
            "vsphereEventsEnabled":{
               "type":"boolean",
               "description":"Indicates whether to collect vCenter Server events, tasks, and alarms or not."
            },
            "target":{
               "type":"string"
            }
         }
      }
   }
}

Response

HTTP status code 200

Successfully retrieved the integration configuration settings for vCenter Server.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Configuration with specified vCenter Server hostname does not exist.

Body: text/plain

Not Found

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

put /api/v1/vsphere/{vcHostname}

Update the integration configuration settings for vCenter Server with the specified hostname.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname

Body: application/json

{
  "acceptCert" : true,
  "username":"exampleVCUsername",
  "password":"exampleVCPassword",
  "syslogProtocol":"tcp",
  "vsphereEventsEnabled":true,
  "configureEsxiHostsAutomatically":false,
  "target":"exampleVIP.ip.or.fqdn",
  "userTags":"tag1=value1,tag2=value2"
}

Schema:

{
  "$schema": "http: //json-schema.org/draft-04/schema",
  "type":  "object",
  "properties": {
    "acceptCert": {
      "type": "boolean",
      "description":"Automatically accept not trusted vCenter Server certificates. Default value is false"
    },
    "username":{
      "type":"string",
      "description":"The vCenter Server username"
    },
    "password":{
      "type":"string",
      "description":"The vCenter Server password"
    },
    "syslogProtocol":{
      "enum":[
        "udp",
        "tcp",
        "ssl"
      ],
      "description":"Syslog protocol used for ESXi hosts configuration."
    },
    "vsphereEventsEnabled":{
      "type":"boolean",
      "description":"Collect vCenter Server events, tasks, and alarms."
    },
    "configureEsxiHostsAutomatically":{
      "type":"boolean",
      "description":"Configure ESXi hosts and turn on auto-configuration. Auto-configuration will periodically try to configure ESXi hosts that are not configured yet."
    },
    "target":{
      "type":"string",
      "description":"Target for vCenter Server and ESXi hosts logs. This can be Log Insight master node or one of the virtual IP addresses."
    },
    "userTags":{
      "type":"string",
      "description":"User tags used for vCenter Server integration"
    }
  }
}

Response

HTTP status code 200

Successfully updated vCenter Server integration configuration for vCenter Server.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Configuration with specified vCenter Server hostname does not exist.

Body: text/plain

Not Found

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

delete /api/v1/vsphere/{vcHostname}

Delete the integration configuration for vCenter Server with the specified hostname.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname

Query Parameters

removeEsxiHostsConfiguration: (boolean - default: true)
Remove ESXi hosts configurations before removing vCenter Server integration

Response

HTTP status code 200

Successfully removed the integration configuration for vCenter Server.

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Configuration with specified vCenter Server hostname does not exist.

Body: text/plain

Not Found

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

/api/v1/vsphere/{vcHostname}/hosts

put /api/v1/vsphere/{vcHostname}/hosts

Update ESXi hosts configuration of vCenter server with the specified hostname.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname

Body: application/json

{
  "configure":true,
  "syslogProtocol": "TCP"
}

Schema:

{
  "$schema": "http: //json-schema.org/draft-04/schema",
  "type":  "object",
  "properties": {
    "configure": {
      "type": "boolean",
      "description":"Indicates whether to configure the ESXi host or remove configuration."
    },
    "syslogProtocol": {
      "enum": [
        "udp",
        "tcp",
        "ssl"
      ],
      "description":"Syslog protocol used for configuring ESXi hosts. Default protocol is UDP."
    }
  },
  "required":  [
    "configure"
  ]
}

Response

HTTP status code 200

ESXi hosts configuration successfully updated.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Configuration with specified vCenter Server hostname does not exist.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

get /api/v1/vsphere/{vcHostname}/hosts

Get ESXi hosts of the vCenter Server with the specified hostname along with their configuration details.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname

Response

HTTP status code 200

Successfully retrieved the list of ESXi hosts and their configuration details.

Body: application/json

{
  "hosts" :
    [
      {
        "hostname":"example-esxi-hostname",
        "os":"VMware ESXi",
        "version":"5.0.1",
        "build":"12345",
        "configured":true,
        "syslogProtocol":"tcp",
        "unsupported":false,
        "disconnected":true
      },{
        "hostname":"example-esxi-hostname1",
        "os":"VMware ESXi",
        "version":"5.0.1",
        "build":"12345",
        "configured":false,
        "syslogProtocol":"udp",
        "unsupported":false,
        "disconnected":false
      }
    ]
}

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",

   "type":"object",
   "properties":{
      "hosts":{
         "type":"array",
         "items":{
            "type":"object",
            "properties":{
               "hostname":{
                  "type":"string"
               },
               "os":{
                  "type":"string"
               },
               "version":{
                  "type":"string"
               },
               "build":{
                  "type":"string"
               },
               "configured":{
                  "type":"boolean"
               },
               "syslogProtocol":{
                  "enum":[
                     "udp",
                     "tcp",
                     "ssl"
                  ]
               },
               "unsupported":{
                  "type":"boolean"
               },
               "disconnected":{
                  "type":"boolean"
               },
               "error":{
                  "type":"string"
               },
               "warning":{
                  "type":"string"
               }
            }
         }
      }
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Configuration with specified vCenter Server hostname does not exist.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vsphere/{vcHostname}/hosts/{esxiHost}

get /api/v1/vsphere/{vcHostname}/hosts/{esxiHost}

Get ESXi host with the specified hostname in the specified vSphere Server along with it's configuration details.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname
esxiHost: required (string)
Hostname of ESXi host

Response

HTTP status code 200

Successfully retrieved ESXi host with the specified hostname and it's configuration details.

Body: application/json

{
  "host" :
    {
      "hostname":"example-esxi-hostname",
      "os":"VMware ESXi",
      "version":"5.0.1",
      "build":"12345",
      "configured":true,
      "syslogProtocol":"tcp",
      "unsupported":false,
      "disconnected":true
   }
}

Schema:

{
   "$schema":"http://json-schema.org/draft-04/schema",

   "type":"object",
   "properties":{
      "host":{
         "type":"object",
         "properties":{
            "hostname":{
               "type":"string"
            },
            "os":{
               "type":"string"
            },
            "version":{
               "type":"string"
            },
            "build":{
               "type":"string"
            },
            "configured":{
               "type":"boolean"
            },
            "syslogProtocol":{
               "enum":[
                  "udp",
                  "tcp",
                  "ssl"
               ]
            },
            "unsupported":{
               "type":"boolean"
            },
            "disconnected":{
               "type":"boolean"
            },
            "error":{
               "type":"string"
            },
            "warning":{
               "type":"string"
            }
         }
      }
   }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Specified ESXi host is not available under specified vSphere instance.

Configuration with specified vCenter Server hostname does not exist.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

put /api/v1/vsphere/{vcHostname}/hosts/{esxiHost}

Update ESXi host configuration with the specified hostname in the specified vCenter Server.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

URI Parameters

vcHostname: required (string)
vCenter Server hostname
esxiHost: required (string)
Hostname of ESXi host

Body: application/json

{
  "configure":true,
  "syslogProtocol": "TCP"
}

Schema:

{
  "$schema": "http: //json-schema.org/draft-04/schema",
  "type":  "object",
  "properties": {
    "configure": {
      "type": "boolean",
      "description":"Indicates whether to configure the ESXi host or remove configuration."
    },
    "syslogProtocol": {
      "enum": [
        "udp",
        "tcp",
        "ssl"
      ],
      "description":"Syslog protocol used for configuring ESXi hosts. Default protocol is UDP."
    }
  },
  "required":  [
    "configure"
  ]
}

Response

HTTP status code 200

Successfully updated ESXI host configuration.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

The request was refused because it lacks valid authentication credentials. This can happen if the Authorization header was missing, or if it contained an invalid session ID.

Obtain a new session ID and retry the request, or make an unauthenticated request without the Authorization header.

Body: text/plain

Invalid session ID

HTTP status code 404

Specified ESXi host is not available under specified vSphere instance.

Configuration with specified vCenter Server hostname does not exist.

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```

/api/v1/vsphere/testconnection

post

post /api/v1/vsphere/testconnection

Test connection to the vCenter Server.

The API expects a request body sent in JSON format. Refer to the schema and example.

This is a supported API.

Request

Body: application/json

{
  "acceptCert" : true,
  "hostname":"example-vc.eng.vmware.com",
  "username":"exampleVCUsername",
  "password":"exampleVCPassword"
}

Schema:

{
  "$schema": "http: //json-schema.org/draft-04/schema",
  "type":  "object",
  "properties": {
    "acceptCert": {
      "type": "boolean",
      "description":"Automatically accept not trusted vCenter Server certificates. Default value is false"
    },
    "hostname":{
      "type":"string",
      "description":"The vCenter Server hostname"
    },
    "username":{
      "type":"string",
      "description":"The vCenter Server username"
    },
    "password":{
      "type":"string",
      "description":"The vCenter Server password"
    }
  },
  "required":  [
    "hostname",
    "username",
    "password"
  ]
}

Response

HTTP status code 200

Test successful.

HTTP status code 400

The request failed because the request body either did not contain valid JSON, or did not match the required JSON format.

Body: application/json

{
  "errorMessage": "Invalid request body.",
  "errorCode": "JSON_FORMAT_ERROR",
  "errorDetails": {
    "reason": "..."
  }
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "id": "#error",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    },
    "errorCode": {
      "type": "string",
      "enum": [
        "FIELD_ERROR",
        "TEST_ERROR",
        "JSON_FORMAT_ERROR",
        "LICENSE_ERROR",
        "VSPHERE_INTEGRATION_ERROR",
        "VROPS_INTEGRATION_ERROR",
        "UPGRADE_ERROR",
        "SEARCH_ERROR",
        "AGENT_ERROR",
        "RBAC_COMMON_ERROR",
        "RBAC_USERS_ERROR",
        "RBAC_GROUPS_ERROR",
        "RBAC_ADGROUPS_ERROR",
        "RBAC_DATASETS_ERROR",
        "RBAC_VIDM_GROUPS_ERROR",
        "SECURITY_ERROR",
        "DEPLOYMENT_ERROR",
        "SUPPORT_BUNDLE_ERROR",
        "LOAD_BALANCER_ERROR",
        "VIDM_ERROR",
        "QUERY_ERROR"
      ]
    },
    "errorDetails": {
      "id": "#errorDetailsName",
      "properties": {
        "errorCode": {
          "type": "string"
        },
        "reason": {
          "type": "string"
        }
      },
      "anyOf":[
        {"required" : ["errorCode"]},
        {"required" : ["reason"]}
      ]
    }
  }
}

HTTP status code 401

Invalid username or password.

Body: text/plain

Invalid session ID

HTTP status code 440

The request was refused because the session ID has expired. Obtain a new session ID from /api/v1/sessions.

Body: text/plain

Login Timeout

HTTP status code 495

SSL connection failed. vCenter Server certificate is not trusted. Use "acceptCert":true in request to automatically accept not trusted certificate.

HTTP status code 500

Internal error while processing the client request

Body: application/json

{
  "errorMessage": "The operation failed due to an internal error."
}

Schema:

{
  "$schema": "http://json-schema.org/draft-04/schema",
  "type": "object",
  "properties": {
    "errorMessage": {
      "type": "string"
    }
  },
  "required": [
    "errorMessage"
  ]
}

HTTP status code 502

Host connection problem.

HTTP status code 504

Host unreachable.

Security

This API requires authentication.

Headers

Authorization: (string)
The word Bearer followed by a single space and a session ID retrieved from /api/v1/sessions. The bearer token is an opaque string and should be sent as-is.
Example:
```
Authorization: Bearer abcdef12345678901234567890
```