With the notable exception of the authentication API calls (e.g. Login
or GetToken
), each API call must be authenticated. Authentication is performed using gRPC metadata when using the gRPC API, and HTTP Headers when using the REST API. There are two types of clients for the Panto API: Agents and Users. This documentation explains how to set up the credentials in your API call in each case.
Agent authentication is set-up automatically from the agent configuration. An agent authenticates using its API name as a Bearer token. The token is set from the configuration of panto-agent
at launch time, from a configuration file, command-line arguments or environment variables.
panto-agent --name=organizations/xCM3-ZaGQoOAaJbqQjcexg/agents/IPh0ffZcTV6FbwaEUR2ZhQ rpc.panto.app
If the agent name is found in the configuration database on the server, the agent will be authenticated.
“User authentication” describes all cases where API calls are performed on behalf of an actual user, registered in the database. This concerns all requests performed from a browser running the Panto frontend client, curl calls, automation scripts, etc. Since most of these cases go through the REST API, the examples will show authentication using HTTP/1.1 headers.
To be authenticated, a user must first Log In. The Login
RPC or the login
endpoint should be used. Logging in takes user credentials in the form of a username and a password. Upon successful login, a user session is created on server with a temporary API token, bound to the session. The token will be used to authenticate all further calls.
Login request:
POST /v1/login HTTP/1.1
Accept: application/json, */*
Content-Length: 62
Content-Type: application/json
Host: api.panto.app
{
"username": "hello@world.io"
"password": "helloworld",
}
HTTP/1.1 200 OK
Content-Length: 95
Content-Type: application/json
Date: Mon, 16 Dec 2019 12:23:12 GMT
Set-Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a; Expires=Tue, 17 Dec 2019 12:23:12 UTC; HttpOnly; Secure
{
"expires": "2019-12-17T12:23:12.132396Z",
"token": "djSbTqvOzGAa9kJH3hUU1rpmD4UmtyLgrrOm-L_h6l4"
}
The response contains 3 pieces of useful information:
token
which will be used to authenticate all further requests in the sessionHttpOnly
cookieGiven the sensitive nature of this data, it is highly recommended to only perform these calls over a secure connection.
Performing an authenticated call requires:
Authorization
headerCookie
header (automatically handled by the browser)List organizations request:
GET /v1/organizations HTTP/1.1
Accept: */*
Authorization: Bearer djSbTqvOzGAa9kJH3hUU1rpmD4UmtyLgrrOm-L_h6l4
Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a
Host: api.panto.app
List organizations response:
HTTP/1.1 200 OK
Content-Length: 118
Content-Type: application/json
Date: Mon, 16 Dec 2019 12:24:26 GMT
Set-Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a; Expires=Tue, 17 Dec 2019 12:24:26 UTC; HttpOnly; Secure
{
"next_page_token": "",
"organizations": [
{
"display_name": "Organization",
"name": "organizations/xCM3-ZaGQoOAaJbqQjcexg"
}
]
}
Note that the session is refreshed and expiration date is extended after each call. Sessions only time out after a pre-set period of inactivity.
A session token is a sensitive credential and must not be stored in LocalStorage or SessionStorage, to prevent XSS attacks. therefore, a way to retrieve a lost token is available, through the GetToken
RPC or the token
REST endpoint. The method uses the session ID in the secure cookie to retrieve the session token.
Get token request:
GET /v1/token HTTP/1.1
Accept: */*
Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a
Host: api.panto.app
Get token response:
HTTP/1.1 200 OK
Content-Length: 95
Content-Type: application/json
Date: Mon, 16 Dec 2019 13:07:38 GMT
Set-Cookie: SessionID=66dfac61-727e-4107-8ce1-002506821b5a; Expires=Tue, 17 Dec 2019 13:07:38 UTC; HttpOnly; Secure
{
"expires": "2019-12-17T13:07:38.150801Z",
"token": "djSbTqvOzGAa9kJH3hUU1rpmD4UmtyLgrrOm-L_h6l4"
}
Name | Type | Description / Example |
---|---|---|
username |
string |
A unique identifier for the user, in the form of a user’s email address |
password |
string |
A password for the user, in plaintext |
None.
A valid session ID must be set as a SessionID
cookie.
Name | Type | Description / Example |
---|---|---|
token |
string |
An opaque token, bound to the newly created session, used for further authentication of the user |
expires |
timestamp |
The date of expiration of the session, if no activity occurs until then |
Name | Type | Description / Example |
---|---|---|
name |
string |
organization/ODEwMzAwMjktYzQ1ZS00OT - the “basename” of the organization is the base64-encoded UUID (without padding) |
uuid |
bytes |
a 16-byte UUID |
display_name |
string |
Pantomath - a name for the organization - can be used as a “user-friendly” display name in the Web UI |
ListOrganizations(ListOrganizationsRequest) -> (ListOrganizationsResponse)
ListOrganizationsRequest
page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListOrganizationsResponse
organizations
- repeated Organization
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations
GetOrganization(GetOrganizationRequest) -> (Organization)
GetOrganizationRequest
name
: the relative resource name of the organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
GET /v1/organizations/<name>
CreateOrganization(CreateOrganizationRequest) -> (Organization)
CreateOrganizationRequest
organization
: the Organization
to create, excluding name
and uuid
which will be generated by the serverPOST /v1/organizations
UpdateOrganization(UpdateOrganizationRequest) -> (Organization)
UpdateOrganizationRequest
organization
(mandatory): an Organization
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations
DeleteOrganization(DeleteOrganizationRequest) -> ()
DeleteOrganizationRequest
name
DELETE /v1/organizations/<name>
Name | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw - the “basename” of the agent is the base64-encoded UUID (without padding) |
uuid |
bytes |
a 16-byte UUID |
display_name |
string |
agent.pantomath.io - a “user-friendly” display name in the Web UI - recommended to use a FQDN for the agent |
last_activity |
timestamp |
Timestamp of the last time the agent connected on the server |
ListAgents(ListAgentsRequest) -> (ListAgentsResponse)
ListAgentsRequest
parent
(mandatory): the relative resource name of the parent Organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListAgentsResponse
agents
- repeated Agent
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/agents
GetAgent(GetAgentRequest) -> (Agent)
GetAgentRequest
name
: the relative resource name of the agent, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw
GET /v1/organizations/<parent>/agents/<name>
CreateAgent(CreateAgentRequest) -> (Agent)
CreateAgentRequest
agent
: the Agent
to create, excluding name
, uuid
and last_activity
which will be generated by the serverPOST /v1/organizations/<parent>/agents
UpdateAgent(UpdateAgentRequest) -> (Agent)
UpdateAgentRequest
agent
(mandatory): an Agent
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations/<parent>/agents
DeleteAgent(DeleteAgentRequest) -> ()
DeleteAgentRequest
name
DELETE /v1/organizations/<parent>/agents/<name>
Name | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/checks/qq4ugtA8Eee0yBQQn9hOqw - the “basename” of the check is the base64-encoded UUID (without padding) |
uuid |
bytes |
a 16-byte UUID |
target |
string |
The relative resource name of a Target |
probe |
string |
The relative resource name of a Probe |
type |
string |
Type of state ({threshold , trend , history }) must be provided along with configuration |
configuration |
string |
Values used in combination with the state_definition (JSON object) must be provided along with type |
children |
Object |
The nested children from a ListChecksRequest or a GetCheck’s children_mask field. |
children.target |
Target |
The Target on which the Probe is applied |
children.probe |
Probe |
The Probe on which the Target is applied |
ListChecks(ListChecksRequest) -> (ListChecksResponse)
ListChecksRequest
parent
(mandatory): the relative resource name of the parent Organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
target
: optional constraint (should be a series of relative resource names of Target
)probe
: optional constraint (should be a series of relative resource names of Probe
)children_mask
- a FieldMask containing the names of the related resources to nest into the returned Checks, e.g. target, probe. Leave empty for no nested resources.page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListChecksResponse
checks
- repeated Check
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/checks
GetCheck(GetCheckRequest) -> (Check)
GetChecktRequest
name
: the relative resource name of the check, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/checks/qq4ugtA8Eee0yBQQn9hOqw
children_mask
- a FieldMask containing the names of the related resources to nest into the returned Check, e.g. target, probe. Leave empty for no nested resources.GET /v1/organizations/<parent>/checks/<name>
CreateCheck(CreateCheckRequest) -> (Check)
CreateCheckRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
check
: the Check
to create, excluding name
and uuid
which will be generated by the serverPOST /v1/organizations/<parent>/checks
UpdateCheck(UpdateCheckRequest) -> (Check)
UpdateCheckRequest
check
(mandatory): an Check
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations/<parent>/checks
DeleteCheck(DeleteCheckRequest) -> ()
DeleteCheckRequest
name
: the relative resource name of the check, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/checks/qq4ugtA8Eee0yBQQn9hOqw
DELETE /v1/organizations/<parent>/checks/<name>
Name | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw/probeconfigurations/j7e5DMTaRAGZzfpkZpdHVw - the “basename” of the configuration is the base64-encoded UUID (without padding) |
check |
string |
The relative resource name of a Check |
target |
Target |
The relative resource Target |
configuration |
string |
A JSON string of the parameters to give to the probe |
schedule |
Duration | The period between executions of the probe |
ListProbeConfigurations(ListProbeConfigurationsRequest) -> (ListProbeConfigurationsResponse)
ListProbeConfigurationsRequest
parent
(mandatory): the relative resource name of the parent agent, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/agents/qq4ugtA8Eee0yBQQn9hOqw
with_target
: flag to include the target
field in the responsepage_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListProbeConfigurationsResponse
probeconfigurations
- repeated ProbeConfiguration
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/agents/<parent>/probeconfigurations
ProbeConfiguration
s of a specific Agent
from the Web UIGetProbeConfiguration(GetProbeConfigurationRequest) -> (ProbeConfiguration)
GetProbeConfigurationRequest
name
(mandatory) : the relative resource name of the probe configuration, e.g. organizations/<parent>/agents/qq4ugtA8Eee0yBQQn9hOqw/probeconfigurations/j7e5DMTaRAGZzfpkZpdHVw
with_target
: flag to include the target
field in the responseGET /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
ProbeConfiguration
of a specific Agent
for a specific Probe
applied to a specific Target
in the Web UICreateProbeConfiguration(CreateProbeConfigurationRequest) -> (ProbeConfiguration)
CreateProbeConfigurationRequest
parent
(mandatory): the relative resource name of the parent agentprobeconfiguration
: the ProbeConfiguration
to create, excluding name
which will be generated by the serverPOST /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
ProbeConfiguration
for a specific Probe
applied to a specific Target
by a specific Agent
in the Web UIUpdateProbeConfiguration(UpdateProbeConfigurationRequest) -> (ProbeConfiguration)
UpdateProbeConfigurationRequest
probeconfiguration
(mandatory): a ProbeConfiguration
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
ProbeConfiguration
for a specific Probe
applied to a specific Target
by a specific Agent
in the Web UIDeleteProbeConfiguration(DeleteProbeConfigurationRequest) -> ()
DeleteProbeConfigurationRequest
name
(mandatory)DELETE /v1/organizations/<parent>/agents/<parent>/probeconfigurations/<name>
ProbeConfiguration
for a specific Probe
applied to a specific Target
from a specific Agent
in the Web UIName | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/targets/GNXPRsSwTUOhz5R2BjfrAQ - the “basename” of the agent is the base64-encoded UUID (without padding) |
uuid |
bytes |
a 16-byte UUID |
address |
string |
target.pantomath.io - a FQDN for the target - can be used as a “user-friendly” display name in the Web UI |
note |
string |
Free note for the target |
tags |
repeated Tag |
Associated Tag basenames |
ListTargets(ListTargetsRequest) -> (ListTargetsResponse)
ListTargetsRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListTargetsResponse
targets
- repeated Target
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/targets
GetTarget(GetTargetRequest) -> (Target)
GetTargetRequest
name
: the relative resource name of the target, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/targets/GNXPRsSwTUOhz5R2BjfrAQ
GET /v1/organizations/<parent>/targets/<name>
CreateTarget(CreateTargetRequest) -> (Target)
CreateTargetRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
target
: the Target
to create, excluding name
and uuid
which will be generated by the serverPOST /v1/organizations/<parent>/targets
curl
UpdateTarget(UpdateTargetRequest) -> (Target)
UpdateTargetRequest
target
(mandatory): the Target
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)POST /v1/organizations/<parent>/targets
curl
DeleteTarget(DeleteTargetRequest) -> ()
DeleteTargetRequest
name
: the relative resource name of the targetDELETE /v1/organizations/<parent>/targets/<name>
curl
A Probe
is a description of a probe in the system. It contains a unique name for the probe, and
Name | Type | Description / Example |
---|---|---|
name |
string |
probes/ping - since probes should be uniquely recognizable by their name, so that the agent knows which one to create, we can use this name as unique identifier |
probe_name |
string |
ping - the unique short name of the probe, identical to the basename of name , used by the agent to find in the registry |
display_name |
string |
Ping - A user-friendly name to be displayed in user-facing text |
description |
string |
A user-friendly description of the probe, to be shown to users, e.g. when selecting a probe, or reading contextual help |
configuration_template |
repeated ProbeParameter |
the list of parameters to configure this probe |
metrics |
repeated Metric |
the list of metrics returned by this probe |
graphs |
repeated Graph |
the list of graphs to render this probe |
ListProbes(ListProbesRequest) -> (ListProbesResponse)
ListProbesRequest
page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListProbesResponse
probes
- repeated Probe
next_page_token
, page_token
to be used to get the next pageGET /v1/probes
ProbeConfiguration
in the Web UI, the client needs to fetch all the Probe
descriptions to display (e.g. as a drop-down probe list)GetProbe(GetProbeRequest) -> (Probe)
GetProbeRequest
name
: the relative resource name of the probe, e.g. probes/ping
GET /v1/targets/<name>
ProbeConfiguration
in the Web UI, the client needs to fetch the Probe
description to display optionsName | Type | Description / Example |
---|---|---|
name |
string |
The name of the parameter, used as key in a JSON |
type |
string |
A Protobuf well-known type, see https://developers.google.com/protocol-buffers/docs/reference/google.protobuf |
description |
string |
The plain text description of the probe parameter |
mandatory |
bool |
Whether the ProbeParameter is mandatory or not |
Name | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/alerts/JnsWcAb3R72wkLX_tAbQFQ - the “basename” of the alert is the base64-encoded UUID (without padding) |
checks |
repeated string |
The relative resource name of the Check the alert is linked to |
channel |
string |
The relative resource name of the Channel |
type |
string |
Type of alert |
configuration |
string |
Configuration parameters (JSON string) |
children |
Object |
The nested children from a ListAlertsRequest or a GetAlert’s children_mask field. |
children.checks |
repeated Check |
The list of Check on which the Alert is linked to |
ListAlerts(ListAlertsRequest) -> (ListAlertsResponse)
ListAlertsRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
children_mask
- a FieldMask containing the names of the related resources to nest into the returned Alerts, e.g. checks. Leave empty for no nested resources.page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListAlertsResponse
alerts
- repeated Alert
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/alerts
Alert
s of a specific Organization
from the Web UIGetAlert(GetAlertRequest) -> (Alert)
GetAlertRequest
name
(mandatory) : the relative resource name of the alert, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/alerts/JnsWcAb3R72wkLX_tAbQFQ
children_mask
- a FieldMask containing the names of the related resources to nest into the returned Alerts, e.g. checks. Leave empty for no nested resources.GET /v1/organizations/<parent>/alerts/<name>
Alert
of a specific Organization
in the Web UICreateAlert(CreateAlertRequest) -> (Alert)
CreateAlertRequest
parent
(mandatory): the relative resource name of the parent organizationalert
: the Alert
to create, excluding name
which will be generated by the serverPOST /v1/organizations/<parent>/alerts
Alert
link to Check
s in the Web UIUpdateAlert(UpdateAlertRequest) -> (Alert)
UpdateAlertRequest
alert
(mandatory): an Alert
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations/<parent>/alerts/<name>
Alert
link to Check
s in the Web UIDeleteAlert(DeleteAlertRequest) -> ()
DeleteAlertRequest
name
(mandatory)DELETE /v1/organizations/<parent>/alerts/<name>
Alert
in the Web UIName | Type | Description / Example |
---|---|---|
name |
string |
channeltypes/email - the “basename” of the channeltype is the label |
label |
string |
Label of channeltype |
configuration |
repeated Parameter |
Available configuration parameters |
ListChannelTypes(ListChannelTypesRequest) -> (ListChannelTypesResponse)
ListChannelTypesRequest
page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListChannelTypesResponse
channeltypes
- repeated ChannelType
next_page_token
, page_token
to be used to get the next pageGET /v1/channeltypes
ChannelType
s before creating a Channel
from the Web UIGetChannelType(GetChannelTypeRequest) -> (ChannelType)
GetChannelTypeRequest
name
(mandatory) : the relative resource name of the ChannelType
, e.g. channeltypes/Q3qK6T0cTsSOf4RlRz8qRw
GET /v1/channeltypes/<name>
ChannelType
in the Web UIName | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/channels/Q3qK6T0cTsSOf4RlRz8qRw - the “basename” of the channel is the base64-encoded UUID (without padding) |
channel_type |
string |
The “basename” of the channeltype |
configuration |
string |
Configuration parameters (JSON string) |
children |
Object |
The nested children from a ListChannelsRequest or a GetChannel’s children_mask field. |
children.channel_type |
ChannelType |
The Target on which the Probe is applied |
ListChannels(ListChannelsRequest) -> (ListChannelsResponse)
ListChannelsRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
children_mask
- a FieldMask containing the names of the related resources to nest into the returned Channels, e.g. channel_type. Leave empty for no nested resources.page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListChannelsResponse
channels
- repeated Channel
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/channels
Channel
s of a specific Organization
from the Web UIGetChannel(GetChannelRequest) -> (Channel)
GetChannelRequest
name
(mandatory) : the relative resource name of the alert, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT/channels/Q3qK6T0cTsSOf4RlRz8qRw
children_mask
- a FieldMask containing the names of the related resources to nest into the returned Channels, e.g. channel_type. Leave empty for no nested resources.GET /v1/organizations/<parent>/channels/<name>
Channel
of a specific Organization
in the Web UICreateChannel(CreateChannelRequest) -> (Channel)
CreateChannelRequest
parent
(mandatory): the relative resource name of the parent organizationchannel
: the Channel
to create, excluding name
which will be generated by the serverPOST /v1/organizations/<parent>/channels
Channel
link to Check
s in the Web UIUpdateChannel(UpdateChannelRequest) -> (Channel)
UpdateChannelRequest
channel
: an Channel
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations/<parent>/channels/<name>
Channel
in the Web UIDeleteChannel(DeleteChannelRequest) -> ()
DeleteChannelRequest
name
(mandatory)DELETE /v1/organizations/<parent>/channels/<name>
Channel
in the Web UIName | Type | Description / Example |
---|---|---|
check |
string |
The relative resource name of the Check that this resulted from |
agent |
string |
The relative resource name of an Agent |
probe_configuration |
string |
The relative resource name of a ProbeConfiguration |
timestamp |
Timestamp |
The time at which the probe was executed. The time is always localized to UTC coordinates. |
fields |
map<string, Any> |
The fields measured by the probe |
tags |
map<string, string> |
The string tags associated with this result |
error |
bool |
true if the probe execution encountered an error |
error_message |
string |
Detailed message about the error that occured |
Result
has noname
, as it would be much too complex to give and keep unique names for each datapoint, and probably not very useful. Clients should perform queries, and deal with the results client-side.
QueryResults(QueryResultsRequest) -> (QueryResultsResponse)
ListResults
?
Field
s are not a standard “named” resourceQueryResultsRequest
check
- the relative resource name of the Check
agent
- the relative resource name of the Agent
start_time
- no results with a timestamp before this will be returned, beginning of time if missingend_time
- no results with a timestamp after this will be returned, ends at latest result if missingtags
- the tags to be present in the returned results (TODO: filter tags out)order_by
- ASCENDING
or DESCENDING
, order by ascending or descending timepage_size
- the maximum number of items to return, server chooses if missingpage_token
- the client uses this field to request a specific page of the list results (see pagination)QueryResultsResponse
results
- repeated Result
next_page_token
- an opaque base64-encoded protobuf structure used to query the next page (see pagination)POST /v1/results/query
AddResults(AddResultsRequest) -> (AddResultsResponse)
AddResultsRequest
results
- repeated Result
AddResultsResponse
results
- repeated Result
POST /v1/results/add
results
from Probes
executions to the serverName | Type | Description / Example |
---|---|---|
check |
string |
The relative resource name of the Check that this state resulted from |
agent |
string |
The relative resource name of the Agent that this state resulted from |
probe_configuration |
string |
The relative resource name of the ProbeConfiguration that this state resulted from |
timestamp |
Timestamp | The time at which the state was evaluated. The time is always localized to UTC coordinates. |
type |
StateType | The type of the state : {UNKNOWN , OK , WARNING , CRITICAL } |
reason |
string |
A description of the cause of this state (can be empty) |
children |
Object |
The nested children from a QueryStatesRequest ’s children_mask field. |
children.check |
Check |
The Check that this state resulted from |
children.agent |
Agent |
The Agent that this state resulted from |
children.probe_configuration |
ProbeConfiguration |
The ProbeConfiguration that this state resulted from |
QueryStates(QueryStatesRequests) -> (QueryStatesResponse)
QueryStatesRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
probe_configurations
- repeated ProbeConfiguration
a list of ProbeConfiguration names to return current states for.children_mask
- a FieldMask
containing the names of the related resources to nest into the returned States
, e.g. check
, agent
, probe_configuration
. Leave empty for no nested resources.page_size
- the maximum number of items to return, server chooses if missingpage_token
- the client uses this field to request a specific page of the list results (see pagination)QueryStatesResponse
states
- repeated State
The states of all corresponding checksnext_page_token
- an opaque base64-encoded protobuf structure used to query the next page (see pagination)POST /v1/organizations/<parent>/states/query
Name | Type | Description / Example |
---|---|---|
check |
string |
The relative resource name of the Check that this notification is about |
agent |
string |
The relative resource name of the Agent that this notification is about |
timestamp |
Timestamp | The time at which the notification was issued. The time is always localized to UTC coordinates. |
event |
EventType | The type of the notification : {NOTIFIED , ACKNOWLEDGED , SNOOZED } |
children |
Object |
The nested children from a QueryStatesRequest ’s children_mask field. |
children.check |
Check |
The Check that this state resulted from |
children.agent |
Agent |
The Agent that this state resulted from |
QueryNotifications(QueryNotificationsRequests) -> (QueryNotificationsResponse)
QueryNotificationsRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
probe_configurations
- repeated ProbeConfiguration
a list of the ProbeConfiguration to return latest notification for.children_mask
- a FieldMask
containing the names of the related resources to nest into the returned States
, e.g. check
, agent
, probe_configuration
. Leave empty for no nested resources.page_size
- the maximum number of items to return, server chooses if missingpage_token
- the client uses this field to request a specific page of the list results (see pagination)QueryNotificationsResponse
notifications
- repeated Notification
The notification of all corresponding checks-agentsnext_page_token
- an opaque base64-encoded protobuf structure used to query the next page (see pagination)POST /v1/organizations/<parent>/notifications/query
AddNotifications(AddNotificationRequests) -> (Notification)
AddNotificationsRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
probe_configuration
- ProbeConfiguration
to add a notification for.event
- the type of event to update the notification to.POST /v1/organizations/<parent>/notifications/add
Name | Type | Description / Example |
---|---|---|
name |
string |
organizations/ODEwMzAwMjktYzQ1ZS00OT/tags/abced - the “basename” of the tag is the base64-encoded name (without padding) |
display_name |
string |
The effective name of the Tag (abcde ) |
note |
string |
Free text field associated withe the Tag (ABCDE servers ) |
color |
string |
RGB color associated with the Tag (#34495e ) |
ListTags(ListTagsRequest) -> (ListTagsResponse)
ListTagsRequest
parent
(mandatory): the relative resource name of the parent organization, e.g. organizations/ODEwMzAwMjktYzQ1ZS00OT
page_size
: maximum number of results to be returned by the serverpage_token
: an opaque base64-encoded protobuf structure used to query the next pageListTagsResponse
tags
- repeated Tag
next_page_token
, page_token
to be used to get the next pageGET /v1/organizations/<parent>/tags
Tag
s of a specific Organization
from the Web UICreateTag(CreateTagRequest) -> (Tag)
CreateTagRequest
parent
(mandatory): the relative resource name of the parent organizationtag
: the Tag
to create, excluding name
which will be generated by the serverPOST /v1/organizations/<parent>/tags
Tag
in the Web UIUpdateTag(UpdateTagRequest) -> (Tag)
UpdateTagRequest
tag
(mandatory): a Tag
containing the fields to updateupdate_mask
: FieldMask represents a set of symbolic field paths (if omitted, all fields will be updated)PUT /v1/organizations/<parent>/tags/<name>
Tag
in the Web UIDeleteTag(DeleteTagRequest) -> ()
DeleteTagRequest
name
(mandatory)DELETE /v1/organizations/<parent>/tags/<name>
Tag
in the Web UI