Administrative endpoints

GET /v6/account-groups Account group list

Returns a list of all account groups available to the current user. The aid value returned for an account in this list of account groups can be used in queries elsewhere within the app. See Account Context for more information on changing Account Group context.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • There is no request body for this request.
  • There are no request parameters for this request.

Example

$ curl https://api.thousandeyes.com/v6/account-groups.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of account groups.

FieldData TypeNotes
accountGroupNamestringvalue must be unique across account groups in organization
aidintegersystem-generated unique ID of the account group
currentinteger1 if the request is being made in the context of this account group, 0 otherwise
defaultinteger1 if the account group being queried is your user’s login account group, 0 otherwise

If successful, returns a list of accounts available to the authenticated user. The “default” flag indicates that this is the “login account group” for the current user, and that any query not including an aid parameter will be executed in that account group context.

The “current” flag indicates that this is the account context you are in at present. For example, calling https://api.thousandeyes.com/v6/account-groups?aid=354 would change the account context, and show current = 1 for account ID 354, even though the user’s default account ID is 353. Data is shown below using this call as an example.

If your user is assigned to account groups that exist in multiple organizations, the “organizationName” field will be shown for each account group.

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "accountGroups": [ { "accountGroupName": "API Sandbox", "aid": 75 } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/account-groups/{aid} Account group detail

Returns detailed information about a specific account group. Requires that the user making the request has the View all account groups settings permission.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information

Request

  • aid={aid} account group to query for detail.
  • There is no request body for this request.

Example

$ curl https://api.thousandeyes.com/v6/account-groups/315.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns details for the requested account group. Metadata for the request is based on the following detail:

FieldData TypeNotes
accountGroupNamestringthe name of the account group
aidintegerunique ID for the account group
organizationNamestringname of the organization (can only be configured by ThousandEyes Customer Success)
currentinteger1 if the request is being made in the context of this account group, 0 otherwise. If you are receiving a 0 response to this request, try making the call with aid={aid} querystring parameter to change the response
defaultinteger1 if the account group being queried is your user’s login account group, 0 otherwise
usersarray of user objectssee individual fields below prefixed by user
users.namestringuser’s display name
users.emailstringuser’s email address
users.uidintegerunique ID for the user
users.rolesarray of role objectssee individual fields below prefixed by roles
users.roles.roleNamestringname of the role
users.roles.roleIdintegerunique ID of the role
users.roles.hasManagementPermissionsinteger1 if the user has management permissions, 0 otherwise
users.roles.builtininteger1 if the role is built-in, 0 if the role is user-defined
agentsarray of agent objectssee individual fields below prefixed by agents
agents.agentIdintegerunique ID for the agent
agents.agentNamestringname of the agent
agents.locationstringlocation specification
agents.countryIdstring2-digit ISO country code
agents.prefixstringprefix containing agents public IP address
agents.utilizationintegerutilization percentage of agent; only available if agentState is Online
agents.ipAddressesarray of stringsarray of private IP addresses
agents.publicIpAddressesarray of stringsarray of public IP addresses
agents.enabledinteger1 for enabled, 0 for disabled
agents.verifySslCertificatesinteger1 for normal operation, 0 to ignore SSL errors on browserbot-based tests
agents.keepBrowserCacheinteger0 for normal operation, 1 for retain cache
agents.lastSeendateTimedate last seen in YYYY-mm-dd HH:MM:SS format
agents.agentTypestringenterprise, enterprise cluster
agents.networkstringnetwork (including ASN) of agent’s public IP
agents.agentStatestringonline or offline

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "accountGroups": [ { "accountGroupName": "Documentation", "aid": 315, "organizationName": "ThousandEyes Internal", "current": 0, "default": 0, "users": [ { "name": "newest username", "email": "dave+documentation@thousandeyes.com", "uid": 1307, "roles": [ { "roleName": "Account Admin", "roleId": 57, "hasManagementPermissions": 0, "builtin": 1 }, { "roleName": "Organization Admin", "roleId": 60, "hasManagementPermissions": 1, "builtin": 1 } ] }, [...] ], "agents": [ { "agentId": 2486, "agentName": "thousandeyes-stg-va-2546", "location": "San Francisco Bay Area", "countryId": "US", "ipAddress": "192.168.1.78", "publicIpAddress": "99.139.65.220", "prefix": "99.128.0.0/11", "ipAddresses": [ "192.168.1.78" ], "publicIpAddresses": [ "99.139.65.220" ], "enabled": 1, "verifySslCertificates": 1, "keepBrowserCache": 0, "lastSeen": "2016-04-26 02:44:08", "agentType": "Enterprise", "network": "AT&T Services, Inc. (AS 7018)", "agentState": "Offline" } ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/account-groups/new Creating an account group

Creates a new account group. Requires the Edit all account groups permission.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information

Request

  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • Request body should contain the following fields:
FieldData TypeRequired/OptionalNotes
accountGroupNamestringrequiredthe name of the account group
agentsarray of agent objectsoptionalTo grant access to enterprise agents, specify the agent list. "agents":[{"agentId": 1234}]. Note that this is not an additive list - the full list must be specified if changing access to agents.

Example

$ curl https://api.thousandeyes.com/v6/account-groups/new \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{"accountGroupName": "my testing account group"}' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns details for the requested account group. Note that any user assigned to “All Account Groups” is automatically assigned to the new account group. Metadata for the request is based on the following detail:

FieldData TypeNotes
accountGroupNamestringthe name of the account group
aidintegerunique ID for the account group
organizationNamestringname of the organization (can only be configured by ThousandEyes Customer Success)
currentinteger1 if the request is being made in the context of this account group, 0 otherwise. If you are receiving a 0 response to this request, try making the call with aid={aid} querystring parameter to change the response
defaultinteger1 if the account group being queried is your user’s login account group, otherwise 0.
usersarray of user objectssee individual fields below prefixed by user
users.namestringuser’s display name
users.emailstringuser’s email address
users.uidintegerunique ID for the user
users.rolesarray of role objectssee individual fields below prefixed by roles
users.roles.roleNamestringname of the role
users.roles.roleIdintegerunique ID of the role
users.roles.hasManagementPermissionsinteger1 if the user has management permissions, 0 otherwise
users.roles.builtininteger1 if the role is built-in, 0 if the role is user-defined

HTTP/1.1 201 Created Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "accountGroups": [ { "accountGroupName": "my testing account group", "aid": 9881, "organizationName": "ThousandEyes Internal", "current": 0, "default": 0, "users": [ { "name": "newest username", "email": "dave+documentation@thousandeyes.com", "uid": 1307, "roles": [ { "roleName": "Organization Admin", "roleId": 60, "hasManagementPermissions": 1, "builtin": 1 } ] }, [...] ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/account-groups/{aid}/update Updating an account group

Modifies an account group. This can include changing the account group’s name, or modifying the list of users assigned to the account group.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information

Request

  • aid={aid} account group to query for detail.
  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • Request body allows update of certain account group fields:
FieldData TypeRequired/OptionalNotes
accountGroupNamestringoptionalname of the account group. To rename the account group, specify a new name.
agentsarray of agent objectsoptionalTo grant access to enterprise agents, specify the agent list. "agents":[{"agentId": 1234}]. Note that this is not an additive list - the full list must be specified if changing access to agents.

Example

$ curl https://api.thousandeyes.com/v6/account-groups/315/update \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "accountGroupName": "Renamed account group" }' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 \

Response

If successful, returns an HTTP/200 status code, as well as the updated account group object.

FieldData TypeNotes
accountGroupNamestringthe name of the account group
aidintegerunique ID for the account group
organizationNamestringname of the organization (can only be configured by ThousandEyes Customer Success)
currentinteger1 if the request is being made in the context of this account group, 0 otherwise. If you are receiving a 0 response to this request, try making the call with aid={aid} querystring parameter to change the response
defaultinteger1 if the account group being queried is your user’s login account group, otherwise 0.
usersarray of user objectssee individual fields below prefixed by user
users.namestringuser’s display name
users.emailstringuser’s email address
users.uidintegerunique ID for the user
users.rolesarray of role objectssee individual fields below prefixed by roles
users.roles.roleNamestringname of the role
users.roles.roleIdintegerunique ID of the role
users.roles.hasManagementPermissionsinteger1 if the user has management permissions, 0 otherwise
users.roles.builtininteger1 if the role is built-in, 0 if the role is user-defined

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "accountGroups": [ { "accountGroupName": "Renamed accounts group", "aid": 315, "organizationName": "ThousandEyes Internal", "current": 1, "default": 1, "users": [...] "agents": [...] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/users User list

Returns a list of all users assigned to the current account group. Returns detailed information about a specific user. Requires that the user making the request has the API Access and View all users permissions. See Account Context for more information on changing Account Group context.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information

Request

  • There is no request body for this request.
  • There are no request parameters for this request.

Example

$ curl https://api.thousandeyes.com/v6/users.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns a list of users assigned to the current account group.

FieldData TypeNotes
namestringthe name of the user
emailstringemail address for the user
uidintegerunique user ID for the user
lastLogindateTimethe last login of the user (UTC)
dateRegistereddateTimethe date the user registered their account (UTC)
loginAccountGroupaccountGroup objectlogin accountGroup for the user
loginAccountGroup.accountGroupNamestringname of the accountGroup
loginAccountGroup.aidintegersystem-generated unique ID of the account group

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "users": [ { "dateRegistered": "2012-06-27 17:23:50", "email": "noreply@thousandeyes.com", "lastLogin": "2013-11-26 17:53:42", "loginAccountGroup": { "accountGroupName": "API Sandbox", "aid": 75 }, "name": "API Sandbox User", "uid": 245 }, ... ] }

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/users/{uid} User detail

Returns detailed information about a specific user. Requires that the user making the request has the API Access and View all users permissions.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • uid={uid} unique ID for the user to query for detail.
  • There is no body for this request.

Example

$ curl https://api.thousandeyes.com/v6/users/245.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns details for the requested user. If the user is explicitly assigned to multiple account groups, each account group will explicitly be shown. If the user is assigned to “All Account Groups”, then there will be a special entry for the user using the allAccountGroupRoles object.

FieldData TypeNotes
namestringthe name of the user
emailstringemail address for the user
uidintegerunique user ID for the user
lastLogindateTimethe last login of the user (UTC)
dateRegistereddateTimethe date the user registered their account (UTC)
loginAccountGroupaccountGroup objectlogin accountGroup for the user
loginAccountGroup.accountGroupNamestringname of the accountGroup
loginAccountGroup.aidintegersystem-generated unique ID of the account group
accountGroupRoleslist of accountGroupRole objectssee below
accountGroupRoles.accountGroup.accountGroupNamestringname of the accountGroup
accountGroupRoles.accountGroupName.aidintegerunique account ID for the accountGroup
accountGroupRoles.roles.roleNamestringthe name of the role
accountGroupRoles.roles.roleIDintegersystem-defined unique ID of the role
accountGroupRoles.roles.hasManagementPermissionsinteger1 for roles with management permissions, 0 for roles without
accountGroupRoles.roles.builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles
allAccountGroupRoleslist of roles objectssee below
allAccountGroupRoles.roles.roleNamestringthe name of the role
allAccountGroupRoles.roles.roleIDintegersystem-defined unique ID of the role
allAccountGroupRoles.roles.hasManagementPermissionsinteger1 for roles with management permissions, 0 for roles without
allAccountGroupRoles.roles.builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "users": [ { "accountGroupRoles": [ { "accountGroup": { "accountGroupName": "API Sandbox", "aid": 75 }, "roles": [ { "builtin": 0, "hasManagementPermissions": 1, "roleId": 280871, "roleName": "API User" } ] } ], "dateRegistered": "2012-06-27 17:23:50", "email": "noreply@thousandeyes.com", "lastLogin": "2013-11-26 17:53:42", "loginAccountGroup": { "accountGroupName": "API Sandbox", "aid": 75 }, "name": "API Sandbox User", "uid": 245 } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/users/new Adding a user

Creates a new user.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • Request body should contain the following fields:
FieldData TypeRequired/OptionalNotes
namestringoptionalthe name of the user
emailstringrequiredemail address for the user
loginAccountGroupaccountGroup objectrequiredlogin accountGroup for the user. If the user being added is already associated with another ThousandEyes organization, this value will be ignored. The user (once added) can modify his default account group as needed.
loginAccountGroup.aidintegerrequired for loginAccountGroup objectsystem-generated unique ID of the account group
accountGroupRoleslist of accountGroupRole objectssee notessee below; either the accountGroupRoles object or the allAccountGroupRoles object must be specified.
accountGroupRoles.accountGroupName.aidintegerrequired for accountGroupName objectunique account ID for the accountGroupName
accountGroupRoles.roles.roleIDintegerrequired for roles objectsystem-defined unique ID of the role
allAccountGroupRoleslist of roles objectsoptionaleither the accountGroupRoles object or the allAccountGroupRoles object must be specified.
allAccountGroupRoles.roles.roleIDintegerrequired for roles objectsystem-defined unique ID of the role

A few notes on the topic of user creation:

  • If the user is already a member of another ThousandEyes customer’s organization, the user will need to set their own login account group.
  • Any update which contains accountGroupRoles is a replace-based update, rather than a delta-based update.

Example

$ curl https://api.thousandeyes.com/v6/users/new \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "name":"newest username", "email":"dave+documentationNEW@thousandeyes.com", "loginAccountGroup": { "aid":691 }, "accountGroupRoles":[ { "accountGroup": { "aid":315 }, "roles":[ { "roleId":57 } ] }, { "accountGroup": { "aid":691 }, "roles":[ { "roleId":60 } ] } ], "allAccountGroupRoles": [ { "roleId": 1140 } ] }' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 \

Response

If the request is successful, returns an object in the same format as the user detail endpoint. In the event that the request fails, check the response body for more information.

FieldData TypeNotes
namestringthe name of the user
emailstringemail address for the user
uidintegerunique user ID for the user
loginAccountGroupaccountGroup objectlogin accountGroup for the user
loginAccountGroup.accountGroupNamestringname of the accountGroup
loginAccountGroup.aidintegersystem-generated unique ID of the account group
accountGroupRoleslist of accountGroupRole objectssee below
accountGroupRoles.accountGroup.accountGroupNamestringname of the accountGroup
accountGroupRoles.accountGroupName.aidintegerunique account ID for the accountGroup
accountGroupRoles.roles.roleNamestringthe name of the role
accountGroupRoles.roles.roleIDintegersystem-defined unique ID of the role
accountGroupRoles.roles.hasManagementPermissionsinteger1 for roles with management permissions, 0 for roles without
accountGroupRoles.roles.builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles
allAccountGroupRoleslist of roles objectssee below
allAccountGroupRoles.roles.roleNamestringthe name of the role
allAccountGroupRoles.roles.roleIDintegersystem-defined unique ID of the role
allAccountGroupRoles.roles.hasManagementPermissionsinteger1 for roles with management permissions, 0 for roles without
allAccountGroupRoles.roles.builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "users": [ { "name": "My new user", "email": "dave+apitesting@thousandeyes.com", "uid": 3914, "loginAccountGroup": { "accountGroupName": "Documentation", "aid": 315 }, "accountGroupRoles": [ { "accountGroup": { "accountGroupName": "Doc Account 2", "aid": 691 }, "roles": [ { "roleName": "Organization Admin", "roleId": 60, "hasManagementPermissions": 1, "builtin": 1 } ] }, { "accountGroup": { "accountGroupName": "Documentation", "aid": 315 }, "roles": [ { "roleName": "Account Admin", "roleId": 57, "hasManagementPermissions": 0, "builtin": 1 } ] } ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/users/{uid}/update Updating a user

Modifies a user. This can include changing the user’s name, email address, account group assignments, or roles. Use of this endpoint requires the Edit users in all account groups or Edit users permission.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • uid={uid} is the unique user ID for the user
  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • Request body allows update of certain user fields:
FieldData TypeRequired/OptionalNotes
namestringoptionalthe name of the user
emailstringoptionalemail address for the user
loginAccountGroupaccountGroup objectoptionallogin accountGroup for the user
loginAccountGroup.aidintegerrequired for loginAccountGroup objectsystem-generated unique ID of the account group
accountGroupRoleslist of accountGroupRole objectsoptionalsee below
accountGroupRoles.accountGroupName.aidintegerrequired for accountGroupName objectunique account ID for the accountGroup
accountGroupRoles.roles.roleIDintegerrequired for roles objectsystem-defined unique ID of the role
allAccountGroupRoleslist of roles objectsoptionalsee below
allAccountGroupRoles.roles.roleIDintegerrequired for roles objectsystem-defined unique ID of the role

A few notes on the topic of user modifications:

  • If a user’s email is updated, the user will need to validate the username change before being able to subsequently log in, or execute API operations.
  • Any update which contains accountGroupRoles is a replace-based update, rather than a delta-based update.

Example

$ curl https://api.thousandeyes.com/v6/users/1390/update \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "name":"newest username", "email":"dave+documentationNEW@thousandeyes.com", "loginAccountGroup": { "aid":691 }, "accountGroupRoles":[ { "accountGroup": { "aid":315 }, "roles":[ { "roleId":57 } ] }, { "accountGroup": { "aid":691 }, "roles":[ { "roleId":60 } ] } ], "allAccountGroupRoles": [ { "roleId": 1140 } ] }' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2 \

Response

If successful, returns an updated user object in the same format as the user detail endpoint.

FieldData TypeNotes
namestringthe name of the user
emailstringemail address for the user
uidintegerunique user ID for the user
loginAccountGroupaccountGroup objectlogin accountGroup for the user
loginAccountGroup.accountGroupNamestringname of the accountGroup
loginAccountGroup.aidintegersystem-generated unique ID of the account group
lastLogindateTimethe last login of the user (UTC)
dateRegistereddateTimethe date the user registered their account (UTC)
accountGroupRoleslist of accountGroupRole objectssee below
accountGroupRoles.accountGroup.accountGroupNamestringname of the accountGroup
accountGroupRoles.accountGroupName.aidintegerunique account ID for the accountGroup
accountGroupRoles.roles.roleNamestringthe name of the role
accountGroupRoles.roles.roleIDintegersystem-defined unique ID of the role
accountGroupRoles.roles.hasManagementPermissionsinteger1 for roles with management permissions, 0 for roles without
accountGroupRoles.roles.builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles
allAccountGroupRoleslist of roles objectssee below
allAccountGroupRoles.roles.roleNamestringthe name of the role
allAccountGroupRoles.roles.roleIDintegersystem-defined unique ID of the role
allAccountGroupRoles.roles.hasManagementPermissionsinteger1 for roles with management permissions, 0 for roles without
allAccountGroupRoles.roles.builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "users": [ { "name": "newest username", "email": "dave+documentationNEW@thousandeyes.com", "uid": 1307, "loginAccountGroup": { "accountGroupName": "Doc Account 2", "aid": 691 }, "lastLogin": "2016-10-14 01:27:39", "dateRegistered": "2013-03-29 19:57:23", "accountGroupRoles": [ { "accountGroup": { "accountGroupName": "Doc Account 2", "aid": 691 }, "roles": [ { "roleName": "Organization Admin", "roleId": 60, "hasManagementPermissions": 1, "builtin": 1 } ] }, { "accountGroup": { "accountGroupName": "Documentation", "aid": 315 }, "roles": [ { "roleName": "Account Admin", "roleId": 57, "hasManagementPermissions": 0, "builtin": 1 } ] } ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/users/{uid}/delete Deleting a user

Deletes a user. Requires Edit users in all account groups or Edit users permissions to be assigned to the user making the reuqest.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • uid={uid} is the unique user ID for the user to delete.
  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • There is no request body for this request.

Example

$curl https://api.thousandeyes.com/v6/users/3914/delete \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If the deletion is successful, will return an HTTP/204 response code with an empty response body.

HTTP/1.1 204 No Content Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

Empty response body

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/roles Role list

Returns a list of all roles defined and visible to the current user.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • There is no request body for this request.
  • There are no request parameters for this request.

Example

$ curl https://api.thousandeyes.com/v6/roles.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of roles defined in the system.

FieldData TypeNotes
roleNamestringthe name of the role
roleIdintegerunique ID of the role
hasManagementPermissionsintegerif the role is assigned any management permissions, this value will be 1. Otherwise, 0
builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "roles": [ { "builtin": 1, "hasManagementPermissions": 1, "roleId": 156, "roleName": "Account Admin" }, { "builtin": 0, "hasManagementPermissions": 1, "roleId": 280871, "roleName": "API User" }, { "builtin": 1, "hasManagementPermissions": 1, "roleId": 159, "roleName": "Organization Admin" }, { "builtin": 1, "hasManagementPermissions": 0, "roleId": 162, "roleName": "Regular User" } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/roles/{roleId} Role detail

Returns detailed information about a role, defining role name, ID and assigned permissions.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • {roleId} is the unique ID for the role
  • There is no request body for this request.

Example

$ curl https://api.thousandeyes.com/v6/roles/280871.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns role details, including role name and assigned permissions.

FieldData TypeNotes
roleNamestringthe name of the role
roleIdintegerunique ID of the role
hasManagementPermissionsintegerif the role is assigned any management permissions, this value will be 1. Otherwise, 0
builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles
permissionslist of permission objectssee below
permissions.permissionIdintegersystem-defined unique ID of the permission
permissions.labelstringlabel corresponding to the permission
permissions.isManagementPermissioninteger1 if the permission is classified as a management permission, 0 Otherwise

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "roles": [ { "builtin": 0, "roleId": 280871, "roleName": "API User", "permissions": [ { "isManagementPermission": 0, "label": "View reports", "permissionId": 8 }, { "isManagementPermission": 0, "label": "View snapshots", "permissionId": 11 }, ... ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/roles/new Creating a role

Allows creation of a role, programmatically.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • Request body should contain the following fields:
FieldData TypeRequired/OptionalNotes
roleNamestringrequiredthe name of the role
permissionslist of permission objectsoptionalsee below
permissions.permissionIdintegerrequired for permissions objectsystem-defined unique ID of the permission

A few notes on the topic of role creation:

  • Post with a role name, and permissions that need to be assigned to the role.
  • Permission definitions and details can be obtained from the permissions endpoint.

Example

$ curl https://api.thousandeyes.com/v6/roles/new \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "roleName": "My new role", "permissions": [ { "permissionId": 1 }, { "permissionId": 2 } ] }' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns role details, including role name and assigned permissions.

FieldData TypeNotes
roleNamestringthe name of the role
roleIdintegerunique ID of the role
builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles
permissionslist of permission objectssee below
permissions.permissionIdintegersystem-defined unique ID of the permission
permissions.labelstringlabel corresponding to the permission
permissions.isManagementPermissioninteger1 if the permission is classified as a management permission, 0 Otherwise

HTTP/1.1 201 Created Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "roles": [ { "roleName": "My new role", "roleId": 57, "builtin": 0, "permissions": [ { "permissionId": 1, "label": "Assign users emails to alerts", "isManagementPermission": 0 }, [...] ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

POST /v6/roles/{roleId}/update Updating a role

Modifies a user-defined role by changing the role name or permissions assigned.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • {roleId} is the unique ID for the role
  • content-type and accept headers must be set (both to application/json) when using this endpoint.
  • Request body allows update of certain role fields:
FieldData TypeRequired/OptionalNotes
roleNamestringoptionalthe name of the role
permissionslist of permission objectsoptionalsee below (and notes below)
permissions.permissionIdintegerrequired for permissions objectsystem-defined unique ID of the permission

A few notes related to role modifications:

  • The full list of permissions must be sent, this endpoint does not support a delta-based grant or revocation of permissions.
  • Permission definitions and details can be obtained from the permissions endpoint.

Example

$ curl https://api.thousandeyes.com/v6/roles/57/update \ -H "Accept: application/json" \ -H "Content-Type: application/json" \ -d '{ "roleName": "New name for my role", "permissions": [ { "permissionId": 1 }, { "permissionId": 3 } ] }' \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

If successful, returns updated role details, including role name and assigned permissions.

FieldData TypeNotes
roleNamestringthe name of the role
roleIdintegerunique ID of the role
builtininteger1 for built-in roles (Account Admin, Organization Admin, Regular User), 0 for user-defined roles
permissionslist of permission objectssee below
permissions.permissionIdintegersystem-defined unique ID of the permission
permissions.labelstringlabel corresponding to the permission
permissions.isManagementPermissioninteger1 if the permission is classified as a management permission, 0 Otherwise

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "roles": [ { "roleName": "New name for my role", "roleId": 57, "builtin": 0, "permissions": [ { "permissionId": 1, "label": "Assign users emails to alerts", "isManagementPermission": 0 }, [...] ] } ] }

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/permissions Permission list

Returns a list of all assignable permissions, which is used in the context of modifying roles.

Users must be in a role that is assigned managment permissions in order to access this endpoint. Users without management permissions attempting to access this endpoint will have an HTTP/403 response code returned.

Optional Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error

Request

  • There is no request body for this request.
  • There are no request parameters for this request.

Example

$ curl https://api.thousandeyes.com/v6/permissions.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of permissions.

FieldData TypeNotes
permissionIdintegerunique ID of the permission
labelstringlabel for the permission (as shown in the ThousandEyes roles interface)
isManagementPermissioninteger1 if the permission is classified as a management permission, 0 Otherwise

HTTP/1.1 200 OK Server: nginx Date: Mon, 09 May 2016 16:04:24 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 233 X-Organization-Rate-Limit-Reset: 1493736900 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-3

Body

{ "permissions": [ { "permissionId": 1, "label": "Assign users emails to alerts", "isManagementPermission": 0 }, { "permissionId": 51, "label": "View billing", "isManagementPermission": 1 }, ... ] }

For more information on our HTTP response status codes, see the response status codes documentation.

GET /v6/audit/user-events/search Activity log

Returns a list of activity log events. User with View activity log for all users in account group permission can see all activity log events in the current account group. User with View own activity log permission can see own activity log events in the current account group. See Account Context for more information on changing Account Group context.

Optional (querystring) Parameters

  • format=json|xml optional, specifies the format of output requested. See Output Formats for more information.
  • window=[0-9]+[smhdw]? specifies a window of time for the result set. See Time Ranges for more information.
  • from=YYYY-mm-ddTHH:MM:SS&to=YYYY-mm-ddTHH:MM:SS specifies an explicit start (and optionally, end) for your range of data. See Time Ranges for more information.
  • aid={aid} optional, changes the account group context of the current request. If an invalid account group ID is specified as a parameter, the response will come back as an HTTP/400 error.

Request

  • There is no request body for this request.
  • There are no request parameters for this request.

Example

$ curl https://api.thousandeyes.com/v6/audit/user-events/search.json \ -u noreply@thousandeyes.com:g351mw5xqhvkmh1vq6zfm51c62wyzib2

Response

Sends back an array of audit events.

FieldData TypeNotes
accountGroupNamestringthe name of the account group
aidintegersystem-generated unique ID of the account group
datedateTimedate of the event in YYYY-mm-dd HH:MM:SS format
eventstringevent type
ipAddressstringsource IP address of the user
uidintegerunique user ID of the user
userstringthe name and email address of the user

HTTP/1.1 200 OK Server: nginx Date: Wed, 21 Jun 2017 08:16:10 GMT Content-Type: application/json;charset=UTF-8 Transfer-Encoding: chunked Connection: keep-alive Cache-Control: no-store X-Organization-Rate-Limit-Limit: 240 X-Organization-Rate-Limit-Remaining: 234 X-Organization-Rate-Limit-Reset: 1498033020 Strict-Transport-Security: max-age=31536000 X-Server-Name: 1-5

Body

{ "auditEvents": [ { "accountGroupName": "API Sandbox", "aid": 75, "date": "2017-06-02 18:08:06", "event": "Login failed", "ipAddress": "192.88.158.246", "uid": 245, "user": "API Sandbox User (noreply@thousandeyes.com)" }, { "accountGroupName": "API Sandbox", "aid": 75, "date": "2017-05-02 13:53:31", "event": "Report created", "ipAddress": "192.88.158.246", "uid": 245, "user": "API Sandbox User (noreply@thousandeyes.com)" } ], "pages": { "current": 1 } }

For more information on our HTTP response status codes, see the response status codes documentation.