openapi: 3.0.0
security:
- BearerAuth: []
servers:
- description: ThousandEyes API production URL
url: https://api.thousandeyes.com/v7
info:
title: Templates API
version: 7.0.100
description: "**Note:** API operations for the creation or retrieval of API tests, Page Load tests, or Transaction tests\
\ are not available for ThousandEyes for Government instance.\n\nTemplates provide a streamlined approach to creating\
\ multiple tests (Synthetic/CEA and Endpoint), tags, alert rules, dashboards, labels (deprecated) and other assets within\
\ ThousandEyes from a single configuration file.\nTemplates make it easy to configure monitoring for even the most complex\
\ monitoring scenarios.\nThe following applies to templates:\n* ThousandEyes provides a pre-defined set of templates for\
\ monitoring common services and applications like Office365, Webex, Atlassian, Slack, custom network, HTTP, API, and\
\ Web targets.\n* You can easily create tests for monitoring common services and applications such as Office365, Webex,\
\ and others using the predefined set of ThousandEyes built-in templates.\n* Users can create their own templates, which\
\ are visible to any other users in the account group the template was created in, provided they have the `View Templates\
\ Read` permission.\n* Templates support dynamic user inputs, which are values provided by users when a template is deployed.\
\ Templates leverage Handlebars templating notation to allow dynamically configuring ThousandEyes resources based on user\
\ provided inputs.\n* Templates can be deployed from the UI or the API.\n* Credentials (usernames, passwords, tokens,\
\ etc.) may be included in a template only as placeholders whose value is provided by user input when deployed. Creating\
\ or updating a template that contains a credentials field in plain text will result in a bad request (ie, HTTP 400).\n\
* Templates can also use Handlebars template notation to reference fields of other assets defined in the template. To\
\ support this, assets are created in the order below, which also determines what other assets a given asset can reference\n\
(ex. Labels cannot reference other assets, Tests can reference labels and tags, etc.)\n 1. Labels\n 2. Tags\n 3. Tests\n\
\ 4. Endpoint Tests\n 5. Connected Devices Tests\n 6. Alert Rules\n 7. Dashboard Filters\n 8. Dashboards\n\nFor more\
\ information about Templates, see the [product documentation](https://docs.thousandeyes.com/product-documentation/internet-and-wan-monitoring/tests/test-templates).\n"
x-provenance:
method: harvested
authored_by: Cisco ThousandEyes
harvested_by: API Evangelist
harvested_on: '2026-08-19'
first_party: true
provider_published: true
source_host: pubhub.devnetcloud.com
note: 27 OpenAPI 3.0 documents (26 per-area plus a unified 326-operation document) served anonymously from Cisco's DevNet
CDN. api.thousandeyes.com itself 401s every path, so the contract is public while the API host is gated.
x-evidence:
- type: source
url: https://pubhub.devnetcloud.com/media/000-v7-apis/docs/reference/
- type: source
url: https://developer.cisco.com/docs/thousandeyes/
tags:
- name: Templates
paths:
/templates:
post:
tags:
- Templates
summary: Create template
description: Creates a template.
operationId: createTemplate
parameters:
- $ref: '#/components/parameters/AccountGroupId'
requestBody:
description: The template to create or update.
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
required: true
responses:
'201':
description: Created
headers:
Location:
style: simple
schema:
type: string
example: https://api.thousandeyes.com/v7/templates/fcbb89a7-61cf-4616-9c4f-828fa3cb4684
content:
application/hal+json:
schema:
$ref: '#/components/schemas/TemplateResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
get:
tags:
- Templates
summary: List templates
description: Retrieves a list of all your templates
operationId: getTemplates
parameters:
- $ref: '#/components/parameters/AccountGroupId'
- name: certificationLevel
in: query
description: Optional parameter to filter Templates by certification level
required: false
schema:
$ref: '#/components/schemas/CertificationLevel'
- name: module
in: query
description: Optional parameter to filter Templates by module
required: false
schema:
$ref: '#/components/schemas/TemplateModule'
- name: name
in: query
description: Optional parameter to filter the Templates by name; the search is case insensitive
required: false
schema:
type: string
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/TemplatesResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
/templates/{id}:
get:
tags:
- Templates
summary: Get template
description: Gets a template using its ID.
operationId: getTemplate
parameters:
- $ref: '#/components/parameters/IdTemplate'
- $ref: '#/components/parameters/AccountGroupId'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/TemplateResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
put:
tags:
- Templates
summary: Update template
operationId: updateTemplate
description: Updates an existing template. This operation overwrites the existing template object with the object sent
in the request. If a partial update is required, it is recommended that you retrieve the template and modify the template
object before updating it.
parameters:
- $ref: '#/components/parameters/IdTemplate'
- $ref: '#/components/parameters/AccountGroupId'
requestBody:
description: The template to create or update.
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
required: true
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/TemplateResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
delete:
tags:
- Templates
summary: Delete template
description: Deletes a template using its ID.
operationId: deleteTemplate
parameters:
- $ref: '#/components/parameters/IdTemplate'
- $ref: '#/components/parameters/AccountGroupId'
responses:
'204':
$ref: '#/components/responses/204'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
/templates/{id}/deploy:
post:
tags:
- Templates
summary: Deploy template
description: "Deploys a template, which will result in creating any of the tests, tags, alert rules, dashboards or other\
\ assets defined in the template.\nYou must specify any `userInputValues` required by the template in the request\
\ body. `userInputValues` enables you to specify a minimum set of user values required to configure the tests from\
\ a template. This way, you do not have to edit all the details of each test configuration. If necessary, you can\
\ edit the test details directly in the template.\n### Considerations\nConsider the following when deploying a template:\n\
* To deploy a template, you must first create a template or use one of ThousandEyes' built-in templates.\n* The deployment\
\ strategy allows you to specify what should happen to a particular asset in the event that a template is redeployed.\n\
\ When you attempt to deploy a template that has already been deployed, the API service compares any assets that\
\ have not yet been deployed with the assets that were deployed in the previous deployment (the comparison is done\
\ using the **asset key**; the asset keys are simply the object keys used in the `tests`, `labels`, `tags`, `alertRules`,\
\ and `dashboards` fields). By default, if the configuration of a particular asset has not changed from the previous\
\ deployment, that asset is ignored.\n If a change is detected:\n * If the asset is a test, a new test is created\
\ with the new configuration.\n * If the asset is not a test, the asset is updated.\n* Tags are deployed in two phases.\
\ Every field on the tag configuration except `assignments` (`key`, `value`, `objectType`, `accessType`, and optional\
\ `color`) is applied before dependent assets so that tag IDs are available for Handlebars references (for example,\
\ `{{tags.myTag.id}}`). The `assignments` field is applied after those assets exist (for example, after the tests\
\ you reference have been created), so it can resolve deployed IDs such as `{{tests.myTest.testId}}`. When tags are\
\ shared across multiple template deployments, existing assignments from other deployments are preserved because assignments\
\ are additive.\n* You can create new resources such as tests, tags, alert rules, labels, dashboards, and modify existing\
\ resources defined in templates, overwriting the default configurations.\n* You can also use existing resources (such\
\ as those created outside the template deployment flow) by adding their ID either in the raw template or using the\
\ overrides when deploying the template. See example usage below for the raw template sample.\n**Note**: The template\
\ API does not currently track \"live\" configuration of assets. Any changes made to assets outside of the template\
\ API will not be considered when comparing changes during the redeployment scenario.\n### Example usage:\n```POST\n\
/v7/tests/templates/fcbb89a7-61cf-4616-9c4f-828fa3cb4684/deploy\n{\n \"userInputValues\": {\n \"interval\": 120,\n\
\ \"target\": \"https://microsoft.com\",\n \"agents\": [{\"agentId\":11}],\n \"domain\": \"microsoft.com\"\
\n },\n \"name\":\"Microsoft Suite\",\n \"tests\": {\n \"secondPageLoadTest\": {\n \"httpInterval\": 120,\n\
\ \"interval\": 120,\n \"testId\": 182481,\n \"type\": \"page-load\",\n \"url\": \"https://microsoft.com\"\
,\n \"testName\": \"Microsoft Suite - Second Page Load\",\n \"agents\": [\n {\n \"agentId\"\
: 11\n }\n ]\n }\n }\n}\n```\n#### Raw Template Sample\n```\n{\n ...\n \"tests\": {\n \"existingTest\"\
: {\n \"testId\": \"123\", //The API will only try to update this test; will never create it\n \"\
type\": \"http-server\",\n ....\n },\n ...\n },\n ...\n}\n```"
operationId: deployTemplate
parameters:
- $ref: '#/components/parameters/IdTemplate'
- $ref: '#/components/parameters/AccountGroupId'
requestBody:
description: Deploy template
content:
application/json:
schema:
$ref: '#/components/schemas/DeployTemplate'
required: true
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/TemplateResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
/templates/{id}/sharing-settings:
get:
tags:
- Templates
summary: Get template sharing settings
operationId: getSharingSettings
parameters:
- $ref: '#/components/parameters/IdTemplate'
- $ref: '#/components/parameters/AccountGroupId'
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/SharingSettingsResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
put:
tags:
- Templates
summary: Update template sharing settings
operationId: updateSharingSettings
parameters:
- $ref: '#/components/parameters/IdTemplate'
- $ref: '#/components/parameters/AccountGroupId'
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SharingSettings'
required: true
responses:
'200':
description: OK
content:
application/hal+json:
schema:
$ref: '#/components/schemas/SharingSettingsResponse'
'400':
$ref: '#/components/responses/400'
'401':
$ref: '#/components/responses/401'
'403':
$ref: '#/components/responses/403'
'404':
$ref: '#/components/responses/404'
'500':
$ref: '#/components/responses/500'
components:
securitySchemes:
BearerAuth:
type: http
scheme: bearer
description: Bearer authentication token
schemas:
Template:
title: Template
required:
- name
description: The template to create or update.
type: object
properties:
name:
type: string
description: The name of the template.
example: My Template
description:
type: string
description: Text that describes the template.
example: A description of My Template
icon:
$ref: '#/components/schemas/TemplateIcon'
isBuiltIn:
type: boolean
description: Indicates whether the template is a built-in template. This field is read-only for normal users.
example: false
schemaVersion:
$ref: '#/components/schemas/SchemaVersionConfig'
certificationLevel:
$ref: '#/components/schemas/CertificationLevel'
description: 'The certification level of the Template. Normal users may only create `user` templates.
'
example: user
userInputs:
description: 'A map of <key, UserInput>. User Inputs are values that the user must fill in order for
the Template to deploy. User Inputs are like variables that can be used for dynamically setting just
about any field in the Template, including fields for Tests, Labels, Dashboards, and most other template assets.
User Inputs are referenced using Handlebars template substitution notation. For example:
`"testName": "{{userInputs.targetDomain}} - HTTP"`
The [Handlebars Syntax](https://handlebarsjs.com/guide/builtin-helpers.html) also supports basic logic operations
and iterators that allow creating powerful and flexible templates.
'
type: object
additionalProperties:
$ref: '#/components/schemas/UserInput'
example:
targetDomain:
name: Target Domain
description: Name of target domain that will be used for configuring tests in this template.
type: string
region:
name: Cloud Region
description: The available cloud regions to target.
type: string
allowedValues:
- name: West
value: us-west-1
- name: East
value: us-east-2
agents:
name: Source Agents
description: The agents that will be used by the tests in this template.
type: agents
groupings:
uniqueItems: true
type: array
description: An ordered list of groupings that organize template objects, such as user inputs or tests.
example:
- name: personalize
title: Personalize your dashboard
description: Allow you to personalize your dashboard
type: user-input
items:
- dashboardTitle
- dashboardDescription
- dashboardFilterTitle
- name: dns-test-group
title: DNS Tests
description: Grouped by DNS test type
type: test
items:
- dnsTest-microsoft365
- dnsTest-sharepoint
- dnsTest-microsoftlogin
- dnsTest-onedrive
- dnsTest-outlook
items:
$ref: '#/components/schemas/TemplateGrouping'
labels:
type: object
description: 'A map of <name, Label> objects. These are ThousandEyes Labels that will be created when the template
is deployed.
**Deprecation notice:** Labels are based on the V6 API, which is deprecated and has no V7 equivalent.
Use `tags` instead, which provide enhanced functionality with full V7 API support.
Do not use `labels` and `tags` together in the same template; prefer `tags` for all new templates.
'
deprecated: true
additionalProperties:
$ref: '#/components/schemas/LabelConfigurationTemplate'
example:
myLabel:
name: My Label
tests:
- testId: 123
externalDocs:
url: https://developer.cisco.com/docs/thousandeyes/v6/update-a-label
tests:
type: object
description: 'A map of <name, TestConfiguration> objects. These are the ThousandEyes CEA/Synthetic tests that will
be created when the template is deployed.
'
additionalProperties:
$ref: '#/components/schemas/TestConfigurationTemplate'
example:
httpServerTest:
testName: '{{name}} - HTTP Server'
type: http-server
tagIds:
- '{{tags.webHealthDashTag.id}}'
- '{{tags.templateTag.id}}'
interval: '{{userInputs.interval}}'
url: https://{{userInputs.domain}}
agents: '{{userInputs.agents}}'
networkTest:
testName: '{{name}} - Network'
type: agent-to-server
server: '{{userInputs.domain}}'
protocol: TCP
port: '{{userInputs.port}}'
tagIds:
- '{{tags.webHealthDashTag.id}}'
- '{{tags.templateTag.id}}'
interval: '{{userInputs.interval}}'
url: https://{{userInputs.domain}}
agents: '{{userInputs.agents}}'
dnsTest:
testName: '{{name}} - DNS'
type: dns-server
domain: '{{userInputs.domain}} A'
tagIds:
- '{{tags.webHealthDashTag.id}}'
- '{{tags.templateTag.id}}'
interval: '{{userInputs.interval}}'
dnsServers: '{{userInputs.dnsServers}}'
agents: '{{userInputs.agents}}'
endpointTests:
type: object
description: 'A map of <name, EndpointTestConfiguration> objects. These are the Endpoint tests that will be created
when the template is deployed. Field values support Handlebars template substitution.
'
additionalProperties:
$ref: '#/components/schemas/EndpointTestConfigTemplate'
example:
endpointTests:
scheduledHttpTest:
name: Scheduled HTTP Test
testType: Http
testCategory: SCHEDULED_TEST
genericConfig:
interval: 3600
networkConfig:
flagPing: true
httpConfig:
url: https://{{userInputs.tenantName}}-my.sharepoint.com
machineConfig:
monitoringSettingsType: ANY_AGENT
agentIds: '{{userInputs.endpointAgents}}'
tags:
type: object
description: 'A map of <name, TagConfiguration> objects. These are ThousandEyes Tags that will be created when the
template is deployed.
Tags use a key/value model and can be assigned to tests, endpoint tests, connected devices tests, and dashboards.
Tag IDs can be referenced in other template assets using Handlebars notation,
e.g., `"tagIds": ["{{tags.myTag.id}}"]`.
'
additionalProperties:
$ref: '#/components/schemas/TagConfigurationTemplate'
example:
webHealthDashTag:
key: Health Overview Dashboard
value: Health Overview Dashboard
objectType: test
accessType: all
templateTag:
key: '{{name}}'
value: '{{name}}'
objectType: test
accessType: all
alertRules:
type: object
description: 'A map of <key, AlertRuleConfigurationTemplate> objects. These are the set of Alert Rules that will
be created when the template is deployed.
'
additionalProperties:
$ref: '#/components/schemas/AlertRuleConfigurationTemplate'
description: 'An Alert Rule object. Values can be templated with Handlebars notation. As such, the Alert Rule
object is defined here as
a set of key/value pairs. See external docs for schema details.
'
example:
httpAlert:
alertType: HTTP Server
ruleName: '{{userInputs.tenantName}} - Alert Rule'
expression: ((totalTime >= 500 ms) && (responseTime >= 500 ms))
roundsViolatingRequired: 1
roundsViolatingOutOf: 1
testIds:
- '{{tests.pageLoadTest.testId}}'
dashboards:
description: 'A map of <key, DashboardConfiguration> objects. These are the set of dashboards that will be created
when the template is deployed. Dashboard fields support Handlebars notation.
'
type: object
additionalProperties:
$ref: '#/components/schemas/DashboardConfigurationTemplate'
example:
myDashboard:
title: My Dashboard
widgets:
- filters:
Test Labels: '[{{labels.templateLabel.groupId}}]'
type: 'Bar Chart: Stacked'
title: 'A Bar Chart: Stacked widget'
metricGroup: Web - HTTP Server
measure:
type: Median
metric: Response Time
axisGroupBy: Continents
dataSource: Cloud & Enterprise Agents
dashboardFilters:
type: object
description: A map of <key, DashboardFilter> objects. These will be the dashboard filters created when the template
is deployed.
additionalProperties:
$ref: '#/components/schemas/DashboardFilterConfigurationTemplate'
example:
netHealthDashboardFilter:
name: '{{userInputs.dashboardFilterTitle}}'
context:
- dataSourceId: VIRTUAL_AGENT
filters:
- filterId: TEST_LABEL
metricIds:
- NET_LOSS
- NET_LATENCY
- NET_JITTER
values:
- '{{labels.testLabel.groupId}}'
deploymentStrategy:
description: "A map of <assetKey, DeploymentStrategy> values. The `deploymentStrategy` field defines how the system\
\ behaves when an asset (test, label, tag, dashboard) defined in the template already exists.\nThe `assetKey`\
\ identifies the asset that the deployment strategy will apply to.\nFor tests, the system uses the test type and\
\ name to determine if a test already exists. For example, if a template contains an http-server test named `Test123`\
\ and an http-server test with the same name already exists, the system assumes that this test already exists.\
\ If the test had a different type (for example, page-load), then the system would not consider the test to already\
\ exist because the types are different.\nFor Labels and Dashboards, the system uses only the name. For Tags,\
\ the unique key is determined by the combination of `key`, `value`, and `objectType`.\nAlert Rules do not currently\
\ support `deploymentStrategy`.\nBelow are the possible deployment strategies and their behaviors:\n * `create`\
\ - The system will always attempt to create the asset. If an asset of the same name and type already exists,\
\ the system will generate an error. This behavior ensures that each asset created from a template is unique.\
\ This is the default behavior.\n * `update` - If an asset of the same type and name already exists, the existing\
\ asset is used instead of creating a new asset. If the configuration of the asset in the template is different\
\ from the existing one, the latest configuration is applied.\n * `ignore` - If an asset of the same type and\
\ name already exists, the existing asset is used instead of creating a new asset. If the configuration of the\
\ asset in the template is different from the existing one, the configuration of the existing asset is used and\
\ the configuration in the template is ignored.\nThe `update` and `ignore` strategies essentially allow assets\
\ to be shared across templates. For example, the built-in \"Custom Web Page\", \"Custom Web Server\", and \"\
Custom Device\" templates all contain a Dashboard asset called \"Health Overview\". It's `deploymentStrategy`\
\ is set to `ignore`, which means that the first deployment of a template such as the \"Custom Web Page\" template\
\ creates the \"Health Overview\" dashboard. Subsequent deployments of the \"Custom Web Page\" template do not\
\ attempt to recreate the \"Health Overview\" dashboard. Instead, the existing dashboard is reused.\nNote: Assets\
\ that were not created using a template are not included when the system searches for existing assets; they are\
\ not used with `update` or `ignore`.\n"
type: object
additionalProperties:
$ref: '#/components/schemas/DeploymentStrategy'
example:
testVoiceLabel: update
testVideoLabel: update
testLabel: update
webHealthDashTag: update
templateTag: update
dnsTest: ignore
webexDashboard: ignore
serverTest: create
resourceInclusion:
description: "A map of `<assetKey, ResourceInclusion>` pairs. The `resourceInclusion` field specifies whether an\
\ asset (such as a test, endpoint test, label, tag, dashboard, or alert rule) should be included in a deployment.\n\
The `assetKey` identifies the specific asset to which the inclusion rule applies.\nPossible resource inclusion\
\ values for each asset:\n * `included` - The system will always create the asset.\n * `skipped` - The system\
\ will not create the asset.\nIf an `assetKey` is not present in the `resourceInclusion` map, it defaults to `included`.\n\
**Note**: The deployment payload can override the `resourceInclusion` value defined in a template.\n"
type: object
additionalProperties:
$ref: '#/components/schemas/ResourceInclusion'
example:
testLabel: skipped
dnsTest: skipped
webexDashboard: included
modules:
uniqueItems: true
type: array
description: ThousandEyes modules this template belongs to. Regular users can only set this to `default`.
example:
- default
items:
$ref: '#/components/schemas/TemplateModule'
UserInput:
description: 'A user input is a value that the user must provide when deploying a template.
User Input values are provided by the user in the UI under the **Global Settings** section.
When deploying via the API, User Inputs values are specified in the payload using the `userInputValues` field.
'
required:
- name
- type
type: object
properties:
name:
type: string
description: The name of the user input field.
example: target
type:
$ref: '#/components/schemas/UserInputType'
title:
type: string
description: The title of the user input field; may be used by UI.
example: Test Target
description:
type: string
description: Description of the user input field; used by UI.
example: The target of the Tests
defaultValue:
$ref: '#/components/schemas/UserInputValue'
description: Default value of user input field.
example: https://google.com
allowedValues:
type: array
description: Allowed values for the User Input. An array of name/value pairs that specify specific values that can
be used with the User Input. In the UI, user inputs with `allowedValues` will be displayed as a drop down selector;
the `name` will be used as the display text.
items:
$ref: '#/components/schemas/UserInputAllowedValue'
UserInputAllowedValue:
type: object
description: The list of values that the user is allowed to use as inputs.
properties:
value:
$ref: '#/components/schemas/UserInputValue'
name:
type: string
description: The name of the value, which will be used for display in the UI and API messages.
example: West
UserInputValue:
description: A user input value. The type of object depends on the user input `type` field.
anyOf:
- type: string
- type: number
- type: object
- type: array
items:
type: string
- type: array
items:
type: number
- type: array
items:
type: object
example: us-west-1
UserInputType:
type: string
# --- truncated at 32 KB (126 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/thousandeyes/refs/heads/main/openapi/thousandeyes-templates-openapi.yml