openapi: 3.0.0
info:
title: InfluxDB Cloud API Service Authorizations (API tokens) Authorizations (API tokens) Templates API
version: 2.0.1
description: 'The InfluxDB v2 API provides a programmatic interface for all interactions with InfluxDB. Access the InfluxDB API using the `/api/v2/` endpoint.
'
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: /api/v2
security:
- TokenAuthentication: []
tags:
- name: Templates
description: 'Export and apply InfluxDB **templates**.
Manage **stacks** of templated InfluxDB resources.
InfluxDB templates are prepackaged configurations for resources.
Use InfluxDB templates to configure a fresh instance of InfluxDB,
back up your dashboard configuration, or share your configuration.
Use the `/api/v2/templates` endpoints to export templates and apply templates.
**InfluxDB stacks** are stateful InfluxDB templates that let you
add, update, and remove installed template resources over time, avoid duplicating
resources when applying the same or similar templates more than once, and
apply changes to distributed instances of InfluxDB OSS or InfluxDB Cloud.
Use the `/api/v2/stacks` endpoints to manage installed template resources.
### Related guides
- [InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/)
- [InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/)
'
paths:
/stacks:
get:
operationId: ListStacks
tags:
- Templates
summary: List installed stacks
description: 'Lists installed InfluxDB stacks.
To limit stacks in the response, pass query parameters in your request.
If no query parameters are passed, InfluxDB returns all installed stacks
for the organization.
#### Related guides
- [View InfluxDB stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/).
'
parameters:
- in: query
name: orgID
required: true
schema:
type: string
description: "An organization ID.\nOnly returns stacks owned by the specified [organization](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#organization).\n\n#### InfluxDB Cloud\n\n- Doesn't require this parameter;\n InfluxDB only returns resources allowed by the API token.\n"
- in: query
name: name
schema:
type: string
description: 'A stack name.
Finds stack `events` with this name and returns the stacks.
Repeatable.
To filter for more than one stack name,
repeat this parameter with each name--for example:
- `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&name=project-stack-0&name=project-stack-1`
'
examples:
findStackByName:
summary: Find stacks with the event name
value: project-stack-0
- in: query
name: stackID
schema:
type: string
description: 'A stack ID.
Only returns the specified stack.
Repeatable.
To filter for more than one stack ID,
repeat this parameter with each ID--for example:
- `INFLUX_URL/api/v2/stacks?&orgID=INFLUX_ORG_ID&stackID=09bd87cd33be3000&stackID=09bef35081fe3000`
'
examples:
findStackByID:
summary: Find a stack with the ID
value: 09bd87cd33be3000
responses:
'200':
description: Success. The response body contains the list of stacks.
content:
application/json:
schema:
type: object
properties:
stacks:
type: array
items:
$ref: '#/components/schemas/Stack'
'400':
description: 'Bad request.
The response body contains detail about the error.
#### InfluxDB OSS
- Returns this error if an incorrect value is passed in the `org` parameter or `orgID` parameter.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
orgIdMissing:
summary: The orgID query parameter is missing
value:
code: invalid
message: 'organization id[""] is invalid: id must have a length of 16 bytes'
orgProvidedNotFound:
summary: The org or orgID passed doesn't own the token passed in the header
value:
code: invalid
message: 'failed to decode request body: organization not found'
'401':
$ref: '#/components/responses/AuthorizationError'
'500':
$ref: '#/components/responses/InternalServerError'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
post:
operationId: CreateStack
tags:
- Templates
summary: Create a stack
description: "Creates or initializes a stack.\n\nUse this endpoint to _manually_ initialize a new stack with the following\noptional information:\n\n - Stack name\n - Stack description\n - URLs for template manifest files\n\nTo automatically create a stack when applying templates,\nuse the [/api/v2/templates/apply endpoint](#operation/ApplyTemplate).\n\n#### Required permissions\n\n- `write` permission for the organization\n\n#### Related guides\n\n- [Initialize an InfluxDB stack](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/init/).\n- [Use InfluxDB templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#apply-templates-to-an-influxdb-instance).\n"
requestBody:
description: The stack to create.
required: true
content:
application/json:
schema:
type: object
title: PostStackRequest
properties:
orgID:
type: string
name:
type: string
description:
type: string
urls:
type: array
items:
type: string
responses:
'201':
description: Success. Returns the newly created stack.
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
'401':
$ref: '#/components/responses/AuthorizationError'
'422':
description: 'Unprocessable entity.
The error may indicate one of the following problems:
- The request body isn''t valid--the request is well-formed, but InfluxDB can''t process it due to semantic errors.
- You passed a parameter combination that InfluxDB doesn''t support.
'
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'500':
$ref: '#/components/responses/InternalServerError'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/stacks/{stack_id}:
get:
operationId: ReadStack
tags:
- Templates
summary: Retrieve a stack
parameters:
- in: path
name: stack_id
required: true
schema:
type: string
description: The identifier of the stack.
responses:
'200':
description: Returns the stack.
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
patch:
operationId: UpdateStack
tags:
- Templates
summary: Update a stack
parameters:
- in: path
name: stack_id
required: true
schema:
type: string
description: The identifier of the stack.
requestBody:
description: The stack to update.
required: true
content:
application/json:
schema:
type: object
title: PatchStackRequest
properties:
name:
type: string
nullable: true
description:
type: string
nullable: true
templateURLs:
type: array
items:
type: string
nullable: true
additionalResources:
type: array
items:
type: object
properties:
resourceID:
type: string
kind:
type: string
templateMetaName:
type: string
required:
- kind
- resourceID
responses:
'200':
description: Returns the updated stack.
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
delete:
operationId: DeleteStack
tags:
- Templates
summary: Delete a stack and associated resources
parameters:
- in: path
name: stack_id
required: true
schema:
type: string
description: The identifier of the stack.
- in: query
name: orgID
required: true
schema:
type: string
description: The identifier of the organization.
responses:
'204':
description: The stack and its associated resources were deleted.
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/stacks/{stack_id}/uninstall:
post:
operationId: UninstallStack
tags:
- Templates
summary: Uninstall a stack
parameters:
- in: path
name: stack_id
required: true
schema:
type: string
description: The identifier of the stack.
responses:
'200':
description: Returns the uninstalled stack.
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/templates/apply:
post:
operationId: ApplyTemplate
tags:
- Templates
summary: Apply or dry-run a template
description: "Applies a template to\ncreate or update a [stack](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/) of InfluxDB\n[resources](https://docs.influxdata.com/influxdb/cloud/reference/cli/influx/export/all/#resources).\nThe response contains the diff of changes and the stack ID.\n\nUse this endpoint to install an InfluxDB template to an organization.\nProvide template URLs or template objects in your request.\nTo customize which template resources are installed, use the `actions`\nparameter.\n\nBy default, when you apply a template, InfluxDB installs the template to\ncreate and update stack resources and then generates a diff of the changes.\nIf you pass `dryRun: true` in the request body, InfluxDB validates the\ntemplate and generates the resource diff, but doesn’t make any\nchanges to your instance.\n\n#### Custom values for templates\n\n- Some templates may contain [environment references](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/create/#include-user-definable-resource-names) for custom metadata.\n To provide custom values for environment references, pass the _`envRefs`_\n property in the request body.\n For more information and examples, see how to\n [define environment references](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#define-environment-references).\n\n- Some templates may contain queries that use\n [secrets](https://docs.influxdata.com/influxdb/cloud/security/secrets/).\n To provide custom secret values, pass the _`secrets`_ property\n in the request body.\n Don't expose secret values in templates.\n For more information, see [how to pass secrets when installing a template](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/#pass-secrets-when-installing-a-template).\n\n#### Required permissions\n\n- `write` permissions for resource types in the template.\n\n#### Rate limits (with InfluxDB Cloud)\n\n- Adjustable service quotas apply.\n For more information, see [limits and adjustable quotas](https://docs.influxdata.com/influxdb/cloud/account-management/limits/).\n\n#### Related guides\n\n- [Use templates](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/use/)\n- [Stacks](https://docs.influxdata.com/influxdb/cloud/influxdb-templates/stacks/)\n"
requestBody:
required: true
description: 'Parameters for applying templates.
'
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateApply'
examples:
skipKindAction:
summary: Skip all bucket and task resources in the provided templates
value:
orgID: INFLUX_ORG_ID
actions:
- action: skipKind
properties:
kind: Bucket
- action: skipKind
properties:
kind: Task
templates:
- contents:
- '[object Object]': null
skipResourceAction:
summary: Skip specific resources in the provided templates
value:
orgID: INFLUX_ORG_ID
actions:
- action: skipResource
properties:
kind: Label
resourceTemplateName: foo-001
- action: skipResource
properties:
kind: Bucket
resourceTemplateName: bar-020
- action: skipResource
properties:
kind: Bucket
resourceTemplateName: baz-500
templates:
- contents:
- apiVersion: influxdata.com/v2alpha1
kind: Bucket
metadata:
name: baz-500
templateObjectEnvRefs:
summary: envRefs for template objects
value:
orgID: INFLUX_ORG_ID
envRefs:
linux-cpu-label: MY_CPU_LABEL
docker-bucket: MY_DOCKER_BUCKET
docker-spec-1: MY_DOCKER_SPEC
templates:
- contents:
- apiVersion: influxdata.com/v2alpha1
kind: Label
metadata:
name:
envRef:
key: linux-cpu-label
spec:
color: '#326BBA'
name: inputs.cpu
- contents:
- apiVersion: influxdata.com/v2alpha1
kind: Bucket
metadata:
name:
envRef:
key: docker-bucket
application/x-jsonnet:
schema:
$ref: '#/components/schemas/TemplateApply'
text/yml:
schema:
$ref: '#/components/schemas/TemplateApply'
x-codeSamples:
- lang: Shell
label: 'cURL: Dry run with a remote template'
source: "curl --request POST \"http://localhost:8086/api/v2/templates/apply\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --data @- << EOF\n {\n \"dryRun\": true,\n \"orgID\": \"INFLUX_ORG_ID\",\n \"remotes\": [\n {\n \"url\": \"https://raw.githubusercontent.com/influxdata/community-templates/master/linux_system/linux_system.yml\"\n }\n ]\n }\nEOF\n"
- lang: Shell
label: 'cURL: Apply with secret values'
source: "curl \"http://localhost:8086/api/v2/templates/apply\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --data @- << EOF | jq .\n {\n \"orgID\": \"INFLUX_ORG_ID\",\n \"secrets\": {\n \"SLACK_WEBHOOK\": \"YOUR_SECRET_WEBHOOK_URL\"\n },\n \"remotes\": [\n {\n \"url\": \"https://raw.githubusercontent.com/influxdata/community-templates/master/fortnite/fn-template.yml\"\n }\n ]\n }\nEOF\n"
- lang: Shell
label: 'cURL: Apply template objects with environment references'
source: "curl --request POST \"http://localhost:8086/api/v2/templates/apply\" \\\n --header \"Authorization: Token INFLUX_API_TOKEN\" \\\n --data @- << EOF\n { \"orgID\": \"INFLUX_ORG_ID\",\n \"envRefs\": {\n \"linux-cpu-label\": \"MY_CPU_LABEL\",\n \"docker-bucket\": \"MY_DOCKER_BUCKET\",\n \"docker-spec-1\": \"MY_DOCKER_SPEC\"\n },\n \"templates\": [\n { \"contents\": [{\n \"apiVersion\": \"influxdata.com/v2alpha1\",\n \"kind\": \"Label\",\n \"metadata\": {\n \"name\": {\n \"envRef\": {\n \"key\": \"linux-cpu-label\"\n }\n }\n },\n \"spec\": {\n \"color\": \"#326BBA\",\n \"name\": \"inputs.cpu\"\n }\n }]\n },\n \"templates\": [\n { \"contents\": [{\n \"apiVersion\": \"influxdata.com/v2alpha1\",\n \"kind\": \"Label\",\n \"metadata\": {\n \"name\": {\n \"envRef\": {\n \"key\": \"linux-cpu-label\"\n }\n }\n },\n \"spec\": {\n \"color\": \"#326BBA\",\n \"name\": \"inputs.cpu\"\n }\n }]\n },\n { \"contents\": [{\n \"apiVersion\": \"influxdata.com/v2alpha1\",\n \"kind\": \"Bucket\",\n \"metadata\": {\n \"name\": {\n \"envRef\": {\n \"key\": \"docker-bucket\"\n }\n }\n }\n }]\n }\n ]\n }\nEOF\n"
responses:
'200':
description: 'Success.
The template dry run succeeded.
The response body contains a resource diff of changes that the
template would have made if installed.
No resources were created or updated.
The diff and summary won''t contain IDs for resources
that didn''t exist at the time of the dry run.
'
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateSummary'
'201':
description: 'Success.
The template applied successfully.
The response body contains the stack ID, a diff, and a summary.
The diff compares the initial state to the state after the template installation.
The summary contains newly created resources.
'
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateSummary'
'422':
description: 'Unprocessable entity.
The error may indicate one of the following problems:
- The template failed validation.
- You passed a parameter combination that InfluxDB doesn''t support.
'
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/TemplateSummary'
- type: object
required:
- message
- code
properties:
message:
type: string
code:
type: string
'500':
description: "Internal server error.\n\n#### InfluxDB Cloud\n\n- Returns this error if creating one of the template\n resources (bucket, dashboard, task, user) exceeds your plan’s\n adjustable service quotas.\n"
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
examples:
createExceedsQuota:
summary: 'InfluxDB Cloud: Creating resource would exceed quota.'
value:
code: internal error
message: "resource_type=\"tasks\" err=\"failed to apply resource\"\n\tmetadata_name=\"alerting-gates-b84003\" err_msg=\"failed to create tasks[\\\"alerting-gates-b84003\\\"]: creating task would exceed quota\""
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
/templates/export:
post:
operationId: ExportTemplate
tags:
- Templates
summary: Export a new template
requestBody:
description: Export resources as an InfluxDB template.
required: false
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TemplateExportByID'
- $ref: '#/components/schemas/TemplateExportByName'
responses:
'200':
description: The template was created successfully. Returns the newly created template.
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
application/x-yaml:
schema:
$ref: '#/components/schemas/Template'
default:
description: Unexpected error
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
components:
schemas:
TableViewProperties:
type: object
required:
- type
- queries
- colors
- shape
- note
- showNoteWhenEmpty
- tableOptions
- fieldOptions
- timeFormat
- decimalPlaces
properties:
type:
type: string
enum:
- table
queries:
type: array
items:
$ref: '#/components/schemas/DashboardQuery'
colors:
description: Colors define color encoding of data into a visualization
type: array
items:
$ref: '#/components/schemas/DashboardColor'
shape:
type: string
enum:
- chronograf-v2
note:
type: string
showNoteWhenEmpty:
description: If true, will display note when empty
type: boolean
tableOptions:
type: object
properties:
verticalTimeAxis:
description: verticalTimeAxis describes the orientation of the table by indicating whether the time axis will be displayed vertically
type: boolean
sortBy:
$ref: '#/components/schemas/RenamableField'
wrapping:
description: Wrapping describes the text wrapping style to be used in table views
type: string
enum:
- truncate
- wrap
- single-line
fixFirstColumn:
description: fixFirstColumn indicates whether the first column of the table should be locked
type: boolean
fieldOptions:
description: fieldOptions represent the fields retrieved by the query with customization options
type: array
items:
$ref: '#/components/schemas/RenamableField'
timeFormat:
description: timeFormat describes the display format for time values according to moment.js date formatting
type: string
decimalPlaces:
$ref: '#/components/schemas/DecimalPlaces'
BuilderTagsType:
type: object
properties:
key:
type: string
values:
type: array
items:
type: string
aggregateFunctionType:
$ref: '#/components/schemas/BuilderAggregateFunctionType'
TemplateEnvReferences:
type: array
items:
type: object
properties:
resourceField:
type: string
description: Field the environment reference corresponds too
envRefKey:
type: string
description: Key identified as environment reference and is the key identified in the template
value:
description: Value provided to fulfill reference
nullable: true
oneOf:
- type: string
- type: integer
- type: number
- type: boolean
defaultValue:
description: Default value that will be provided for the reference when no value is provided
nullable: true
oneOf:
- type: string
- type: integer
- type: number
- type: boolean
required:
- resourceField
- envRefKey
StaticLegend:
description: StaticLegend represents the options specific to the static legend
type: object
properties:
colorizeRows:
type: boolean
heightRatio:
type: number
format: float
show:
type: boolean
opacity:
type: number
format: float
orientationThreshold:
type: integer
valueAxis:
type: string
widthRatio:
type: number
format: float
QueryEditMode:
type: string
enum:
- builder
- advanced
GeoViewLayerProperties:
type: object
required:
- type
properties:
type:
type: string
enum:
- heatmap
- circleMap
- pointMap
- trackMap
ColorMapping:
type: object
description: A color mapping is an object that maps time series data to a UI color scheme to allow the UI to render graphs consistent colors across reloads.
additionalProperties:
type: string
example:
series_id_1: '#edf529'
series_id_2: '#edf529'
measurement_birdmigration_europe: '#663cd0'
configcat_deployments-autopromotionblocker: '#663cd0'
ViewProperties:
oneOf:
- $ref: '#/components/schemas/LinePlusSingleStatProperties'
- $ref: '#/components/schemas/XYViewProperties'
- $ref: '#/components/schemas/SingleStatViewProperties'
- $ref: '#/components/schemas/HistogramViewProperties'
- $ref: '#/components/schemas/GaugeViewProperties'
- $ref: '#/components/schemas/TableViewProperties'
- $ref: '#/components/schemas/SimpleTableViewProperties'
- $ref: '#/components/schemas/MarkdownViewProperties'
- $ref: '#/components/schemas/CheckViewProperties'
- $ref: '#/components/schemas/ScatterViewProperties'
- $ref: '#/components/schemas/HeatmapViewProperties'
- $ref: '#/components/schemas/MosaicViewProperties'
- $ref: '#/components/schemas/BandViewProperties'
- $ref: '#/components/schemas/GeoViewProperties'
RetentionRules:
type: array
description: 'Retention rules to expire or retain data.
The InfluxDB `/api/v2` API uses `RetentionRules` to configure the [retention period](https://docs.influxdata.com/influxdb/cloud/reference/glossary/#retention-period).
#### InfluxDB Cloud
- `retentionRules` is required.
#### InfluxDB OSS
- `retentionRules` isn''t required.
'
items:
$ref: '#/components/schemas/RetentionRule'
BuilderConfig:
type: object
properties:
buckets:
type: array
items:
type: string
tags:
type: array
items:
$ref: '#/components/schemas/BuilderTagsType'
functions:
type: array
items:
$ref: '#/components/schemas/BuilderFunctionsType'
aggregateWindow:
type: object
properties:
period:
type: string
fillValues:
type: boolean
GaugeViewProperties:
type: object
required:
- type
- queries
- colors
- shape
- note
- showNoteWhenEmpty
- prefix
- tickPrefix
- suffix
- tickSuffix
- decimalPlaces
properties:
type:
type: string
enum:
- gauge
queries:
type: array
items:
$ref: '#/components/schemas/DashboardQuery'
colors:
description: Colors define color encoding of data into a visualization
type: array
items:
$ref: '#/components/schemas/DashboardColor'
shape:
type: string
enum:
- chronograf-v2
note:
type: string
showNoteWhenEmpty:
description: If true, will display note when empty
type: boolean
prefix:
type: string
tickPrefix:
type: string
suffix:
type: string
tickSuffix:
type: string
decimalPlaces:
$ref: '#/components/schemas/DecimalPlaces'
CustomCheck:
allOf:
- $ref: '#/components/schemas/CheckBase'
- type: object
properties:
type:
type: string
enum:
- custom
required:
- type
Link:
type: string
format: uri
readOnly: true
description: URI of resource.
DashboardQuery:
type: object
properties:
text:
type: string
description: The text of the Flux query.
editMode:
$ref: '#/components/schemas/QueryEditMode'
name:
type: string
builderConfig:
$ref: '#/components/schemas/BuilderConfig'
TemplateSummaryLabel:
type: object
properties:
id:
type: string
orgID:
type: string
kind:
$ref: '#/components/schemas/TemplateKind'
templateMetaName:
type: string
name:
type: string
properties:
type: object
properties:
color:
type: string
description:
type: string
envReferences:
$ref: '#/components/schemas/TemplateEnvReferences'
TemplateSummary:
type: object
properties:
sources:
type: array
items:
type: string
stackID:
type: string
summary:
type: object
properties:
buckets:
type: array
items:
type: object
properties:
id:
type: string
orgID:
type: string
kind:
$ref: '#/components/schemas/TemplateKind'
templateMetaName:
type: string
name:
type: string
description:
type: string
# --- truncated at 32 KB (113 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/influxdata/refs/heads/main/openapi/influxdata-templates-api-openapi.yml