Skip to content
Browse endpoints

Metrics API

v1.0.0
Base URL

Authentication

5 endpoints

Register

Start user registration

post/auth/register

Initiates the user registration process. A verification code will be sent to the provided email address to complete the registration.

Request body

RegisterRequestobject
emailEmailAddressrequired

Primary email address for the account. Used for verification and notifications.

passwordStrongPasswordrequired

Secure password for the account.

Responses

204

Registration verification code sent

Errors

400

REGISTRATION_DISABLED

Registration is currently disabled

400

EMAIL_ALREADY_EXISTS

Email already exists

VerifyRegistration

Verify registration and create an account

post/auth/register/verify

Completes the account registration process by verifying the code sent to the account's email. Upon successful verification, the account is created and activated.

Request body

VerifyRegistrationRequestobject
emailEmailAddressrequired

The email address being verified.

codeVerificationCoderequired

The 6-digit verification code sent to the email address.

Responses

201

Account registered successfully

Accountobject
idstringrequired

Unique identifier for the account.

emailEmailAddressrequired

The primary email address of the account.

statusAccountStatusrequired

The current operational status of the account.

createdAtinteger:int64required

Timestamp when the account was created, in milliseconds since Unix epoch.

lastLoginAtinteger:int64

Timestamp of the last login, in milliseconds since Unix epoch.

isolatedAtinteger:int64

Timestamp when the account was isolated, if applicable.

scheduledDeletionAtinteger:int64

Timestamp when the account is scheduled for permanent deletion.

Errors

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

400

EMAIL_ALREADY_EXISTS

Email already exists

Login

Log in a user

post/auth/login

Authenticates a user using their credentials (email and password). Returns a JSON Web Token (JWT) and user information upon successful authentication.

Request body

LoginRequestobject
emailEmailAddressrequired

The email address associated with the account.

passwordPasswordInputrequired

The account password.

Responses

200

User logged in successfully

LoginResponseobject
tokenstringrequired

JWT access token used for authenticating subsequent requests.

Errors

400

INCORRECT_EMAIL_OR_PASSWORD

Incorrect email or password

RequestPasswordReset

Request password reset

post/auth/password/reset

Initiates a password reset for the specified account. If an account with the provided email exists, a verification code will be sent to that email address.

Request body

RequestPasswordResetRequestobject
emailEmailAddressrequired

The email address associated with the account to reset the password for.

Responses

204

Password reset verification code sent if the account exists

VerifyPasswordReset

Verify password reset

post/auth/password/reset/verify

Verifies the password reset code and sets a new password for the account.

Request body

VerifyPasswordResetRequestobject
emailEmailAddressrequired

The email address of the account.

codeVerificationCoderequired

The verification code sent to the email address.

passwordStrongPasswordrequired

The new password for the account.

Responses

204

Password reset

Errors

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

Account

7 endpoints

GetAccount

Get the authenticated account

get/v1/account

Retrieves the details of the currently authenticated account, including user information and account status.

Responses

200

Account details

Accountobject
idstringrequired

Unique identifier for the account.

emailEmailAddressrequired

The primary email address of the account.

statusAccountStatusrequired

The current operational status of the account.

createdAtinteger:int64required

Timestamp when the account was created, in milliseconds since Unix epoch.

lastLoginAtinteger:int64

Timestamp of the last login, in milliseconds since Unix epoch.

isolatedAtinteger:int64

Timestamp when the account was isolated, if applicable.

scheduledDeletionAtinteger:int64

Timestamp when the account is scheduled for permanent deletion.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

DeleteAccount

Start account deletion

delete/v1/account

Initiates the process of deleting the authenticated account. A verification code will be sent to the user's email to confirm the deletion.

Responses

204

Account deletion verification code sent

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

ChangePassword

Start password change

post/v1/account/password

Initiates the process of changing the account's password. A verification code will be sent to the user's email to confirm the password change.

Request body

ChangePasswordRequestobject
oldPasswordPasswordInputrequired

The current password of the account.

passwordStrongPasswordrequired

The new secure password for the account.

invalidateAllSessionsboolean

When true, all active sessions for the account are signed out once the password change is confirmed, including the current session.

Responses

204

Password change verification code sent

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

INCORRECT_PASSWORD

Incorrect password

VerifyChangePassword

Verify password change

post/v1/account/password/verify

Verifies the password change code and sets the new password for the account.

Request body

VerifyChangePasswordRequestobject
codeVerificationCoderequired

The verification code sent to the user's email address.

Responses

204

Password changed

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

VerifyDeleteAccount

Verify account deletion

post/v1/account/delete/verify

Verifies the account deletion code and schedules the account for permanent deletion.

Request body

VerifyDeleteAccountRequestobject
codeVerificationCoderequired

The verification code sent to confirm account deletion.

Responses

200

Account deletion scheduled

Accountobject
idstringrequired

Unique identifier for the account.

emailEmailAddressrequired

The primary email address of the account.

statusAccountStatusrequired

The current operational status of the account.

createdAtinteger:int64required

Timestamp when the account was created, in milliseconds since Unix epoch.

lastLoginAtinteger:int64

Timestamp of the last login, in milliseconds since Unix epoch.

isolatedAtinteger:int64

Timestamp when the account was isolated, if applicable.

scheduledDeletionAtinteger:int64

Timestamp when the account is scheduled for permanent deletion.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

RestoreAccount

Start account restore

post/v1/account/restore

Initiates the process of restoring an account that has been scheduled for deletion. A verification code will be sent to the user's email to confirm the restoration.

Responses

204

Account restore verification code sent

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

VerifyRestoreAccount

Verify account restore

post/v1/account/restore/verify

Verifies the account restore code and reactivates the account.

Request body

VerifyRestoreAccountRequestobject
codeVerificationCoderequired

The verification code sent to confirm account restoration.

Responses

200

Account restored

Accountobject
idstringrequired

Unique identifier for the account.

emailEmailAddressrequired

The primary email address of the account.

statusAccountStatusrequired

The current operational status of the account.

createdAtinteger:int64required

Timestamp when the account was created, in milliseconds since Unix epoch.

lastLoginAtinteger:int64

Timestamp of the last login, in milliseconds since Unix epoch.

isolatedAtinteger:int64

Timestamp when the account was isolated, if applicable.

scheduledDeletionAtinteger:int64

Timestamp when the account is scheduled for permanent deletion.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

Billing

3 endpoints

GetBillingSummary

Get billing summary

get/v1/billing

Retrieves the current month's billing estimate for the authenticated account.

Responses

200

Billing summary

BillingSummaryobject
periodStartinteger:int64required

Start of the current billing month in milliseconds since Unix epoch.

periodEndinteger:int64required

End of the current billing month in milliseconds since Unix epoch.

billingPlanBillingPlanrequired

Current billing plan for this account.

currencystringrequired

Currency used for all cent values.

usageCentsintegerrequired

Estimated gross usage before credits.

creditCentsintegerrequired

Remaining monthly account credit after current usage.

amountDueCentsintegerrequired

Estimated amount due after credits.

lineItemsBillingLineItem[]required

Billable resources included in the current month usage.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

ListBillingInvoices

List recent billing invoices

get/v1/billing/invoices

Lists recent paid invoices for the authenticated account.

Parameters

limitintegerquery

Responses

200

Recent billing invoices

BillingInvoicesResponseobject
invoicesBillingInvoiceSummary[]required

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

DownloadBillingInvoice

Create a billing invoice download

post/v1/billing/invoices/{invoiceId}/download

Returns a short-lived invoice download URL for the authenticated account.

Parameters

invoiceIdstringpathrequired

Responses

200

Billing invoice download

BillingInvoiceDownloadobject
urlstring:urirequired

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

Roles

6 endpoints

ListRoles

List authorization roles for the authenticated account

get/v1/auth/roles

Retrieves a list of all authorization roles associated with the currently authenticated account.

Required permissions

Service
auth
Access level
List
Resource type
role

Responses

200

Roles retrieved successfully

ListRolesResponseobject
rolesRole[]required

List of authorization roles.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

CreateRole

Create an authorization role

post/v1/auth/roles

Creates a new authorization role with a set of permissions (statements). The caller must hold every allowed permission included in the new role.

Required permissions

Service
auth
Access level
Create
Resource type
role

Request body

CreateRoleRequestobject
nameIdentifierNamerequired

Display name.

descriptionRoleDescription

Human-readable description.

statementsRoleStatement[]required

Authorization policy statements. Allowed statements must stay within the caller's effective permissions.

Responses

201

Role created successfully

Roleobject
nameIdentifierNamerequired

The unique name of the authorization role.

systembooleanrequired

Flag indicating if this is a built-in system role that cannot be modified.

descriptionRoleDescription

A human-readable description of the role's purpose.

statementsRoleStatement[]required

List of permission statements defining the role.

createdAtinteger:int64required

Timestamp when the role was created, in milliseconds since Unix epoch.

updatedAtinteger:int64required

Timestamp when the role was last updated, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

ROLE_NAME_ALREADY_EXISTS

Role name already exists

409

SYSTEM_ROLES_IMMUTABLE

System roles are immutable

400

ROLE_STATEMENT_UNKNOWN_TARGET

Role statement %s does not match any known authorization target

400

DUPLICATE_ROLE_STATEMENT

Role statement %s duplicates an earlier statement

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

ListAuthorizationPolicies

List authorization policies

get/v1/auth/roles/policies

Lists the backend authorization policy targets that can be used in custom role statements.

Required permissions

Service
auth
Access level
List
Resource type
role

Responses

200

Authorization policies retrieved successfully

ListAuthorizationPoliciesResponseobject
policiesAuthorizationPolicy[]required

Authorization policy targets available to custom roles.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

GetRole

Get an authorization role

get/v1/auth/roles/{roleName}

Retrieves the details of a specific authorization role by its name.

Required permissions

Service
auth
Access level
Read
Resource type
role

Parameters

roleNameIdentifierNamepathrequired

Authorization role name.

Responses

200

Role details

Roleobject
nameIdentifierNamerequired

The unique name of the authorization role.

systembooleanrequired

Flag indicating if this is a built-in system role that cannot be modified.

descriptionRoleDescription

A human-readable description of the role's purpose.

statementsRoleStatement[]required

List of permission statements defining the role.

createdAtinteger:int64required

Timestamp when the role was created, in milliseconds since Unix epoch.

updatedAtinteger:int64required

Timestamp when the role was last updated, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

UpdateRole

Update an authorization role

put/v1/auth/roles/{roleName}

Updates the description and statements of an existing authorization role. Role names are immutable. The caller must hold every allowed permission included in the updated role.

Required permissions

Service
auth
Access level
Write
Resource type
role

Parameters

roleNameIdentifierNamepathrequired

Authorization role name.

Request body

UpdateRoleRequestobject
descriptionRoleDescription

Human-readable description.

statementsRoleStatement[]required

Authorization policy statements. Allowed statements must stay within the caller's effective permissions.

Responses

200

Role updated successfully

Roleobject
nameIdentifierNamerequired

The unique name of the authorization role.

systembooleanrequired

Flag indicating if this is a built-in system role that cannot be modified.

descriptionRoleDescription

A human-readable description of the role's purpose.

statementsRoleStatement[]required

List of permission statements defining the role.

createdAtinteger:int64required

Timestamp when the role was created, in milliseconds since Unix epoch.

updatedAtinteger:int64required

Timestamp when the role was last updated, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

SYSTEM_ROLES_IMMUTABLE

System roles are immutable

404

RESOURCE_NOT_FOUND

Resource not found

400

ROLE_STATEMENT_UNKNOWN_TARGET

Role statement %s does not match any known authorization target

400

DUPLICATE_ROLE_STATEMENT

Role statement %s duplicates an earlier statement

DeleteRole

Delete an authorization role

delete/v1/auth/roles/{roleName}

Deletes an authorization role. A role cannot be deleted if it is still assigned to API access tokens, workspace members, or pending invitations.

Required permissions

Service
auth
Access level
Delete
Resource type
role

Parameters

roleNameIdentifierNamepathrequired

Authorization role name.

Responses

204

Role deleted successfully

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

SYSTEM_ROLES_IMMUTABLE

System roles are immutable

409

ROLE_IN_USE

Role is still assigned to one or more principals or pending invitations

Access tokens

4 endpoints

ListAccessTokens

List access tokens for the authenticated user

get/v1/auth/tokens

Retrieves a list of all API access tokens created for the currently authenticated account.

Required permissions

Service
auth
Access level
List
Resource type
token

Responses

200

Access tokens retrieved successfully

ListAccessTokensResponseobject
tokensAccessTokenSummary[]required

List of access token summaries for the account.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

CreateAccessToken

Create a new access token

post/v1/auth/tokens

Creates a new API access token with an assigned role. The caller must be allowed to create tokens, read the requested role, and hold every allowed permission in that role.

Required permissions

Service
auth
Access level
Create
Resource type
token
Service
auth
Access level
Read
Resource type
role

Request body

CreateAccessTokenRequestobject
namestring

A human-readable name for the new access token.

expiresInDaysinteger

The number of days after which the token should expire.

roleIdentifierNamerequired

The name of the authorization role to assign to the token. The caller must hold every allowed permission in this role.

Responses

201

Access token created successfully

CreateAccessTokenResponseobject
tokenstringrequired

The secret API access token value. This is only shown once upon creation.

tokenIdTokenIdrequired

Unique identifier for the access token, used for revocation.

namestring

Human-readable name for the token.

createdAtinteger:int64required

Timestamp when the token was created, in milliseconds since Unix epoch.

expiresAtinteger:int64

Timestamp when the token expires, in milliseconds since Unix epoch.

rolestring

The authorization role assigned to this token.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

EXPIRES_IN_DAYS_OUT_OF_RANGE

expiresInDays must be between 1 and 365

404

RESOURCE_NOT_FOUND

Resource not found

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

UpdateAccessToken

Update an access token

put/v1/auth/tokens/{tokenId}

Changes the role assigned to an API access token. The caller must be allowed to update the token, read the requested role, and hold every allowed permission in that role.

Required permissions

Service
auth
Access level
Write
Resource type
token
Service
auth
Access level
Read
Resource type
role

Parameters

tokenIdTokenIdpathrequired

Access token identifier.

Request body

UpdateAccessTokenRequestobject
roleIdentifierNamerequired

The new authorization role to assign to the token. The caller must hold every allowed permission in this role.

Responses

200

Access token updated successfully

AccessTokenSummaryobject
tokenIdTokenIdrequired

Unique identifier for the access token.

namestring

Human-readable name for the token.

createdAtinteger:int64required

Timestamp when the token was created, in milliseconds since Unix epoch.

lastUsedAtinteger:int64

Timestamp when the token was last used, in milliseconds since Unix epoch.

expiresAtinteger:int64

Timestamp when the token expires, in milliseconds since Unix epoch.

rolestring

The authorization role assigned to this token.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

DeleteAccessToken

Revoke an access token

delete/v1/auth/tokens/{tokenId}

Permanently revokes an API access token, making it invalid for further authentication.

Required permissions

Service
auth
Access level
Delete
Resource type
token

Parameters

tokenIdTokenIdpathrequired

Access token identifier.

Responses

204

Access token revoked

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

Workspaces

14 endpoints

ListWorkspaces

List available workspaces

get/v1/workspaces

Retrieves the workspaces available to the authenticated account.

Responses

200

Workspaces retrieved successfully

ListWorkspacesResponseobject
currentWorkspaceIdstringrequired

Workspace id selected by the current authentication principal.

workspacesWorkspaceSummary[]required

Workspaces available to the authenticated account.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

CreateWorkspace

Create a workspace

post/v1/workspaces

Creates a workspace owned by the authenticated account.

Request body

CreateWorkspaceRequestobject
nameDisplayIdentifierNamerequired

Workspace display name.

Responses

201

Workspace created successfully

WorkspaceSummaryobject
idstringrequired

Unique identifier for the workspace.

nameDisplayIdentifierNamerequired

Workspace display name.

ownerstringrequired

Account id of the workspace owner.

rolestringrequired

Effective role for the authenticated account in this workspace.

currentbooleanrequired

Whether this workspace is selected by the current authentication principal.

createdAtinteger:int64required

Timestamp when the workspace was created, in milliseconds since Unix epoch.

updatedAtinteger:int64required

Timestamp when the workspace was last updated, in milliseconds since Unix epoch.

scheduledDeletionAtinteger:int64

When set, the workspace is pending deletion and will be permanently removed at this time (milliseconds since Unix epoch). It can be restored until then.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_WORKSPACE_NAME

Workspace name must be between 1 and 128 non-whitespace characters

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

UpdateWorkspace

Update a workspace

put/v1/workspaces/{workspaceId}

Renames a workspace owned by the authenticated account.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Request body

UpdateWorkspaceRequestobject
nameDisplayIdentifierNamerequired

New workspace display name.

Responses

204

Workspace updated successfully

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_WORKSPACE_NAME

Workspace name must be between 1 and 128 non-whitespace characters

DeleteWorkspace

Delete a workspace

delete/v1/workspaces/{workspaceId}

Sends a verification code to confirm deletion of an owned workspace. Every account must keep access to at least one workspace, and the current workspace cannot be deleted.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Responses

204

Workspace deletion verification code sent

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

CANNOT_DELETE_LAST_WORKSPACE

Every account must have at least one workspace

409

CANNOT_DELETE_CURRENT_WORKSPACE

Current workspace cannot be deleted

VerifyDeleteWorkspace

Verify workspace deletion

post/v1/workspaces/{workspaceId}/delete/verify

Verifies the workspace deletion code and permanently deletes the owned workspace.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Request body

VerifyDeleteWorkspaceRequestobject
codeVerificationCoderequired

The verification code sent to confirm workspace deletion.

Responses

204

Workspace deleted successfully

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

CANNOT_DELETE_LAST_WORKSPACE

Every account must have at least one workspace

409

CANNOT_DELETE_CURRENT_WORKSPACE

Current workspace cannot be deleted

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

RestoreWorkspace

Start workspace restore

post/v1/workspaces/{workspaceId}/restore

Initiates restoring a workspace that has been scheduled for deletion. A verification code is sent to the owner's email to confirm the restoration.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Responses

204

Workspace restore verification code sent

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

VerifyRestoreWorkspace

Verify workspace restore

post/v1/workspaces/{workspaceId}/restore/verify

Verifies the workspace restore code and reactivates the workspace if it is still within the restore window.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Request body

VerifyRestoreWorkspaceRequestobject
codeVerificationCoderequired

The verification code sent to confirm workspace restore.

Responses

204

Workspace restored successfully

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

SelectWorkspace

Select a workspace

post/v1/workspaces/{workspaceId}/select

Selects an available workspace and returns a new JWT for subsequent requests.

Parameters

workspaceIdEntityIdpathrequired

Responses

200

Workspace selected successfully

LoginResponseobject
tokenstringrequired

JWT access token used for authenticating subsequent requests.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

CreateWorkspaceInvitation

Invite a workspace member

post/v1/workspaces/{workspaceId}/invitations

Creates an invitation for an email address to join the selected workspace.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Request body

CreateWorkspaceInvitationRequestobject
emailEmailAddressrequired

Email address to invite.

roleIdentifierNamerequired

Role to grant when the invitation is accepted.

Responses

202

Workspace invitation created successfully

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_WORKSPACE_INVITATION

Invalid workspace invitation

400

WORKSPACE_MEMBER_ALREADY_EXISTS

The invited account already has access to this workspace

400

WORKSPACE_INVITATION_ALREADY_PENDING

An invitation for this email address is already pending

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

404

RESOURCE_NOT_FOUND

Resource not found

ListWorkspaceMembers

List workspace members

get/v1/workspaces/{workspaceId}/members

Lists accepted members for an owned workspace.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

Responses

200

Workspace members retrieved successfully

ListWorkspaceMembersResponseobject
membersWorkspaceMember[]required

Accepted workspace members.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

UpdateWorkspaceMember

Update a workspace member

put/v1/workspaces/{workspaceId}/members/{accountId}

Changes the role assigned to an accepted workspace member.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

accountIdEntityIdpathrequired

Workspace member account identifier.

Request body

UpdateWorkspaceMemberRequestobject
roleIdentifierNamerequired

Role to assign to the workspace member.

Responses

200

Workspace member updated successfully

WorkspaceMemberobject
accountIdstringrequired

Account identifier for the workspace member.

emailstring:email

Email address for the workspace member.

rolestringrequired

Role assigned to the workspace member.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

RemoveWorkspaceMember

Remove a workspace member

delete/v1/workspaces/{workspaceId}/members/{accountId}

Removes an accepted member from an owned workspace. This is an owner-only account action and cannot be delegated through a workspace role.

Parameters

workspaceIdEntityIdpathrequired

Workspace identifier.

accountIdEntityIdpathrequired

Workspace member account identifier.

Responses

204

Workspace member removed successfully

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

GetWorkspaceInvitation

Get workspace invitation

get/workspace-invitations/{token}

Retrieves the workspace invitation addressed to the authenticated account. Returns 404 if the invitation does not exist, has expired, or is not addressed to the authenticated account.

Parameters

tokenstringpathrequired

Raw invitation token from the invitation URL.

Responses

200

Workspace invitation retrieved successfully

WorkspaceInvitationobject
workspaceIdEntityIdrequired

Workspace identifier.

workspaceNamestringrequired

Workspace display name.

emailstring:emailrequired

Invited email address.

rolestringrequired

Role granted when the invitation is accepted.

expiresAtinteger:int64required

Timestamp when the invitation expires, in milliseconds since Unix epoch.

expiredbooleanrequired

Whether the invitation has expired.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

AcceptWorkspaceInvitation

Accept workspace invitation

post/v1/workspace-invitations/{token}/accept

Accepts a workspace invitation for the authenticated account and returns a workspace-scoped JWT.

Parameters

tokenstringpathrequired

Raw invitation token from the invitation URL.

Responses

200

Workspace invitation accepted successfully

LoginResponseobject
tokenstringrequired

JWT access token used for authenticating subsequent requests.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

Metrics

6 endpoints

ListMetrics

List all metrics

get/v1/metrics

Retrieves a list of all available metrics that have been recorded.

Required permissions

Service
metrics
Access level
List
Resource type
metric

Parameters

maxResultsintegerquery

The maximum number of metrics to return in a single response page.

nextTokenstringquery

Pagination token to retrieve the next page of metrics for the same filters.

querystringquery

Case-insensitive text contained in the metric name.

dimensionsstring[]query

Dimension names that every returned metric must expose.

dimensionValuesstring[]query

Dimension values to match, formatted as 'name:value'. Multiple values for one name are ORed; different names are ANDed.

Responses

200

A page of available metrics

ListMetricsResponseobject
metricsMetric[]required
nextTokenstring

Token used for retrieving the next page of results.

totalCountinteger:int64required

The total number of metrics matching the current filters.

dimensionFacetsMetricDimensionFacet[]required

Workspace-wide dimension facets; value options are populated for selected dimensions.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_PAGINATION_TOKEN

Invalid pagination token

GetMetricData

Get metrics data

get/v1/metrics/{metricName}

Retrieves time-series data points for a specific metric, filtered by time range, resolution, and dimensions.

Required permissions

Service
metrics
Access level
Read
Resource type
metric

Parameters

metricNameMetricNamepathrequired

The unique name of the metric to retrieve data for.

resolutionResolutionquery

The granularity of the returned data points, in seconds. Must be a multiple of the metric's original resolution.

aggregationAggregationquery

The aggregation expression to apply to the data points within each resolution bucket.

startTimestampinteger:int64queryrequired

The beginning of the time range to query, in milliseconds since Unix epoch.

endTimestampinteger:int64query

The end of the time range to query, in milliseconds since Unix epoch. Defaults to the current time if not specified.

maxResultsintegerquery

The maximum number of data points to return in a single response page.

includeDimensionsstring[]query

Filter data points by these dimensions. Format each item as 'name:value'. Filters that match no data return an empty result.

excludeDimensionsstring[]query

Exclude data points that match these dimensions. Format each item as 'name:value'. Filters that match no data return an empty result.

nextTokenstringquery

Pagination token to retrieve the next page of results if the current result set is truncated.

Responses

200

A page of metric data points

GetMetricDataResponseobject
entriesDataPointResult[]

The list of retrieved data points.

nextTokenstring

Token used for retrieving the next page of results.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_PAGINATION_TOKEN

Invalid pagination token

400

START_TIME_AFTER_END_TIME

Start time must not be bigger than end time

400

INVALID_AGGREGATION

Invalid aggregation expression

400

INVALID_METRIC_QUERY

Invalid metric query

400

METRIC_QUERY_TIMESTAMP_TOO_OLD

Metric query start time is outside the retention window

400

METRIC_QUERY_TIMESTAMP_IN_FUTURE

Metric query end time must not be more than one minute in the future

404

RESOURCE_NOT_FOUND

Resource not found

409

RESOURCE_DELETION_IN_PROGRESS

A previous deletion of this resource is still in progress

PutMetricData

Submit metrics data

post/v1/metrics/{metricName}

Publishes data points for a specific metric. Data points can include dimensions and values.

Required permissions

Service
metrics
Access level
Write
Resource type
metric

Parameters

metricNameMetricNamepathrequired

Metric name.

Request body

PutMetricDataRequestobject
entriesDataPoint[]required

A list of 1 to 1000 data points to be published.

Responses

202

Metrics data accepted

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

ENTRY_TIMESTAMP_TOO_OLD

Entry timestamp must not be older than 24 hours

400

ENTRY_TIMESTAMP_IN_FUTURE

Entry timestamp must not be in the future

400

INVALID_METRIC_DATA

%s

400

DUPLICATE_DIMENSION_NAME

Duplicate dimension name: %s

400

ENTRY_REQUIRES_VALUE_OR_STATISTIC_SET

Entry must include exactly one of value or statisticSet

400

STATISTIC_SET_INCOMPLETE

statisticSet must include avg, min, max, and sampleCount

400

STATISTIC_SET_INVALID_RANGE

statisticSet must satisfy min <= avg <= max

400

TOO_MANY_DIMENSIONS

Too many dimensions. Limit is %s

400

TOO_MANY_DIMENSION_COMBINATIONS

Too many dimension combinations. Limit is %s

409

RESOURCE_UPDATED_CONCURRENTLY

Resource was updated by another process

DeleteMetric

Delete metric

delete/v1/metrics/{metricName}

Deletes all data associated with a specific metric.

Required permissions

Service
metrics
Access level
Delete
Resource type
metric

Parameters

metricNameMetricNamepathrequired

Metric name.

Responses

204

Metric deleted

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

DeleteDimension

Delete dimension metadata from a metric

delete/v1/metrics/{metricName}/dimensions/{dimensionName}

Removes a specific dimension from the metadata of a metric. Note that this doesn't necessarily delete the data points associated with this dimension immediately, but it removes it from the list of dimensions for the metric.

Required permissions

Service
metrics
Access level
Delete
Resource type
metric

Parameters

metricNameMetricNamepathrequired

Metric name.

dimensionNamestringpathrequired

Dimension name.

Responses

204

Dimension metadata deleted

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

409

RESOURCE_UPDATED_CONCURRENTLY

Resource was updated by another process

GetDimensionValues

Get available values for a dimension

get/v1/metrics/{metricName}/dimensions/{dimensionName}/values

Retrieves all unique values recorded for a specific dimension of a metric.

Required permissions

Service
metrics
Access level
List
Resource type
metric

Parameters

metricNameMetricNamepathrequired

Metric name.

dimensionNamestringpathrequired

Dimension name.

Responses

200

List of dimension values

GetDimensionValuesResponseobject
valuesstring[]

The list of unique values for the requested dimension.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

Dashboards

6 endpoints

ListDashboards

List all dashboards for the authenticated user

get/v1/dashboards

Retrieves a list of all dashboards created by the currently authenticated user.

Required permissions

Service
metrics
Access level
List
Resource type
dashboard

Parameters

maxResultsintegerquery

The maximum number of dashboards to return in a single response page.

nextTokenstringquery

Pagination token to retrieve the next page of dashboards if the current result set is truncated.

Responses

200

List of dashboards

ListDashboardsResponseobject
dashboardsDashboardSummary[]

The list of dashboard summaries.

nextTokenstring

Pagination token to retrieve the next set of dashboards.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_PAGINATION_TOKEN

Invalid pagination token

CreateDashboard

Create a new dashboard

post/v1/dashboards

Creates a new dashboard with a specified configuration of charts and variables.

Required permissions

Service
metrics
Access level
Create
Resource type
dashboard

Request body

CreateDashboardRequestobject
nameDisplayIdentifierNamerequired

Human-readable name of the dashboard.

autoRefreshEnabledboolean

Flag to enable automatic refreshing.

refreshIntervalMsinteger

Automatic refresh interval in milliseconds (5s to 5min).

Responses

201

Dashboard created

Dashboardobject
idstringrequired

Unique identifier for the dashboard.

nameDisplayIdentifierNamerequired

Human-readable name of the dashboard.

chartsChartConfig[]required

List of chart configurations that make up the dashboard.

autoRefreshEnabledboolean

Flag to enable or disable automatic data refreshing for the dashboard.

refreshIntervalMsinteger

The interval in milliseconds at which the dashboard data is automatically refreshed.

createdAtinteger:int64

Timestamp when the dashboard was created, in milliseconds since Unix epoch.

updatedAtinteger:int64

Timestamp when the dashboard was last updated, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

400

DASHBOARD_REFRESH_INTERVAL_REQUIRED

refreshIntervalMs is required when autoRefreshEnabled is true

CreateDashboardEmbed

Generate public iframe embed code for a dashboard

post/v1/dashboards/{dashboardId}/embed

Generates a signed URL or token that allows a dashboard to be embedded in an external website via an iframe.

Required permissions

Service
metrics
Access level
Read
Resource type
dashboard
Service
auth
Access level
Create
Resource type
role
Service
auth
Access level
Create
Resource type
token

Parameters

dashboardIdEntityIdpathrequired

Dashboard identifier.

Responses

201

Dashboard embed token created

CreateDashboardEmbedResponseobject
tokenstringrequired

The specialized access token for the embedded view.

tokenIdTokenIdrequired

Unique identifier for the embed token.

rolestringrequired

The restricted authorization role generated for this embed.

iframestringrequired

Ready-to-use HTML iframe snippet for embedding the dashboard.

expiresAtinteger:int64required

Timestamp when the embed access expires, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

GetDashboard

Get a dashboard by id

get/v1/dashboards/{dashboardId}

Retrieves the full configuration and metadata of a specific dashboard by its ID.

Required permissions

Service
metrics
Access level
Read
Resource type
dashboard

Parameters

dashboardIdEntityIdpathrequired

Dashboard identifier.

Responses

200

Dashboard details

Dashboardobject
idstringrequired

Unique identifier for the dashboard.

nameDisplayIdentifierNamerequired

Human-readable name of the dashboard.

chartsChartConfig[]required

List of chart configurations that make up the dashboard.

autoRefreshEnabledboolean

Flag to enable or disable automatic data refreshing for the dashboard.

refreshIntervalMsinteger

The interval in milliseconds at which the dashboard data is automatically refreshed.

createdAtinteger:int64

Timestamp when the dashboard was created, in milliseconds since Unix epoch.

updatedAtinteger:int64

Timestamp when the dashboard was last updated, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

UpdateDashboard

Update a dashboard

put/v1/dashboards/{dashboardId}

Updates the configuration (charts, variables, name) of an existing dashboard.

Required permissions

Service
metrics
Access level
Read
Resource type
dashboard
Service
metrics
Access level
Write
Resource type
dashboard
Service
metrics
Access level
Read
Resource type
metric

Parameters

dashboardIdEntityIdpathrequired

Dashboard identifier.

Request body

UpdateDashboardRequestobject
nameDisplayIdentifierName

Human-readable name of the dashboard.

chartsChartConfig[]

The updated list of chart configurations for the dashboard.

autoRefreshEnabledboolean

Flag to enable automatic refreshing.

refreshIntervalMsinteger

Automatic refresh interval in milliseconds (5s to 5min).

Responses

200

Dashboard updated

Dashboardobject
idstringrequired

Unique identifier for the dashboard.

nameDisplayIdentifierNamerequired

Human-readable name of the dashboard.

chartsChartConfig[]required

List of chart configurations that make up the dashboard.

autoRefreshEnabledboolean

Flag to enable or disable automatic data refreshing for the dashboard.

refreshIntervalMsinteger

The interval in milliseconds at which the dashboard data is automatically refreshed.

createdAtinteger:int64

Timestamp when the dashboard was created, in milliseconds since Unix epoch.

updatedAtinteger:int64

Timestamp when the dashboard was last updated, in milliseconds since Unix epoch.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

409

RESOURCE_UPDATED_CONCURRENTLY

Resource was updated by another process

400

DUPLICATE_CHART_VARIABLE_NAME

Duplicate chart variable name: %s

400

DUPLICATE_CHART_ID

Duplicate chart id: %s

400

CHART_ROW_INVALID

Chart must fit within dashboard rows 0 through 3599

400

CHART_COLUMN_INVALID

Chart column must be between 0 and 23

400

CHART_COL_SPAN_INVALID

Chart colSpan must be between 1 and 24

400

CHART_ROW_SPAN_INVALID

Chart rowSpan must be between 1 and 36

400

CHART_EXCEEDS_DASHBOARD_WIDTH

Chart exceeds dashboard width

400

CHARTS_OVERLAP

Charts overlap: %s and %s

400

INVALID_DASHBOARD_FILTER

Invalid dimension filter at index %s for variable: %s

400

DUPLICATE_DASHBOARD_FILTER

Duplicate dimension filter for variable: %s

400

CONTRADICTORY_DASHBOARD_FILTER

Contradictory dimension filters for variable: %s

400

INVALID_DASHBOARD_TIME_RANGE

Invalid time range for chart: %s

400

CHART_VARIABLE_TYPE_REQUIRED

Chart variable type is required for: %s

400

CHART_VARIABLE_VISIBLE_REQUIRED

Chart variable visible is required for: %s

400

METRIC_VARIABLE_METRIC_NAME_REQUIRED

Metric variable metricName is required for: %s

400

UNSUPPORTED_CHART_VARIABLE_TYPE

Unsupported chart variable type: %s

400

EXPRESSION_VARIABLE_EXPRESSION_REQUIRED

Expression variable expression is required for: %s

400

INVALID_EXPRESSION

Invalid expression

400

INVALID_NUMERIC_EXPRESSION

Invalid numeric expression

400

MISMATCHED_EXPRESSION_PARENTHESES

Mismatched parentheses in expression

400

MISSING_EXPRESSION_OPERAND

Missing operand for operator %s

400

MISSING_EXPRESSION_OPERANDS

Missing operands for operator %s

400

INVALID_EXPRESSION_TOKEN

Invalid token in expression: %s

400

CYCLIC_DASHBOARD_VARIABLE_DEPENDENCY

Cyclic dashboard variable dependency detected at: %s

400

DASHBOARD_REFRESH_INTERVAL_REQUIRED

refreshIntervalMs is required when autoRefreshEnabled is true

400

DASHBOARD_REFRESH_INTERVAL_TOO_FAST

refreshIntervalMs must be at least the finest chart resolution of %s seconds

DeleteDashboard

Delete a dashboard

delete/v1/dashboards/{dashboardId}

Permanently deletes a dashboard.

Required permissions

Service
metrics
Access level
Delete
Resource type
dashboard

Parameters

dashboardIdEntityIdpathrequired

Dashboard identifier.

Responses

204

Dashboard deleted

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

Alarms

6 endpoints

ListAlarms

List all alarms

get/v1/alarms

Retrieves a list of all alarms configured for the authenticated account.

Required permissions

Service
metrics
Access level
List
Resource type
alarm

Parameters

maxResultsintegerquery

The maximum number of alarms to return in a single response page.

nextTokenstringquery

Pagination token to retrieve the next page of alarms if the current result set is truncated.

querystringquery

Case-insensitive text contained in the alarm name.

statusesAlarmStatus[]query

The alarm statuses to return. Missing or empty selects all statuses.

Responses

200

List of alarms

ListAlarmsResponseobject
alarmsAlarmSummary[]

The list of alarm summaries.

nextTokenstring

Pagination token to retrieve the next set of alarms.

totalCountinteger:int64required

The number of alarms matching the query and selected status.

statusCountsAlarmStatusCountsrequired

Alarm counts by status for the current query, before status filtering.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_PAGINATION_TOKEN

Invalid pagination token

ListAlarmHistory

List alarm history

get/v1/alarms/{alarmName}/history

Retrieves status transition history for a specific alarm.

Required permissions

Service
metrics
Access level
Read
Resource type
alarm

Parameters

alarmNameIdentifierNamepathrequired

Alarm name.

maxResultsintegerquery

The maximum number of history entries to return in a single response page.

nextTokenstringquery

Pagination token to retrieve the next page of alarm history if the current result set is truncated.

Responses

200

Alarm history

ListAlarmHistoryResponseobject
historyAlarmHistoryEntry[]

The list of alarm status transitions.

nextTokenstring

Pagination token to retrieve the next set of alarm history entries.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_PAGINATION_TOKEN

Invalid pagination token

GetAlarm

Get an alarm

get/v1/alarms/{alarmName}

Retrieves the details and current status of a specific alarm by its name.

Required permissions

Service
metrics
Access level
Read
Resource type
alarm

Parameters

alarmNameIdentifierNamepathrequired

Alarm name.

Responses

200

Alarm details

Alarmobject
nameIdentifierName

The unique name of the alarm.

variablesAlarmVariable[]

List of metric variables that the alarm expression monitors.

expressionstring

The threshold expression (e.g., 'A > 90').

evaluationPeriodInMininteger:int32

The duration in minutes over which the metric data is evaluated.

datapointsToAlarminteger:int32

The number of consecutive data points that must breach the threshold to trigger the alarm.

resolutionResolution

The resolution of the metric data used for evaluation.

treatMissingDataAsTreatMissingDataAs

How the alarm treats periods where the expression cannot be evaluated because metric data is missing.

statusAlarmStatus

The current operational state of the alarm.

notificationStatusNotificationStatus

Whether the most recent status transition was delivered to every configured notification channel. FAILED means a configured channel could not be resolved.

notificationChannelsstring[]

List of names of notification channels to alert when the alarm status changes.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

CreateAlarm

Create an alarm

post/v1/alarms/{alarmName}

Creates a new alarm that monitors a metric and triggers notifications when thresholds are met.

Required permissions

Service
metrics
Access level
Create
Resource type
alarm
Service
metrics
Access level
Read
Resource type
metric
Service
metrics
Access level
Read
Resource type
notification-channel

Parameters

alarmNameIdentifierNamepathrequired

Alarm name.

Request body

CreateAlarmRequestobject
variablesAlarmVariable[]required

List of metric variables that the alarm expression monitors.

expressionstringrequired

The threshold expression (e.g., 'A > 90'). Must use variable names defined in 'variables'.

evaluationPeriodInMininteger:int32required

The duration in minutes over which the metric data is evaluated.

datapointsToAlarminteger:int32required

The number of consecutive data points that must breach the threshold to trigger the alarm.

resolutionResolutionrequired

The resolution of the metric data used for evaluation.

treatMissingDataAsTreatMissingDataAsrequired

How the alarm should treat periods where the expression cannot be evaluated because metric data is missing.

notificationChannelsIdentifierName[]

List of names of notification channels to alert when the alarm status changes.

Responses

201

Alarm created

Alarmobject
nameIdentifierName

The unique name of the alarm.

variablesAlarmVariable[]

List of metric variables that the alarm expression monitors.

expressionstring

The threshold expression (e.g., 'A > 90').

evaluationPeriodInMininteger:int32

The duration in minutes over which the metric data is evaluated.

datapointsToAlarminteger:int32

The number of consecutive data points that must breach the threshold to trigger the alarm.

resolutionResolution

The resolution of the metric data used for evaluation.

treatMissingDataAsTreatMissingDataAs

How the alarm treats periods where the expression cannot be evaluated because metric data is missing.

statusAlarmStatus

The current operational state of the alarm.

notificationStatusNotificationStatus

Whether the most recent status transition was delivered to every configured notification channel. FAILED means a configured channel could not be resolved.

notificationChannelsstring[]

List of names of notification channels to alert when the alarm status changes.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_EXPRESSION

Invalid expression

400

EXPRESSION_TOO_COMPLEX

Expression is too complex

400

MISMATCHED_EXPRESSION_PARENTHESES

Mismatched parentheses in expression

400

MISSING_EXPRESSION_OPERAND

Missing operand for operator %s

400

MISSING_EXPRESSION_OPERANDS

Missing operands for operator %s

400

INVALID_EXPRESSION_TOKEN

Invalid token in expression: %s

404

RESOURCE_NOT_FOUND

Resource not found

400

INVALID_ALARM_REQUEST

Invalid alarm request

400

DUPLICATE_ALARM_VARIABLE_NAME

Alarm variable names must be unique

400

ALARM_EVALUATION_PERIOD_NOT_MULTIPLE_OF_RESOLUTION

Alarm evaluation period must be a whole multiple of the resolution

400

ALARM_DATAPOINTS_EXCEED_EVALUATION_BUCKETS

Datapoints to alarm cannot exceed the number of evaluation buckets in the evaluation period

400

ALARM_EVALUATION_WINDOW_TOO_LARGE

Alarm evaluation window contains too many buckets for the selected resolution

400

UNVERIFIED_NOTIFICATION_CHANNEL

Notification channel must be verified before it can be attached to an alarm

UpdateAlarm

Update an alarm

put/v1/alarms/{alarmName}

Updates the configuration of an existing alarm.

Required permissions

Service
metrics
Access level
Read
Resource type
alarm
Service
metrics
Access level
Write
Resource type
alarm
Service
metrics
Access level
Read
Resource type
metric
Service
metrics
Access level
Read
Resource type
notification-channel

Parameters

alarmNameIdentifierNamepathrequired

Alarm name.

Request body

UpdateAlarmRequestobject
variablesAlarmVariable[]required

List of metric variables that the alarm expression monitors.

expressionstringrequired

The threshold expression (e.g., 'A > 90'). Must use variable names defined in 'variables'.

evaluationPeriodInMininteger:int32required

The duration in minutes over which the metric data is evaluated.

datapointsToAlarminteger:int32required

The number of consecutive data points that must breach the threshold to trigger the alarm.

resolutionResolutionrequired

The resolution of the metric data used for evaluation.

treatMissingDataAsTreatMissingDataAsrequired

How the alarm should treat periods where the expression cannot be evaluated because metric data is missing.

notificationChannelsIdentifierName[]

List of names of notification channels to alert when the alarm status changes.

Responses

200

Alarm updated

Alarmobject
nameIdentifierName

The unique name of the alarm.

variablesAlarmVariable[]

List of metric variables that the alarm expression monitors.

expressionstring

The threshold expression (e.g., 'A > 90').

evaluationPeriodInMininteger:int32

The duration in minutes over which the metric data is evaluated.

datapointsToAlarminteger:int32

The number of consecutive data points that must breach the threshold to trigger the alarm.

resolutionResolution

The resolution of the metric data used for evaluation.

treatMissingDataAsTreatMissingDataAs

How the alarm treats periods where the expression cannot be evaluated because metric data is missing.

statusAlarmStatus

The current operational state of the alarm.

notificationStatusNotificationStatus

Whether the most recent status transition was delivered to every configured notification channel. FAILED means a configured channel could not be resolved.

notificationChannelsstring[]

List of names of notification channels to alert when the alarm status changes.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_EXPRESSION

Invalid expression

400

EXPRESSION_TOO_COMPLEX

Expression is too complex

400

MISMATCHED_EXPRESSION_PARENTHESES

Mismatched parentheses in expression

400

MISSING_EXPRESSION_OPERAND

Missing operand for operator %s

400

MISSING_EXPRESSION_OPERANDS

Missing operands for operator %s

400

INVALID_EXPRESSION_TOKEN

Invalid token in expression: %s

404

RESOURCE_NOT_FOUND

Resource not found

409

RESOURCE_UPDATED_CONCURRENTLY

Resource was updated by another process

400

INVALID_ALARM_REQUEST

Invalid alarm request

400

DUPLICATE_ALARM_VARIABLE_NAME

Alarm variable names must be unique

400

ALARM_EVALUATION_PERIOD_NOT_MULTIPLE_OF_RESOLUTION

Alarm evaluation period must be a whole multiple of the resolution

400

ALARM_DATAPOINTS_EXCEED_EVALUATION_BUCKETS

Datapoints to alarm cannot exceed the number of evaluation buckets in the evaluation period

400

ALARM_EVALUATION_WINDOW_TOO_LARGE

Alarm evaluation window contains too many buckets for the selected resolution

400

UNVERIFIED_NOTIFICATION_CHANNEL

Notification channel must be verified before it can be attached to an alarm

DeleteAlarm

Delete an alarm

delete/v1/alarms/{alarmName}

Permanently deletes an alarm.

Required permissions

Service
metrics
Access level
Delete
Resource type
alarm

Parameters

alarmNameIdentifierNamepathrequired

Alarm name.

Responses

204

Alarm deleted

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

Notification channels

6 endpoints

ListNotificationChannels

List all notification channels for the authenticated user

get/v1/notification-channels

Retrieves a list of all notification channels (e.g., email, webhooks) configured for the authenticated account.

Required permissions

Service
metrics
Access level
List
Resource type
notification-channel

Parameters

maxResultsintegerquery

The maximum number of notification channels to return in a single response page.

nextTokenstringquery

Pagination token to retrieve the next page of notification channels if the current result set is truncated.

Responses

200

List of notification channels

ListNotificationChannelsResponseobject
channelsNotificationChannel[]

List of notification channels configured for the account.

nextTokenstring

Pagination token to retrieve the next set of notification channels.

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

INVALID_PAGINATION_TOKEN

Invalid pagination token

CreateNotificationChannel

Create a new notification channel

post/v1/notification-channels

Creates a new notification channel to receive alarm alerts. Some channel types may require verification.

Required permissions

Service
metrics
Access level
Create
Resource type
notification-channel

Request body

CreateNotificationChannelRequestobject
nameIdentifierNamerequired

Unique name of the notification channel.

typeNotificationChannelTyperequired

The transport type of the notification channel.

configNotificationChannelConfigrequired

Type-specific configuration for the channel.

Responses

201

Notification channel created

NotificationChannelobject
nameIdentifierNamerequired

Unique name of the notification channel.

typeNotificationChannelTyperequired

The transport type of the notification channel.

configNotificationChannelConfigrequired

Type-specific configuration for the channel.

verifiedbooleanrequired

Indicates whether the channel has been successfully verified (e.g., via email code).

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

400

NOTIFICATION_CHANNEL_CONFIG_REQUIRED

Notification channel config is required

400

WEBHOOK_NOTIFICATION_CHANNEL_CONFIG_REQUIRED

Webhook notification channel config is required

400

WEBHOOK_NOTIFICATION_CHANNEL_CANNOT_INCLUDE_EMAIL_CONFIG

Webhook notification channels cannot include email config

400

EMAIL_NOTIFICATION_CHANNEL_CONFIG_REQUIRED

Email notification channel config is required

400

EMAIL_NOTIFICATION_CHANNEL_CANNOT_INCLUDE_WEBHOOK_CONFIG

Email notification channels cannot include webhook config

409

RESOURCE_LIMIT_EXCEEDED

Resource limit exceeded

GetNotificationChannel

Get a notification channel by name

get/v1/notification-channels/{channelName}

Retrieves the details and current verification status of a specific notification channel by its name.

Required permissions

Service
metrics
Access level
Read
Resource type
notification-channel

Parameters

channelNameIdentifierNamepathrequired

Notification channel name.

Responses

200

Notification channel details

NotificationChannelobject
nameIdentifierNamerequired

Unique name of the notification channel.

typeNotificationChannelTyperequired

The transport type of the notification channel.

configNotificationChannelConfigrequired

Type-specific configuration for the channel.

verifiedbooleanrequired

Indicates whether the channel has been successfully verified (e.g., via email code).

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

UpdateNotificationChannel

Update a notification channel

put/v1/notification-channels/{channelName}

Updates the configuration of an existing notification channel.

Required permissions

Service
metrics
Access level
Read
Resource type
notification-channel
Service
metrics
Access level
Write
Resource type
notification-channel

Parameters

channelNameIdentifierNamepathrequired

Notification channel name.

Request body

UpdateNotificationChannelRequestobject
configNotificationChannelConfigrequired

The updated configuration for the channel.

Responses

200

Notification channel updated

NotificationChannelobject
nameIdentifierNamerequired

Unique name of the notification channel.

typeNotificationChannelTyperequired

The transport type of the notification channel.

configNotificationChannelConfigrequired

Type-specific configuration for the channel.

verifiedbooleanrequired

Indicates whether the channel has been successfully verified (e.g., via email code).

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

NOTIFICATION_CHANNEL_CONFIG_REQUIRED

Notification channel config is required

400

WEBHOOK_NOTIFICATION_CHANNEL_CONFIG_REQUIRED

Webhook notification channel config is required

400

WEBHOOK_NOTIFICATION_CHANNEL_CANNOT_INCLUDE_EMAIL_CONFIG

Webhook notification channels cannot include email config

400

EMAIL_NOTIFICATION_CHANNEL_CONFIG_REQUIRED

Email notification channel config is required

400

EMAIL_NOTIFICATION_CHANNEL_CANNOT_INCLUDE_WEBHOOK_CONFIG

Email notification channels cannot include webhook config

409

RESOURCE_UPDATED_CONCURRENTLY

Resource was updated by another process

DeleteNotificationChannel

Delete a notification channel

delete/v1/notification-channels/{channelName}

Permanently deletes a notification channel.

Required permissions

Service
metrics
Access level
Delete
Resource type
notification-channel

Parameters

channelNameIdentifierNamepathrequired

Notification channel name.

Responses

204

Notification channel deleted

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

409

NOTIFICATION_CHANNEL_IN_USE

Notification channel is still referenced by one or more alarms

VerifyNotificationChannel

Verify an email notification channel

post/v1/notification-channels/{channelName}/verify

Verifies a notification channel (e.g., via a code sent to an email address) to enable it for receiving alerts.

Required permissions

Service
metrics
Access level
Read
Resource type
notification-channel
Service
metrics
Access level
Write
Resource type
notification-channel

Parameters

channelNameIdentifierNamepathrequired

Notification channel name.

Request body

VerifyNotificationChannelRequestobject
codeVerificationCoderequired

The verification code sent to the channel (e.g., via email).

Responses

200

Notification channel verified

NotificationChannelobject
nameIdentifierNamerequired

Unique name of the notification channel.

typeNotificationChannelTyperequired

The transport type of the notification channel.

configNotificationChannelConfigrequired

Type-specific configuration for the channel.

verifiedbooleanrequired

Indicates whether the channel has been successfully verified (e.g., via email code).

Errors

401

UNAUTHORIZED

Unauthorized

401

TOKEN_EXPIRED

Token expired

403

ACCOUNT_NOT_ACTIVE

Account is not active

403

ACCESS_DENIED

Access denied

404

RESOURCE_NOT_FOUND

Resource not found

400

ONLY_EMAIL_NOTIFICATION_CHANNELS_CAN_BE_VERIFIED

Only email notification channels can be verified

400

INVALID_OR_EXPIRED_VERIFICATION_CODE

Invalid or expired verification code

409

RESOURCE_UPDATED_CONCURRENTLY

Resource was updated by another process