openapi: 3.0.0
info:
title: Complete InfluxDB Cloud Authorizations (API tokens) Authorizations (API tokens) Templates API
description: 'Create and manage authorizations (API tokens).
An _authorization_ contains a list of `read` and `write`
permissions for organization resources and provides an API token for authentication.
An authorization belongs to an organization and only contains permissions for that organization.
We recommend the following for managing your tokens:
- Create a generic user to create and manage tokens for writing data.
- Store your tokens in a secure password vault for future access.
### User sessions with authorizations
Optionally, when creating an authorization, you can scope it to a specific user.
If the user signs in with username and password, creating a _user session_,
the session carries the permissions granted by all the user''s authorizations.
For more information, see [how to assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/).
To create a user session, use the [`POST /api/v2/signin` endpoint](#operation/PostSignin).
### Related endpoints
- [Signin](#tag/Signin)
- [Signout](#tag/Signout)
### Related guides
- [Authorize API requests](https://docs.influxdata.com/influxdb/cloud/api-guide/api_intro/#authentication)
- [Manage API tokens](https://docs.influxdata.com/influxdb/cloud/security/tokens/)
- [Assign a token to a specific user](https://docs.influxdata.com/influxdb/cloud/security/tokens/create-token/)
'
servers:
- url: ''
security:
- TokenAuthentication: []
tags:
- 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/)
'
name: Templates
paths:
/api/v2/stacks:
get:
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/).
'
operationId: ListStacks
parameters:
- 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: orgID
required: true
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: name
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
in: query
name: stackID
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
stacks:
items:
$ref: '#/components/schemas/Stack'
type: array
type: object
description: Success. The response body contains the list of stacks.
'400':
content:
application/json:
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'
schema:
$ref: '#/components/schemas/Error'
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.
'
'401':
$ref: '#/components/responses/AuthorizationError'
'500':
$ref: '#/components/responses/InternalServerError'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: List installed stacks
tags:
- Templates
post:
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"
operationId: CreateStack
requestBody:
content:
application/json:
schema:
properties:
description:
type: string
name:
type: string
orgID:
type: string
urls:
items:
type: string
type: array
title: PostStackRequest
type: object
description: The stack to create.
required: true
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
description: Success. Returns the newly created stack.
'401':
$ref: '#/components/responses/AuthorizationError'
'422':
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
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.
'
'500':
$ref: '#/components/responses/InternalServerError'
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Create a stack
tags:
- Templates
/api/v2/stacks/{stack_id}:
delete:
operationId: DeleteStack
parameters:
- description: The identifier of the stack.
in: path
name: stack_id
required: true
schema:
type: string
- description: The identifier of the organization.
in: query
name: orgID
required: true
schema:
type: string
responses:
'204':
description: The stack and its associated resources were deleted.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Delete a stack and associated resources
tags:
- Templates
get:
operationId: ReadStack
parameters:
- description: The identifier of the stack.
in: path
name: stack_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
description: Returns the stack.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Retrieve a stack
tags:
- Templates
patch:
operationId: UpdateStack
parameters:
- description: The identifier of the stack.
in: path
name: stack_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
properties:
additionalResources:
items:
properties:
kind:
type: string
resourceID:
type: string
templateMetaName:
type: string
required:
- kind
- resourceID
type: object
type: array
description:
nullable: true
type: string
name:
nullable: true
type: string
templateURLs:
items:
type: string
nullable: true
type: array
title: PatchStackRequest
type: object
description: The stack to update.
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
description: Returns the updated stack.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Update a stack
tags:
- Templates
/api/v2/stacks/{stack_id}/uninstall:
post:
operationId: UninstallStack
parameters:
- description: The identifier of the stack.
in: path
name: stack_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Stack'
description: Returns the uninstalled stack.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Uninstall a stack
tags:
- Templates
/api/v2/templates/apply:
post:
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"
operationId: ApplyTemplate
requestBody:
content:
application/json:
examples:
skipKindAction:
summary: Skip all bucket and task resources in the provided templates
value:
actions:
- action: skipKind
properties:
kind: Bucket
- action: skipKind
properties:
kind: Task
orgID: INFLUX_ORG_ID
templates:
- contents:
- '[object Object]': null
skipResourceAction:
summary: Skip specific resources in the provided templates
value:
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
orgID: INFLUX_ORG_ID
templates:
- contents:
- apiVersion: influxdata.com/v2alpha1
kind: Bucket
metadata:
name: baz-500
templateObjectEnvRefs:
summary: envRefs for template objects
value:
envRefs:
docker-bucket: MY_DOCKER_BUCKET
docker-spec-1: MY_DOCKER_SPEC
linux-cpu-label: MY_CPU_LABEL
orgID: INFLUX_ORG_ID
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
schema:
$ref: '#/components/schemas/TemplateApply'
application/x-jsonnet:
schema:
$ref: '#/components/schemas/TemplateApply'
text/yml:
schema:
$ref: '#/components/schemas/TemplateApply'
description: 'Parameters for applying templates.
'
required: true
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateSummary'
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.
'
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/TemplateSummary'
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.
'
'422':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/TemplateSummary'
- properties:
code:
type: string
message:
type: string
required:
- message
- code
type: object
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.
'
'500':
content:
application/json:
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\""
schema:
$ref: '#/components/schemas/Error'
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"
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Apply or dry-run a template
tags:
- Templates
x-codeSamples:
- label: 'cURL: Dry run with a remote template'
lang: Shell
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"
- label: 'cURL: Apply with secret values'
lang: Shell
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"
- label: 'cURL: Apply template objects with environment references'
lang: Shell
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"
/api/v2/templates/export:
post:
operationId: ExportTemplate
requestBody:
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/TemplateExportByID'
- $ref: '#/components/schemas/TemplateExportByName'
description: Export resources as an InfluxDB template.
required: false
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Template'
application/x-yaml:
schema:
$ref: '#/components/schemas/Template'
description: The template was created successfully. Returns the newly created template.
default:
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
description: Unexpected error
summary: Export a new template
tags:
- Templates
components:
schemas:
AxisScale:
description: 'Scale is the axis formatting scale. Supported: "log", "linear"'
enum:
- log
- linear
type: string
NotificationEndpointType:
enum:
- slack
- pagerduty
- http
- telegram
type: string
SimpleTableViewProperties:
properties:
note:
type: string
queries:
items:
$ref: '#/components/schemas/DashboardQuery'
type: array
shape:
enum:
- chronograf-v2
type: string
showAll:
type: boolean
showNoteWhenEmpty:
description: If true, will display note when empty
type: boolean
type:
enum:
- simple-table
type: string
required:
- type
- showAll
- queries
- shape
- note
- showNoteWhenEmpty
type: object
TemplateEnvReferences:
items:
properties:
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
envRefKey:
description: Key identified as environment reference and is the key identified in the template
type: string
resourceField:
description: Field the environment reference corresponds too
type: string
value:
description: Value provided to fulfill reference
nullable: true
oneOf:
- type: string
- type: integer
- type: number
- type: boolean
required:
- resourceField
- envRefKey
type: object
type: array
HeatmapViewProperties:
properties:
adaptiveZoomHide:
type: boolean
binSize:
type: number
colors:
description: Colors define color encoding of data into a visualization
items:
type: string
type: array
generateXAxisTicks:
items:
type: string
type: array
generateYAxisTicks:
items:
type: string
type: array
legendColorizeRows:
type: boolean
legendHide:
type: boolean
legendOpacity:
format: float
type: number
legendOrientationThreshold:
type: integer
note:
type: string
queries:
items:
$ref: '#/components/schemas/DashboardQuery'
type: array
shape:
enum:
- chronograf-v2
type: string
showNoteWhenEmpty:
description: If true, will display note when empty
type: boolean
timeFormat:
type: string
type:
enum:
- heatmap
type: string
xAxisLabel:
type: string
xColumn:
type: string
xDomain:
items:
type: number
maxItems: 2
type: array
xPrefix:
type: string
xSuffix:
type: string
xTickStart:
format: float
type: number
xTickStep:
format: float
type: number
xTotalTicks:
type: integer
yAxisLabel:
type: string
yColumn:
type: string
yDomain:
items:
type: number
maxItems: 2
type: array
yPrefix:
type: string
ySuffix:
type: string
yTickStart:
format: float
type: number
yTickStep:
format: float
type: number
yTotalTicks:
type: integer
required:
- type
- queries
- colors
- shape
- note
- showNoteWhenEmpty
- xColumn
- yColumn
- xDomain
- yDomain
- xAxisLabel
- yAxisLabel
- xPrefix
- yPrefix
- xSuffix
- ySuffix
- binSize
type: object
Stack:
properties:
createdAt:
format: date-time
readOnly: true
type: string
events:
items:
properties:
description:
type: string
eventType:
type: string
name:
type: string
resources:
items:
properties:
apiVersion:
type: string
associations:
items:
properties:
kind:
$ref: '#/components/schemas/TemplateKind'
metaName:
type: string
type: object
type: array
kind:
$ref: '#/components/schemas/TemplateKind'
links:
properties:
self:
type: string
type: object
resourceID:
type: string
templateMetaName:
type: string
type: object
type: array
sources:
items:
type: string
type: array
updatedAt:
format: date-time
readOnly: true
type: string
urls:
items:
type: string
type: array
type: object
type: array
id:
type: string
orgID:
type: string
type: object
RetentionRule:
properties:
everySeconds:
default: 2592000
description: 'The duration in seconds for how long data will be kept in the database.
The default duration is 2592000 (30 days).
0 represents infinite retention.
'
example: 86400
format: int64
minimum: 0
type: integer
shardGroupDurationSeconds:
description: 'The shard group duration.
The duration or interval (in seconds) that each shard group covers.
#### InfluxDB Cloud
- Does not use `shardGroupDurationsSeconds`.
#### InfluxDB OSS
- Default value depends on the
[bucket retention period](https://docs.influxdata.com/influxdb/cloud/reference/internals/shards/#shard-group-duration).
'
format: int64
type: integer
type:
default: expire
enum:
- expire
type: string
required:
- everySeconds
type: object
DecimalPlaces:
description: Indicates whether decimal places should be enforced, and how many digits it should show.
properties:
digits:
description: The number of digits after decimal to display
format: int32
type: integer
isEnforced:
description: Indicates whether decimal point setting should be enforced
type: boolean
type: object
RenamableField:
description: Describes a field that can be renamed and made visible or invisible.
properties:
displayName:
description: The name that a field is renamed to by the user.
type: string
internalName:
description: The calculated name of a field.
readOnly: true
type: string
visible:
description: Indicates whether this field should be visible on the table.
type: boolean
type: object
LinePlusSingleStatProperties:
properties:
adaptiveZoomHide:
type: boolean
axes:
$ref: '#/components/schemas/Axes'
colors:
description: Colors define color encoding of data into a visualization
# --- truncated at 32 KB (115 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/influxdb/refs/heads/main/openapi/influxdb-templates-api-openapi.yml